跳转至

运行 doctor

运行 openclaw doctor 以修复并迁移 OpenClaw 安装。本页介绍该命令、其自动化标志以及只读 lint 模式。

当系统代理运行 Doctor 时，它会使用同一 OpenClaw 安装中的独立进程。这样，批量诊断检查就可以在不阻塞 Gateway 事件循环的情况下运行。这会使用现有的 --non-interactive 行为，包括其安全迁移；它不会启用额外修复。一旦启动，Doctor 会在被取消的调用方结束之前完成并释放其资源，因此取消操作不会放弃正在进行的迁移。

快速开始

openclaw doctor

无头与自动化模式

openclaw doctor --yes

无需提示即可接受默认的非服务修复，并在服务保留和安装漂移规则下进入维护。

openclaw doctor --fix

无需提示即可应用建议的非服务修复（--repair 是别名），并在服务保留和安装漂移规则下进入维护。

openclaw doctor --lint
openclaw doctor --lint --json

为 CI 或预检自动化运行结构化健康检查。只读：无提示、无修复、无迁移、无重启或状态写入。

openclaw doctor --fix --force

同时应用激进的配置/状态修复。修复维护使用相同的服务保留和安装漂移规则；从目标安装运行 openclaw gateway install --force 以替换其启动器和受管环境。

openclaw doctor --non-interactive

无提示运行，仅应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时仍会自动运行。添加 --fix 可在无提示的情况下执行所有受支持的启动阻塞修复，包括工作区设置、会话存储、exec 审批和审计架构迁移。显式修复会在数据库快照前检查所有权；另一个活动所有者必须先停止，修复才能继续。格式错误或冲突的保留文件需要错误中指定的手动恢复。

当共享数据库已是最新时，准备阶段会保留正在运行的 Gateway 的工作进程环境可用。实际的架构修复会在后续维护继续之前退役旧的数据库资源，包括修复清理失败时。

openclaw doctor --deep

扫描系统服务中额外的 gateway 安装（launchd/systemd/schtasks）。

设置 OPENCLAW_GATEWAY_STARTUP_TRACE=1 时，Doctor 会将各阶段计时（doctor.* 和 cli.bootstrap.* 行）输出到 stderr。

在写入前查看更改，请先打开配置文件：

cat ~/.openclaw/openclaw.json

只读 lint 模式

openclaw doctor --lint 是 openclaw doctor --fix 的自动化友好版本。它们共享相同的 Doctor 规则注册表，但它们选择或执行规则的方式不同：

模式 提示 写入配置/状态 输出 用途
openclaw doctor 是 是，安全迁移和已确认的修复 友好的健康报告 引导式检查和修复
openclaw doctor --json 否 否 JSON 建议报告 机器可读的运维检查
openclaw doctor --fix 有时 是，遵循修复策略 友好的修复日志 应用已批准的修复
openclaw doctor --lint 否 否 结构化发现 CI、预检和审查门禁

默认 doctor --lint 运行广泛安全的自动化配置文件：这些检查是静态的、本地的，并且适用于 CI 或预检输出。它会跳过需启用的检查，这些检查属于建议性、环境敏感、依赖实时服务、账户/工作区清单或历史清理。当你想要完整的已注册 lint 审计（包括这些需启用的检查）时，使用 doctor --lint --all；或针对特定检查使用 --only <id>。

doctor --fix 不使用 lint 默认配置文件，也不接受 --all。它运行 Doctor 的有序修复路径：现代健康检查可以提供可选的 repair() 实现，而旧区域仍使用其传统 Doctor 修复流程。一些 lint 发现仅用于诊断，因此出现在 --lint --all 中的检查并不意味着 --fix 会修改该区域。该契约将 detect()（报告发现）与 repair()（报告更改/差异/副作用）分开，这为未来的 doctor --fix --dry-run 保留了路径，而不会将 lint 检查变成变更规划器。

一些内置检查在内部默认禁用，以便它们仍可用于 --all、--only 和 Doctor 修复流程，而不会成为默认 doctor --lint 自动化配置文件的一部分。发现严重级别仍按每个发现输出（info、warning 或 error）；默认选择不是严重级别。

openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --only core/doctor/gateway-config --json

JSON 输出字段：

  • schemaVersion：机器可读 lint 信封的版本；在解析其他字段前应先基于此字段分支
  • ok：是否有发现达到所选严重级别阈值
  • checksRun / checksSkipped：计数（因配置文件、--only 或 --skip 跳过）
  • findings：结构化诊断，包含 checkId、severity、message，以及可选的 path、line、column、ocPath、source、target、requirement、fixHint

退出码：

代码 含义
0 没有达到或超过所选阈值的检测结果
1 一个或多个检测结果达到所选阈值
2 在能够输出检测结果之前发生命令/运行时故障

这些基于阈值的退出码属于显式 --lint 模式，无论是否带有 --json。单独的 openclaw doctor --json 在生成其载荷后保留普通 Doctor 的建议性退出码 0；机器消费者应读取 ok 和 findings。在输出之前的致命错误仍保持非零。

在 openclaw update 期间，无法删除 Doctor 的一次性 lint 快照会记录为更新警告，并且不会阻止更新。独立运行的 doctor --lint 仍会将该清理失败报告为错误。更新会保留检查的实际检测结果；清理警告不会掩盖其他失败。

标志：

  • --severity-min info|warning|error（默认 warning）：同时控制打印内容以及导致非零退出的内容。
  • --all：运行所有已注册的 lint 检查，包括被排除在默认自动化集合之外的可选启用检查。
  • --only <id>（可重复）：仅运行指定的检查 id；未知 id 会作为错误检测结果报告。
  • --skip <id>（可重复）：排除某个检查，同时保持其余运行处于活动状态。
  • --severity-min、--all、--only 和 --skip 需要 --lint。单独的 --json 可用于建议性机器可读报告；除非另一种机器模式控制输出，否则 --fix 会拒绝它。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw