openclaw doctor

运行全面的系统健康检查，诊断常见问题并提供自动修复建议。

命令签名

openclaw doctor [选项]

选项

选项	类型	说明
--fix	boolean	自动修复发现的问题
--check <name>	string	仅运行指定的检查项
--json	boolean	JSON 格式输出
--verbose	boolean	显示详细诊断信息

检查项目

openclaw doctor 会依次执行以下检查：

检查项	说明
node	Node.js 版本 ≥ 18
npm	npm 是否可用
disk	磁盘空间是否充足（≥ 500MB）
config	配置文件语法和必填项校验
ports	所需端口（18789、18790）是否可用
network	网络连接和 API 可达性
permissions	文件和目录权限检查
dependencies	依赖包完整性检查

输出格式

openclaw doctor

🩺 OpenClaw Doctor — 系统诊断

✔ Node.js         v20.11.0 (需要 ≥ 18)
✔ npm             v10.2.4
✔ 磁盘空间        45.2 GB 可用
✔ 配置文件        有效
✖ 端口 18789      被占用 (PID: 5678)
✔ 网络连接        API 可达
✔ 文件权限        正常
✔ 依赖包          完整

诊断结果：发现 1 个问题

  ✖ 端口 18789 已被进程 5678 占用
    → 运行 openclaw doctor --fix 自动解决
    → 或手动终止进程：kill 5678
    → 或修改端口：openclaw config set gateway.port 18800

自动修复

使用 --fix 标志自动尝试修复可修复的问题：

openclaw doctor --fix

可自动修复的问题包括：

• 创建缺失的目录
• 修正文件权限
• 重新安装损坏的依赖
• 生成缺失的配置文件

WARNING

--fix 不会终止占用端口的进程或修改系统级设置，这些需要手动处理。

仅运行特定检查

# 仅检查端口
openclaw doctor --check ports

# 仅检查配置
openclaw doctor --check config

常见问题

问题	原因	解决方案
Node.js 版本过低	安装了旧版本	升级到 Node.js 18+
配置文件无效	YAML 语法错误	运行 openclaw configure 重新配置
端口被占用	其他进程占用	修改端口或终止冲突进程
依赖不完整	安装中断	运行 npm install 重新安装

示例

# 运行完整诊断
openclaw doctor

# 自动修复
openclaw doctor --fix

# 详细输出
openclaw doctor --verbose

# JSON 格式（供脚本使用）
openclaw doctor --json

# 仅检查网络
openclaw doctor --check network

另请参阅

• openclaw health — 快速健康检查
• openclaw config — 配置管理
• openclaw configure — 交互式配置向导