跳转至

Lint 与升级后模式

Doctor 的只读姿态会生成发现项,而不更改配置或状态。 本页涵盖 lint 输出、检查选择以及升级后检查。

Lint 模式

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

显式 openclaw doctor --lint 是部署预检姿态。添加 --json 可获得机器可读输出,且不会改变 lint 基于阈值的退出码。此处报告的策略发现项记录在 openclaw policy 中。

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

只读报告会保留现有的 SQLite 数据库、WAL 和共享内存文件,包括它们的修改时间。较旧的共享状态架构会产生一个“待迁移”发现项,并附带 openclaw doctor --fix 指引;检查不会升级它。普通 Doctor 和显式修复保留其迁移行为。

Doctor 会在移除检查快照之前关闭私有数据库读取器和写入器。清理失败会保留已完成的发现项和检查计数;更新器运行会将临时文件移除失败报告为警告。如果数据库退役失败,Doctor 会报告错误并保留私有快照。

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

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 退出码:

代码 含义
0 没有达到或超过所选严重级别阈值的发现项。
1 至少一个发现项达到所选阈值。
2 健康检查完成前发生命令/运行时故障。

--severity-min 同时控制哪些发现项会打印以及退出阈值:openclaw doctor --lint --severity-min error 即使存在较低严重级别的 info/warning 发现项,也可能不打印任何内容并退出 0。

当更新器运行 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 下产生警告,要求为 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 以显示它。

检查选择

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 的 fleet。共享凭据问题只报告一次;特定于 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 针对相同的已挂载状态/配置运行一次同一镜像,然后再正常重启容器。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw