运行 doctor

本页介绍如何调用 openclaw doctor：支持的操作模式、可立即运行的示例，以及该命令可接受的所有选项。

如果插件在 Doctor 运行期间加载失败，报告会包含一个错误发现项，其中带有插件 ID、源路径和错误信息。ENOSPC 失败会指明磁盘空间原因。独立的 doctor --non-interactive 会针对这些失败以 1 退出，并报告 Doctor 已完成但存在插件加载错误。当更新程序调用 Doctor 时，同样的失败仍会作为已记录的警告保留，以便原本安全的更新可以继续；在解决报告的原因后，请重新运行 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 会保留较新的文件，不写入待定的配置修复，并以错误退出。请重新运行 openclaw doctor 以查看更新后的建议。

如果保存成功但后续处理失败，Doctor 会以错误停止，指出已写入的文件，并报告写入是否已回滚。如果写入未回滚或无法确认恢复，请在重新运行 Doctor 之前检查该文件和活动配置。

如果共享状态数据库使用了较新的 schema，Doctor 会在提供交互式更新之前拒绝操作，因为更新准入也需要该数据库。请从写入该状态的 OpenClaw 安装或其他兼容构建运行 Doctor。当代理数据库使用较新的 schema 时，可读的共享数据库仍允许进行交互式源更新；如果更新未接管，Doctor 会在诊断或修复之前再次检查所有数据库 schema。请参阅数据库 schema。

在执行审批格式升级后，Doctor 会报告那些不再生效的旧生成审批，因为它们未与工作目录绑定。openclaw doctor --fix 会移除这些非活动的生成条目，并保持手动允许列表规则不变。请重新运行受影响的流程，并选择始终在此处允许以重新建立对目标目录的信任。正常的 openclaw update 收尾操作会自动运行此安全修复。

显式修复会停止匹配的受管 Gateway，并在获取只读 schema 快照之前检查 Gateway、状态和代理数据库的所有权。修复期间会排除其他进程，然后重新启动同一服务一次并验证就绪状态。策略刷新会保留已安装的启动器和环境。另外，先前运行的服务中符合条件的安装漂移会通过原生安装程序进行协调。自动安装刷新仅涵盖与安装相关的漂移；其他操作员修改或不确定的检查仍需要交互式确认。维护前已确认为离线的服务会保留其启动器和停止状态；Linux 策略可以在不激活的情况下刷新，如下文所述。使用所报告的、可感知 profile 的 openclaw gateway install --force 命令来协调其安装漂移（安装可能会启动服务）。在 Linux 上，如果 systemd 在修复期间卸载了已停止的单元，Doctor 还会恢复先前正在运行的服务；但更改后的服务定义或管理器仍会阻止重启。在 macOS 上，一个已加载、已启用且处于重启间隔期的作业不算离线：Doctor 会在修复前将其停止，并在修复后恢复。请从 Gateway 进程树之外的 shell 运行修复。对于由外部监管或不匹配的安装，请通过其所属的监管程序停止和启动 Gateway。

在 Linux 维护停止之前，Doctor 会备份并刷新过时的 OpenClaw 单元策略，并确认 daemon-reload。操作员的 drop-in 文件保持不变。当前的服务停止策略为 330 秒。常驻 Gateway 可能仍然持有较旧、较短的关闭预算：2026.9.5 发布版在启动时缓存了该预算。对于较短或未报告的常驻预算，维护会要求 Gateway 阻止新的准入并排空现有工作，一旦其报告空闲即停止。等待过程使用更新现有的每步截止时间（默认 30 分钟）。到达该截止时间时，已准入的轮次可能会被中断并发出警告；已报告的写监护阶段（如会话变更或终端持久化）会拒绝停止，并指明其所属阶段。没有监护观测的较旧常驻进程会在截止时间停止，并发出警告，指明活动的根请求和 cron 运行；未知的监护并不构成拒绝。已确认离线的受管服务可以在不启动的情况下接收策略刷新。

在自动分诊期间，当模式和维护锁允许时，修复可以针对离线目标运行。如果修复需要停止受管的 Gateway，Doctor 会拒绝在其自动修复子树中执行该操作，因为停止会取消恢复。请使用只读诊断或安全的离线工件修复，然后执行原子性的 openclaw gateway restart，或请独立操作员在分诊之外的 shell 中运行 Doctor。

只读数据库快照和初始完整性扫描每个数据库有 30 秒的执行限制。超时会指明数据库名称，并要求你在重试之前停止其 Gateway 服务和其他 OpenClaw 进程。如果所有写入者都已停止，请检查存储性能和被报告的数据库；超时并不证明数据损坏。

openclaw doctor --fix --non-interactive 会无提示地应用阻止 Gateway 启动的受支持迁移，包括共享状态审计模式、旧版工作区设置、旧版会话存储和执行审批。格式错误或冲突的输入会被保留，并需要按诊断信息中的手动操作处理。更新程序在接受已安装目标之前会使用此修复路径。

更新时的 Doctor 会在可选检查之前运行启动所需的修复。在大型机群上，它可以推迟身份验证和模型诊断、插件检查、技能和工作区元数据、会话快照检查以及建议性 lint，以便为必要修复和更新验证预留时间。每个被推迟的检查都会以 update-inspection-deferred 警告的形式出现在 Doctor 输出和更新结果中，并附带原因和剩余的检查额度。被推迟的检查既未通过也未失败；它根本没有运行。

激活后运行 openclaw doctor --fix 以完成这些检查并审查可选修复。普通的 Doctor 运行不会保留更新的检查限额。必要的会话、数据库、工作区状态和执行审批就绪检查仍会在更新期间运行。项目克隆检查、SQLite 数据库大小建议以及工作区备份和内存建议保持其独立范围。

即使修复最终未发现任何更改，此维护窗口同样适用。没有使用 --fix、--repair 或 --yes 的运行不会进入维护。自定义状态目录仅限运行时使用，不会采用原生服务。

单独的 --force 不会选择修复模式：openclaw doctor --force 仍为引导模式，并且在符合条件的服务重写之前仍需要交互式同意。与 --fix、--repair 或 --yes 一起使用时，它允许进行激进的配置/状态修复，并遵循上述相同的安装漂移和 Linux 策略刷新规则。Force 不会绕过服务所有权、写入权限或仅限交互式确认的要求。

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/状态协调器、代理数据库租约以及旧版 Gateway（如 2026.6.33）使用的临时文件锁。活动或无法验证的旧版锁所有者会阻止修复，并指明其 PID 和锁路径；请通过其服务所有者停止该 Gateway，然后从独立 shell 运行 openclaw doctor --fix。仍可运行的不匹配服务也会阻止维护；使用 openclaw gateway status --deep 检查它。一旦原生管理器确认其处于离线状态，Doctor 就可以修复其选定的状态，而无需更改或启动该服务。已停止或禁用的 systemd 单元无需在管理器保持加载状态即可进行状态修复。

如果迁移或配置修复无法完成，Doctor 会让已停止的服务保持停止状态，并以退出码 1 报告不完整的修复。当状态需要手动恢复时，诊断信息会指明其路径和下一步操作：

不支持的规范工作区版本： 使用支持该版本的 OpenClaw 构建。保持共享数据库不变。
无法读取或冲突的执行策略： 停止 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`	生成并配置 Gateway 令牌。
`--allow-exec`	允许 doctor 在验证密钥时执行已配置的 `exec` SecretRefs。
`--deep`	扫描系统服务以查找额外的 Gateway 安装；报告最近的 Gateway 监督进程重启交接。
`--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