运行 doctor
This page covers how to invoke openclaw doctor: the supported postures, ready-to-run
examples, and every option the command accepts.
如果在 Doctor 期间插件加载失败,报告会包含一条错误发现,其中包含插件 ID、源路径和错误。ENOSPC 失败会指明磁盘空间原因。独立运行的 doctor --non-interactive 遇到这些失败时会以 1 退出,并报告 Doctor 因插件加载错误而结束。当更新程序调用 Doctor 时,这些失败仍会作为已记录的警告保留,以便原本安全的更新可以继续;在解决所报告的原因后,重新运行 Doctor。
CLI 在退出前会排空其共享状态数据库工作进程。脚本调用方仍必须检查进程退出状态:Doctor complete. 记录检查已完成,但随后发生的崩溃在更新期间仍属于失败的候选 Doctor 步骤。
模式¶
Doctor 支持这些运行模式:
| 模式 | 命令 | 行为 |
|---|---|---|
| 引导式检查 | openclaw doctor |
交互式健康检查流程;可复制旧配置并应用自动状态迁移。 |
| 建议型 JSON | openclaw doctor --json |
只读发现;生成报告后成功退出。 |
| 修复 | openclaw doctor --fix |
应用受支持的修复;除非非交互式修复是安全的,否则使用提示。 |
| Lint | openclaw doctor --lint [--json] |
只读发现,并带有基于阈值的退出码,用于 CI 门禁。 |
| 共享 SQLite 维护 | openclaw doctor --state-sqlite compact |
显式创建检查点、压缩并验证规范共享状态数据库。 |
| 会话 SQLite 工具 | openclaw doctor --session-sqlite <mode> |
检查或维护 SQLite 会话,并显式导入旧历史记录。 |
当操作员或脚本希望以 JSON 形式获取建议型 Doctor 报告时,使用 openclaw doctor --json。它在生成报告后成功退出;检查 ok 和 findings 以了解健康状态。当 CI 应在所选严重级别阈值下对发现以非零退出码退出时,使用显式的 openclaw doctor --lint --json。当人工操作员希望 Doctor 编辑配置或状态时,优先使用 --fix。
对于只读诊断,使用 --lint 或单独的 --json。普通 doctor(包括 doctor --non-interactive)即使没有 --fix,也可以复制旧配置并迁移状态。--non-interactive 抑制的是提示,而不是写入操作。
交互式 doctor 首先检查共享模式兼容性,并可提供源更新。如果更新未接管,Doctor 会在询问暂停匹配的受管 Gateway 以让你审查修复之前,检查所有数据库模式。接受后会接管维护权限,保留各个修复提示,并在数据库句柄关闭后恢复服务先前状态。拒绝会跳过修复,并在同一次调用中继续执行只读 --lint 检查,不更改服务或持久化状态,也不请求修复批准。如果报告发现警告或错误,则退出 1,否则退出 0。已有的 --deep 和 --allow-exec 选择仍然适用。外部监督或不匹配的 Gateway 仍受其现有维护所有权检查约束。
当普通 doctor 询问 是否立即应用推荐的配置修复? 时,它会检查所选根配置文件是否仍与该建议的来源匹配。如果在写入前其内容或所选路径已更改,Doctor 会保留较新的文件,不写入待处理的配置修复,并以错误退出。重新运行 openclaw doctor 以查看更新后的建议。
如果保存成功但后续处理失败,Doctor 会以错误停止,指明已写入的文件,并报告写入是否已回滚。如果未回滚或无法确认恢复,请在重新运行 Doctor 之前检查该文件和当前活动配置。
如果共享状态数据库使用较新的模式,Doctor 会在提供交互式更新之前拒绝,因为更新准入也需要该数据库。请从写入该状态的 OpenClaw 安装或另一个兼容构建中运行 Doctor。当代理数据库使用较新模式时,可读的共享数据库仍允许交互式源更新;如果更新未接管,Doctor 会在诊断或修复之前再次检查所有数据库模式。参见 数据库模式。
在执行审批格式升级后,Doctor 会报告较旧的已生成审批,这些审批因未绑定到工作目录而不再有效。openclaw doctor --fix 会移除这些非活动的已生成条目,并保持手动允许列表规则不变。重新运行受影响的工作流,并选择 始终在此处允许 以更新对目标目录的信任。正常的 openclaw update 最终处理会自动运行此安全修复。
显式修复会停止匹配的受管 Gateway,并在获取只读模式快照之前检查 Gateway、状态和代理数据库的所有权。修复期间它会排除其他进程,然后重启同一服务一次并验证就绪状态。策略刷新会保留已安装的启动器和环境。另外,先前运行中的服务中符合条件的安装漂移会通过原生安装程序进行协调。自动安装刷新仅覆盖仅安装相关的漂移;其他操作员编辑或不确定的检查仍需要交互式确认。在维护前确认离线的服务会保留其启动器和停止状态;Linux 策略可以如下所述在不激活的情况下刷新。使用报告的感知配置文件的 openclaw gateway install --force 命令来协调它们的安装漂移(安装可能会启动服务)。在 Linux 上,如果 systemd 在修复期间卸载已停止的单元,Doctor 还会恢复先前运行的服务;已更改的服务定义或管理器仍会阻止重启。在两次重启之间已加载且启用的 macOS 作业并非离线:Doctor 会在修复前停止它,并在之后恢复它。请在 Gateway 进程树之外的 shell 中运行修复。对于外部监督或不匹配的安装,请通过其所属监督程序停止并启动 Gateway。
在 Linux 维护停机之前,Doctor 会备份并刷新过时的 OpenClaw 单元策略,并确认 daemon-reload。Operator 覆盖项保持不变。
当前服务停止策略为 330 秒。常驻 Gateway 仍可能具有较旧、较短的关闭预算:2026.9.5 版本在启动时缓存了该预算。
对于较短或未报告的常驻预算,维护会要求 Gateway 阻止新准入并排空现有工作,一旦其报告空闲即停止。
等待使用更新现有的每步截止时间(默认 30 分钟)。
到达该截止时间时,已准入的回合可能被警告中断;已报告的写托管阶段(例如会话变更或终端持久化)会拒绝停止并指明其所有者阶段。没有托管观察的旧常驻实例会在截止时间停止,并附带警告,指明活动的根请求和 cron 运行;未知托管不构成拒绝。已确认离线的受管服务可以在不启动的情况下接收策略刷新。
在自动分诊期间,当架构和维护锁允许时,修复可以针对离线目标运行。如果修复需要停止受管 Gateway,Doctor 会在其自动修复子树中拒绝,因为该停止会取消恢复。请使用只读诊断或安全的离线工件修复,随后执行原子的 openclaw gateway restart,或者要求独立操作员在分诊之外的 shell 中运行 Doctor。
只读数据库快照和初始完整性扫描对每个数据库有 30 秒执行限制。超时会指明数据库,并要求在重试前停止其 Gateway 服务和其他 OpenClaw 进程。如果所有写入者已停止,请检查存储性能和所报告的数据库;超时并不证明损坏。
openclaw doctor --fix --non-interactive 会应用阻止 Gateway 启动的受支持迁移,且不会提示,包括共享状态审计架构、旧版工作区设置、旧版会话存储和 exec 审批。格式错误或冲突的输入会被保留,并需要诊断中的手动操作。更新器在接受已安装目标之前使用此修复路径。
更新期间的 Doctor 会在可选检查之前运行启动所需修复。当已安装更新器支持重启后检查时,Doctor 会将基于 lint 的、仅检查类检查移出已停止 Gateway 窗口。更新器在重启后运行它们,并将其发现保存在 post-activation doctor inspections 结果步骤中。发现或不完整的检查仍为建议性,不会使原本成功的更新失败。修复、迁移、就绪门控以及没有等效 lint 覆盖的检查保持其现有顺序。较旧的已安装更新器将检查保留在其原始 Doctor 遍次中。
在大型机群上,它可以推迟身份验证和模型诊断、插件检查、技能和工作区元数据、会话快照检查以及建议性 lint,以为必需修复和更新验证预留时间。每个推迟的检查都会作为 update-inspection-deferred 警告出现在 Doctor 输出和更新结果中,并附带原因和剩余检查额度。推迟的检查既未通过也未失败;它未被运行。
激活后运行 openclaw doctor --fix 以完成这些检查并审查可选修复。普通 Doctor 运行不会保留更新的检查限制。必需的会话、数据库、工作区状态和 exec 审批就绪检查仍会在更新期间运行。项目克隆检查、SQLite 数据库大小建议以及工作区备份和内存建议保留其独立范围。
即使修复最终未发现变更,此维护窗口也适用。不带 --fix、--repair 或 --yes 的非交互式运行不会进入维护。普通交互式运行仅在获得托管同意后进入。自定义状态目录仍仅为运行时使用,不会采用原生服务。
单独的 --force 不会选择修复模式:openclaw doctor --force 仍为引导式,并且在符合条件的服务重写之前仍需要交互式同意。使用 --fix、--repair 或 --yes 时,它允许激进的配置/状态修复,并遵循上述相同的安装漂移和 Linux 策略刷新规则。强制不会绕过服务所有权、写访问或仅限交互式的确认要求。
Warning
doctor --fix 会遵循显式配置的工作区和存储路径,包括 OPENCLAW_STATE_DIR 之外的路径。将 OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_PATH 设置为副本不会重定向这些路径。在复制的状态上预演修复之前,也请复制外部工作区和存储,然后在复制的配置中重写其路径以指向副本。否则,Doctor 可能会修改原始状态。
更新期间,Doctor 会遵循更新器的服务激活策略。如果正在运行的 Gateway 具有旧版本/构建,或在包替换后无法加载其 WebSocket 处理程序,Doctor 会通过已验证的服务管理器停止该过期实例,并确认其进程和监听器已消失。它在运行离线修复(包括旧版会话导入)期间保留服务托管,然后重启服务并通过 RPC 验证候选版本的版本和构建 ID。启动可能需要这些导入,因此候选就绪状态在维护后检查。警告会指明被替换的 PID 和已验证的服务构建。仅 HTTP 健康检查不能证明恢复。被拒绝的停止或未验证的恢复会在更新结果中记录失败阶段和确切恢复命令。
旧版核心后收敛在其新的 Doctor 进程运行期间保留服务维护托管,然后在发布完成前恢复 Gateway。普通健康 Gateway 仍遵循父级的激活策略;openclaw update --no-restart 不会授予活动写入者状态修复访问权限。
不可用的服务检查会变为警告,并且不授予服务控制权限。Doctor 仍会在修复前检查 Gateway/状态协调器、agent 数据库租约以及旧版 Gateway(例如 2026.6.33)使用的临时文件锁。活动或无法验证的旧版锁所有者会阻止修复,并指明其 PID 和锁路径;请通过其服务所有者停止该 Gateway,然后从独立 shell 运行 openclaw doctor --fix。仍可运行的未匹配服务也会阻止维护;请使用 openclaw gateway status --deep 检查它。一旦原生管理器确认其离线,Doctor 就可以在不更改或启动该服务的情况下修复其选定状态。已停止或禁用的 systemd 单元无需在管理器中保持加载,状态修复即可继续。
如果迁移或配置修复无法完成,Doctor 会保持已停止的服务 处于停止状态,并以退出代码 1 报告不完整的修复。当状态需要 手动恢复时,诊断会指明其路径和下一步操作:
- 不支持的规范工作区版本: 使用支持该版本的 OpenClaw 构建。保持共享数据库不变。
- 无法读取或冲突的 exec 策略: 停止 Gateway 和节点主机, 然后将指定的遗留文件或中断的声明与预期策略的已验证副本进行协调。保留现有 SQLite 策略。
Doctor 不会隔离不支持的工作区状态、丢弃未来版本 行,或推断执行策略。重复相同的修复调用无法 解决这些情况。手动恢复后,在通过其所有者启动服务之前, 请验证就绪状态。
示例¶
openclaw doctor
openclaw doctor --lint
openclaw doctor --json
openclaw doctor --lint --json
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --all
openclaw doctor --lint --allow-exec
openclaw doctor --deep
openclaw doctor --fix
openclaw doctor --fix --non-interactive
openclaw doctor --generate-gateway-token
openclaw doctor --post-upgrade
openclaw doctor --post-upgrade --json
openclaw doctor --state-sqlite compact
openclaw doctor --state-sqlite compact --json
openclaw doctor --session-sqlite inspect --session-sqlite-all-agents
openclaw doctor --session-sqlite dry-run --session-sqlite-agent main --json
openclaw doctor --session-sqlite import --session-sqlite-all-agents
openclaw doctor --session-sqlite validate --session-sqlite-all-agents --json
openclaw doctor --session-sqlite compact --session-sqlite-all-agents
openclaw doctor --session-sqlite recover --github-issue
openclaw doctor --session-sqlite restore --session-sqlite-all-agents
对于特定渠道的权限,请使用渠道检查而不是 doctor:
openclaw channels capabilities --channel discord --target channel:<channel-id>
openclaw channels status --probe
channels capabilities 报告机器人针对特定渠道目标的有效权限。channels status --probe 审计所有已配置的渠道和语音自动加入目标。
选项¶
| 选项 | 效果 |
|---|---|
--no-workspace-suggestions |
禁用工作区记忆/搜索建议。 |
--yes |
接受默认值,并在不提示的情况下进入修复维护。 |
--repair / --fix |
应用建议的修复,同时与匹配的受管 Gateway 协调维护(--fix 是别名)。刷新过时的 Linux 策略,并协调符合条件的运行中服务安装漂移;保留已停止的启动器和停止状态。 |
--force |
允许激进的修复选项。单独使用时仍保持引导式;与 --fix、--repair 或 --yes 一起使用时,使用相同的策略刷新和安装漂移规则。 |
--non-interactive |
无提示运行;安全的自动迁移仍会应用。与 --fix、--repair 或 --yes 组合使用以进入修复维护。 |
--generate-gateway-token |
生成并配置网关 token。 |
--allow-exec |
允许 doctor 在验证密钥时执行已配置的 exec SecretRefs。 |
--deep |
扫描系统服务以查找额外的 gateway 安装;报告最近的 Gateway supervisor 重启交接。 |
--lint |
以只读模式运行 结构化健康检查 并输出诊断结果。 |
--post-upgrade |
运行升级后的插件兼容性检查;结果输出到 stdout;如果存在任何错误级别的结果,则退出代码为 1。 |
--state-sqlite <mode> |
运行显式的共享状态 SQLite 维护。唯一模式是 compact。 |
--session-sqlite <mode> |
运行目标会话 SQLite 维护或遗留导入:inspect、dry-run、import、validate、compact、recover 或 restore。 |
| 选项 | 效果 |
|---|---|
--session-sqlite-store <path> |
配合 --session-sqlite:选择 SQLite 数据库或旧版 sessions.json 源,具体遵循该模式的选择规则。 |
--session-sqlite-agent <id> |
配合 --session-sqlite:选择一个已配置的 agent。 |
--session-sqlite-all-agents |
配合 --session-sqlite:选择已配置和已发现的 agent 存储。 |
--github-issue |
配合 --session-sqlite recover:准备一份已脱敏的 openclaw/openclaw 问题报告;doctor 会在 --yes 或交互式确认后使用 gh 创建它。 |
--json |
输出只读 JSON。单独的 --json 仅为建议性;与 --lint 组合使用可获得基于阈值的退出码。与其他机器模式一起使用时,输出该模式已有的 JSON 报告。 |
--severity-min <level> |
配合 --lint:丢弃低于 info、warning 或 error 的发现。 |
--all |
配合 --lint:运行所有已注册的检查,包括默认集合中排除的可选检查。 |
--skip <id> |
配合 --lint:跳过某个检查 id。可重复使用。 |
--only <id> |
配合 --lint:仅运行给定的检查 id。可重复使用。 |
--severity-min、--all、--only 和 --skip 仅在与 --lint 一起使用时才被接受。单独的 --json 使用默认的只读 lint 检查选择,但保留 Doctor 的建议性退出行为。两种只读模式均拒绝 --repair、--fix、--force、--yes 和 --generate-gateway-token。显式 --lint 还会拒绝 --session-sqlite 模式及其选择器,包括 --github-issue。其他机器模式仍可使用 --json 生成其自身的输出。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw