运行 doctor
运行 openclaw doctor 以修复并迁移 OpenClaw 安装。本页介绍该命令、其自动化标志以及只读 lint 模式。
当 System agent 运行 Doctor 时,它会使用来自同一 OpenClaw 安装的独立进程。这样,批量诊断检查就可以在不阻塞 Gateway 事件循环的情况下运行。这使用现有的 --non-interactive 行为,包括其安全迁移;它不会启用额外修复。一旦启动,Doctor 会在被取消的调用方结束之前完成并释放其资源,因此取消不会放弃正在进行的迁移。
快速开始¶
无头与自动化模式¶
在不提示的情况下接受默认的非服务修复,并在服务保留和安装漂移规则下进入维护。
在不提示的情况下应用推荐的非服务修复(--repair 是别名),并在服务保留和安装漂移规则下进入维护。
同时应用激进的配置/状态修复。修复维护使用相同的服务保留和安装漂移规则;从目标安装运行 openclaw gateway install --force 以替换其启动器和受管环境。
无提示运行,仅应用安全迁移(配置规范化 + 磁盘状态移动)。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时仍会自动运行。添加 --fix 可在无提示的情况下执行所有受支持的启动阻塞修复,包括工作区设置、会话存储、exec 审批和审计架构迁移。显式修复在数据库快照前检查所有权;另一个活动所有者必须先停止,修复才能继续。格式错误或冲突的保留文件需要错误中指定的手动恢复。
当共享数据库已是最新时,准备阶段会保持正在运行的 Gateway 的工作者环境可用。实际的架构修复会在后续维护继续之前退役旧的数据库资源,即使修复清理失败也是如此。
如果插件因为其源捕获耗尽磁盘空间而无法加载,Doctor 会报告 ENOSPC 及底层文件系统错误。释放受影响文件系统的空间并重新运行 Doctor。独立的 --non-interactive Doctor 以退出代码 1 结束;由更新调用的 Doctor 会将问题记录为警告,以便更新可以继续,同时保持诊断可见。
当设置 OPENCLAW_GATEWAY_STARTUP_TRACE=1 时,Doctor 会将各阶段计时(doctor.* 和 cli.bootstrap.* 行)打印到 stderr。
要在写入前审查更改,请先打开配置文件:
只读 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