Lint 与升级后模式

Doctor 的只读模式会产生发现结果，而不会更改配置或状态。 本页介绍了 lint 输出、检查选择以及升级后的探测。

Lint 模式¶

仅运行 openclaw doctor --json 是只读且非交互式的：不提示、不修复，也不重写配置/状态。它与 lint 模式发出相同的默认发现结果，但在生成报告后以 0 退出，因此输出格式不会改变普通 Doctor 的建议性成功契约。读取负载中的 ok 和 findings 字段以判断健康状态。

显式的 openclaw doctor --lint 是部署预检模式。添加 --json 可获取机器可读输出，而不会改变 lint 基于阈值的退出码。此处报告的策略发现结果已在 openclaw policy 中记录。

完整报告在报告内部进行普通读取时复用私有共享状态快照，从而保留实时数据库及其 WAL 文件。每个新报告都会读取一个新快照。需要可写检查状态或独立数据库验证的检查会保留自己的副本；--only 检查会按需准备状态。

Doctor 会在移除检查快照之前停用私有数据库读取器和写入器。清理失败会保留已完成的发现结果和检查计数；更新程序运行时会报告临时文件移除失败作为警告。如果数据库停用失败，Doctor 会报告错误并保留私有快照。

插件源捕获使用原始配置文件的临时存储，位于这些数据库快照之外。它们的插件缓存所有者会保留它们，直到插件检查完成，因此后续通道设置检查可以安全地复用已认可的原生文件。

openclaw doctor --json
openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --allow-exec
openclaw doctor --lint --only core/doctor/gateway-config --json
openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info
openclaw doctor --lint --only memory-core/managed-local-embedding-setup --severity-min error --json

托管本地嵌入设置检查是一个作用域受限、非变异的切换前门禁，用于已有语义索引。它通过 --only 或 --all 选择启用，因此普通 doctor --lint 行为保持不变。它报告缺失的 llama.cpp 设置以及交互式 models auth login 修复措施，而不声称完全具备 Gateway 就绪性、不启动服务、不下载模型，也不更改配置。

人类可读输出很简洁：

doctor --lint: ran 6 check(s), 1 finding(s)
  [warning] core/doctor/gateway-config gateway.mode - gateway.mode is unset; gateway start will be blocked.
    fix: Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`.

JSON 输出是脚本接口：

{
  "schemaVersion": 1,
  "ok": false,
  "checksRun": 5,
  "checksSkipped": 0,
  "findings": [
    {
      "checkId": "core/doctor/gateway-config",
      "severity": "warning",
      "message": "gateway.mode is unset; gateway start will be blocked.",
      "path": "gateway.mode",
      "fixHint": "Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`."
    }
  ]
}

显式 lint 退出码：

--severity-min 同时控制打印哪些发现结果以及退出阈值：openclaw doctor --lint --severity-min error 可能什么都不打印并以 0 退出，即使存在较低严重性的 info/warning 发现结果。

当更新程序运行 lint 时，低于其错误阈值的警告级发现结果会保留在单独的 JSON warnings 数组中。它们不会改变 lint 退出码。更新程序会将这些建议记录在其运行历史中，包括有意开放的通道策略，因此它们仍可在 openclaw update status 中查看。普通的独立 lint 会保持所选输出阈值。

如果调用方在检查开始前取消状态租约获取，Doctor 会记录一条信息性诊断，包含 errorCode: OPENCLAW_STATE_LEASE_ABORTED、已用时间以及调用方的信号作为原因。当低于所选阈值时，该诊断会出现在 JSON warnings 和人类可读输出中，而不会导致 lint 失败。它表示检查未执行。获取后取消以及其他检查失败仍然属于错误。

在更新期间，可选检查与策略建议均作为警告处理，包括有意开放的 DM 策略。必需的配置、状态和启动检查仍保持阻塞性。保存的报告会保留每一项发现结果，并附有单独限定的原因；更新历史会保留严重性计数、决定性错误，并在达到其诊断上限时保留显式的省略计数。

安全发现结果会在更新报告中保留其特定的检查标识符和修复措施。密钥迁移命令出现在较长的字段列表之前，以便有界诊断保留 openclaw secrets configure 和 openclaw secrets apply 后续步骤。

PLAINTEXT_FOUND、REF_SHADOWED 和 LEGACY_RESIDUE 是来自单独的 openclaw secrets audit 命令的发现结果。它们描述的是加固或保留的恢复材料，而不是数据库损坏。单独的 secrets audit --check 可能因这些发现结果而以非零状态退出；仅凭该结果并不能识别出失败的候选 Doctor 检查。请使用候选者记录的 lint 发现结果，而不是截断的 stderr 尾部，来识别更新失败。

如果配置的 Codex 插件缺失，或其宣称的健康 API 无法验证，则会在 core/doctor/codex-session-routes 下产生一个可用性警告，其中包含插件名称和修复命令。不受信任的安装不会被导入以检查其健康 API。

更新程序的 --severity-min error 运行会针对这些警告以 0 退出，采用与 Gateway 启动相同的警告策略。无效配置、不安全的状态检查以及实际健康检查报告的错误仍会保留其失败状态。缺少已配置的 plugins.load.paths 会在 core/doctor/final-config-validation 下产生一个警告，其中 requirement 为 configured-plugin-path-unavailable，并在 source 中包含不可用的路径。权限、I/O 和其他检查失败则改用 configured-plugin-path-inspection-failed，保留文件系统的 errorCode 和错误消息，并为受影响路径提供恢复提示。更新程序会保留该警告并继续执行。Doctor 会保留无法检查其插件所有者的设置；参见 插件修复警告。

仅运行 openclaw doctor --json 时，只要它输出了发现项载荷，退出码就是 0，即使 ok 为 false 也是如此。参数错误仍会返回非零退出码。如果 lint 运行器在生成报告之前失败，Doctor 会退出 2，并输出一个经过脱敏的 JSON 文档，其中包含 ok: false、checksRun: 0，以及在 core/doctor/lint-inspection 下的一个错误发现项。它会为现有消费者保留 error: { type: "cli_error", message } 字段。这种就绪状态形状可被已发布的更新器接受，包括 2026.9.5，而不会将检查失败视为成功的检查。

--all 控制在进行严重级别过滤之前选择哪些检查。默认 lint 运行会排除那些深入的、历史性的，或更可能暴露可修复遗留残留的检查；使用 --all 可获取完整清单。--only <id> 是最精确的选择器，可以通过 id 运行任何已注册的检查。

core/doctor/session-snapshots 会将保留的遗留会话元数据中的过期路径报告为信息性发现项。即使在 --fix 下，它也会保留原始文件；活动会话使用规范的 SQLite 状态和当前运行时技能目录。历史快照路径不需要清理或会话重置。

core/doctor/local-audio-acceleration 会报告自动选择的本地 STT 命令、分别的 capable/requested/observed 后端证据，以及回退顺序，而不会加载语音模型。它会输出一个信息性发现项，因此请包含 --severity-min info 以显示它。

core/doctor/skill-workshop-relocation 会区分待处理的遗留集合备份根目录和为审查而保留的根目录。符合条件的提案或备份根目录会收到 openclaw doctor --fix 指引，而不是保证所有备份都会被退役。保留的根目录需要人工审查工作区所有权、备份清单以及工作区迁移阻塞项。如果两类根目录仍然存在，Doctor 会报告两个后续步骤。不要删除保留的备份以清除警告。 该检查会使用已配置的 agent 目录和实际文件系统路径，即使 lint 读取的是私有状态快照。正确放置的 Workshop 目标不需要仅仅因为 lint 使用临时目录而重新定位。

检查选择¶

openclaw doctor --lint --only core/doctor/gateway-config --json
openclaw doctor --lint --skip core/doctor/skills-readiness

--only 和 --skip 接受完整的检查 id，并且可以重复使用。未注册的 --only id 会输出一个 core/doctor/lint-selection 错误发现项；有效选中的检查仍会运行。使用输出中的 checksRun/checksSkipped 来确认聚焦门禁选择了你预期的检查。

要检查模型凭据，请运行 openclaw doctor --lint --only core/doctor/auth-profiles --json。 此需显式启用的检查会检查共享凭据以及每个已配置 agent 的本地 auth store，包括没有默认 agent 的 fleets。共享凭据问题只报告一次；特定于 agent 的冷却期仍归属于其本地存储。

core/doctor/runtime-tool-schemas 不会在只读 Doctor 报告中探测基于 OAuth 的 MCP 服务器，包括分诊和更新检查。即使本地状态写入指向一次性快照，探测也可能在外部服务器上轮换 refresh token。Doctor 会以信息性严重级别报告此延迟；使用 --severity-min info 可显示它。对于 mcp.servers 中的服务器，请针对服务配置运行 openclaw mcp probe <name>。从已认证的服务 agent 回合中验证插件提供的服务器或 agent 本地 auth profiles，以便刷新后的凭据与其所有者一起持久化。非 OAuth MCP 架构检查仍会运行。

升级后模式¶

openclaw doctor --post-upgrade 会运行插件兼容性探测，以便在构建或升级后进行链式处理。发现项会输出到 stdout；如果任何发现项的 level: "error"，退出码为 1。添加 --json 可获得机器可读的信封（{ probesRun, findings }），适用于 CI、社区 fork-upgrade 技能以及其他升级后冒烟测试工具。如果已安装的插件索引缺失或格式错误，JSON 模式仍会输出信封，并附带一个 plugin.index_unavailable 错误发现项。

当已安装索引中某个已启用的官方插件属于与升级后的 OpenClaw CLI 不同的发布批次时，这些探测还会以 plugin.version_drift 发出警告。请按照报告的插件更新命令操作，然后重启 Gateway。精确的 npm 固定版本只有在注册表确认目标存在后，才会收到更新命令。独立版本管理的社区插件和已禁用的插件会被排除；仅版本漂移不会改变退出码。

容器镜像启动是通常“更新后运行 doctor”流程的例外。当 openclaw gateway run 在新 OpenClaw 版本上启动时，它会在报告就绪之前运行安全的状态和插件修复。如果修复无法安全完成，启动会退出，并提示你先使用 openclaw doctor --fix 针对相同的已挂载状态/配置运行一次同一镜像，然后再正常重启容器。