跳转至

运行 doctor

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

当 System agent 运行 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)。

如果插件因为其源捕获耗尽磁盘空间而无法加载,Doctor 会报告 ENOSPC 及底层文件系统错误。释放受影响文件系统的空间并重新运行 Doctor。独立的 --non-interactive Doctor 以退出代码 1 结束;由更新调用的 Doctor 会将问题记录为警告,以便更新可以继续,同时保持诊断可见。

当设置 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:计数(因 profile、--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