openclaw doctor 是 OpenClaw 内置的健康检查与修复工具，可检测 Gateway、渠道、插件、技能、模型路由、配置迁移等异常并引导修复。运行 openclaw doctor 查看诊断，加 --fix 自动修复（备份 ~/.openclaw/openclaw.json.bak），加 --lint 只读检查（支持 JSON 输出和严重级别过滤）。修复前会备份配置文件，Nix 模式下只读检查可用但修复操作禁用。

openclaw doctor 健康检查与自动修复命令参考

Gateway 和渠道的健康检查 + 快速修复工具。

相关文档：

• 故障排查：Troubleshooting
• 安全审计：Security

为什么要用 doctor

openclaw doctor 是 OpenClaw 的健康状态面板。当 Gateway、渠道、插件、技能、模型路由、本地状态或配置迁移表现异常，且希望用一个命令解释问题所在时，使用它。

doctor 有三种运行姿态：

姿态	命令	行为
检查	openclaw doctor	面向人的检查与引导式提示。
修复	openclaw doctor --fix	执行支持的修复，除非非交互式修复安全，否则使用提示。
检查	openclaw doctor --lint	只读的结构化检查结果，适用于 CI、预检和审核门禁。

自动化场景优先用 --lint，当操作员有意让 doctor 编辑配置或状态时用 --fix。

示例

openclaw doctor
openclaw doctor --lint
openclaw doctor --lint --json
openclaw doctor --lint --severity-min warning
openclaw doctor --deep
openclaw doctor --fix
openclaw doctor --fix --non-interactive
openclaw doctor --generate-gateway-token

渠道级别的权限检查使用渠道探测工具而非 doctor：

openclaw channels capabilities --channel discord --target channel:<channel-id>
openclaw channels status --probe

Discord 能力探测会报告机器人有效的渠道权限；状态探测会审计已配置的 Discord 渠道和语音自动加入目标。

选项

• --no-workspace-suggestions：禁用工作区内存/搜索建议
• --yes：接受所有默认值而不提示
• --repair：应用推荐的非服务修复而不提示；Gateway 服务安装和重写仍需交互确认或显式 gateway 命令
• --fix：--repair 的别名
• --force：应用激进修复，包括在必要时覆盖自定义服务配置
• --non-interactive：无提示运行；仅执行安全迁移和非服务修复
• --generate-gateway-token：生成并配置一个 Gateway token
• --deep：扫描系统服务中的额外 Gateway 安装，并报告最近的 Gateway supervisor 重启切换记录
• --lint：以只读模式运行优化后的健康检查，输出诊断结果
• --json：与 --lint 配合，输出 JSON 格式结果而非人类可读文本
• --severity-min <level>：与 --lint 配合，忽略低于 info、warning 或 error 级别的检查结果
• --skip <id>：与 --lint 配合，跳过指定检查 ID；可重复使用以跳过多个
• --only <id>：与 --lint 配合，仅运行指定检查 ID；可重复使用以运行小范围选定项

lint 模式

openclaw doctor --lint 是 doctor 的只读自动化姿态。它使用结构化健康检查路径，不提示、不修复、不重写配置/状态。适用于 CI、预检脚本和审核工作流，需要机器可读的输出而非引导式修复提示。--json、--severity-min、--only 和 --skip 等 lint 输出选项仅在 --lint 下生效。

openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --only core/doctor/gateway-config --json

人类可读输出精简：

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 输出是 lint 运行的脚本接口：

{
  "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`."
    }
  ]
}

退出行为：

• 0：在所选严重级别阈值上没有发现结果
• 1：至少有一个发现结果达到所选阈值
• 2：命令/运行时失败，无法产生 lint 结果

--severity-min 同时控制可见结果和退出阈值。例如，openclaw doctor --lint --severity-min error 可能打印无结果并退出 0，即使存在更低级别的 info 或 warning 发现结果。

结构化健康检查

现代 doctor 检查使用一个小型结构化约定：

detect(ctx, scope?) -> HealthFinding[]
repair?(ctx, findings) -> HealthRepairResult

detect() 为 doctor --lint 提供数据。repair() 是可选的，仅由 doctor --fix / doctor --repair 考虑。尚未迁移到此形状的检查继续使用旧版 doctor 贡献流程。

这种分离是有意的：detect() 负责诊断，repair() 负责报告它修改了什么或将要修改什么。修复上下文可以携带 dryRun/diff 请求，修复结果可以返回结构化 diffs（针对配置/文件编辑）和 effects（针对服务、进程、包、状态或其他副作用）。这使转换后的检查能够朝着 doctor --fix --dry-run 和 diff 报告发展，而无需将变更规划移入 detect()。

repair() 报告它是否尝试了请求的修复，通过 status: "repaired" | "skipped" | "failed"。省略 status 意味着 repaired，因此简单的修复检查只需返回变更。当修复返回 skipped 或 failed 时，doctor 报告原因并在该检查上不运行验证。

成功结构化修复后，doctor 以修复后的发现结果为范围重新运行 detect()。检查可以使用选定的发现结果、路径或 ocPath 值进行聚焦验证。如果发现结果仍然存在，doctor 报告修复警告而不是将变更视为静默完成。

一个发现结果包含：

字段	用途
checkId	稳定的 ID，用于 skip/only 过滤和 CI 允许列表。
severity	info、warning 或 error。
message	人类可读的问题描述。
path	配置、文件或逻辑路径（可用时）。
line / column	源代码位置（可用时）。
ocPath	精确的 oc:// 地址（当检查可以指向一个时）。
fixHint	建议的操作者操作或修复摘要。

此版本在结构化健康路径上注册了优化后的核心 doctor 检查。openclaw/plugin-sdk/health 子路径为后续消费者暴露相同约定，但基于插件的检查仅在其所属包在活跃命令路径中注册后才运行。

检查选择

使用 --only 和 --skip 当工作流需要聚焦于特定门禁时：

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

--only 和 --skip 接受完整的检查 ID，可重复使用。如果 --only 的 ID 未注册，则该 ID 不会运行任何检查；使用命令的 checksRun 和 checksSkipped 字段验证聚焦门禁是否选择了预期的检查。

注意事项：

• 在 Nix 模式（OPENCLAW_NIX_MODE=1）下，只读 doctor 检查仍可工作，但 doctor --fix、doctor --repair、doctor --yes 和 doctor --generate-gateway-token 被禁用，因为 openclaw.json 不可变。请编辑此安装的 Nix 源；对于 nix-openclaw，使用智能体优先的 Quick Start。
• 交互式提示（如 keychain/OAuth 修复）仅在 stdin 是 TTY 且 未设置 --non-interactive 时运行。无头运行（cron、Telegram、无终端）将跳过提示。
• 性能：非交互式 doctor 运行跳过急切插件加载，保持无头健康检查快速。交互式 doctor 会话仍加载旧版健康与修复流程所需的插件表面。
• --lint 比 --non-interactive 更严格：它始终只读、从不提示、从不应用安全迁移。需要 doctor 做更改时运行 doctor --fix 或 doctor --repair。
• --fix（--repair 的别名）将备份写入 ~/.openclaw/openclaw.json.bak，然后删除未知配置键，并列出每个移除项。
• 优化后的健康检查可以为 doctor --fix 暴露 repair() 路径；未暴露此路径的检查继续通过现有 doctor 修复流程。
• doctor --fix --non-interactive 报告缺失或过时的 Gateway 服务定义，但不会在更新修复模式之外安装或重写它们。缺失服务运行 openclaw gateway install，有意替换启动器时运行 openclaw gateway install --force。
• 状态完整性检查现在可以检测 sessions 目录中的孤立转录文件。将它们归档为 .deleted.<timestamp> 需要交互确认；--fix、--yes 和无头运行会将其保持原位。
• Doctor 还扫描 ~/.openclaw/cron/jobs.json（或 cron.store）中的旧版 cron 任务形状，并可在调度器运行时自动规范化之前就地重写。
• Doctor 报告带有显式 payload.model 覆盖的 cron 任务，包括提供者命名空间计数以及与 agents.defaults.model 的不匹配，使得在认证或计费调查期间对不继承默认模型的任务可见。
• 在 Linux 上，当用户的 crontab 仍在运行旧版 ~/.openclaw/bin/ensure-whatsapp.sh 时，doctor 会发出警告；该脚本已不再维护，且当 cron 缺少 systemd user-bus 环境时可能记录错误的 WhatsApp Gateway 停机。
• 启用 WhatsApp 时，doctor 会检查是否存在退化的 Gateway 事件循环，同时本地 openclaw-tui 客户端仍在运行。doctor --fix 仅停止已验证的本地 TUI 客户端，以免 WhatsApp 回复因旧的 TUI 刷新循环而排队。
• Doctor 将旧版 openclaw-codex/* 模型引用重写为规范 openclaw/* 引用，涉及主模型、回退、心跳/subagent/压缩覆盖、hooks、渠道模型覆盖以及过期的会话路由固定。--fix 将 Codex 意图移至 provider/model 范围的 agentRuntime.id: "codex" 条目，保留会话认证配置文件固定（如 openclaw-codex:...），移除过期的整体智能体/会话运行时固定，并将修复后的 OpenAI 智能体引用保留在 Codex 认证路由上，而非直接使用 OpenAI API-key 认证。
• Doctor 清理由旧版 OpenClaw 版本创建的旧版插件依赖暂存状态，并为声明 openclaw 作为对等依赖的受管 npm 插件重建主机 openclaw 包的链接。它还修复由配置引用的缺失可下载插件，如 plugins.entries、已配置的渠道、配置的 provider/search 设置或配置的智能体运行时。在包更新期间，doctor 跳过包管理器插件修复，直到包交换完成；之后如果配置的插件仍需要恢复，重新运行 openclaw doctor --fix。如果下载失败，doctor 报告安装错误并保留配置的插件条目以备下次修复尝试。
• Doctor 通过从 plugins.allow/plugins.deny/plugins.entries 中移除缺失的插件 ID 来修复过时的插件配置，并在插件发现健康时匹配悬空的渠道配置、心跳目标和渠道模型覆盖。
• Doctor 将无效插件配置隔离，禁用受影响的 plugins.entries.<id> 条目并移除其无效的 config 负载。Gateway 启动时仅跳过该坏插件，其他插件和渠道可继续运行。
• 设置 OPENCLAW_SERVICE_REPAIR_POLICY=external 当另一个 supervisor 拥有 Gateway 生命周期时。Doctor 仍报告 Gateway/服务健康并应用非服务修复，但跳过服务安装/启动/重启/引导和旧版服务清理。
• 在 Linux 上，doctor 忽略不活跃的额外 Gateway 类 systemd 单元，并且在修复过程中不会重写正在运行的 systemd Gateway 服务的命令/入口点元数据。先停止服务，或使用 openclaw gateway install --force 当有意替换活跃启动器时。
• Doctor 自动迁移旧版平面 Talk 配置（talk.voiceId、talk.modelId 等）为 talk.provider + talk.providers.<provider>。
• 重复的 doctor --fix 运行在仅存在对象键顺序差异时不再报告/应用 Talk 规范化。
• Doctor 包含内存搜索就绪性检查，并可在嵌入凭证缺失时推荐运行 openclaw configure --section model。
• Doctor 在未配置命令所有者时发出警告。命令所有者是允许运行仅所有者命令和批准危险操作的人类操作员账户。DM 配对仅允许某人向机器人交谈；如果在首次所有者引导之前已批准发送者，请显式设置 commands.ownerAllowFrom。
• Doctor 在配置了 Codex 模式智能体且操作员的 Codex 主目录中存在个人 Codex CLI 资产时发出警告。本地 Codex 应用服务器启动使用隔离的每个智能体主目录，因此使用 openclaw migrate codex --dry-run 来盘点应有意提升的资产。
• Doctor 移除已退役的 plugins.entries.codex.config.codexDynamicToolsProfile；Codex 应用服务器始终将 Codex 原生工作区工具保留为原生。
• Doctor 在默认智能体允许的技能由于缺少二进制文件、环境变量、配置或 OS 需求而在当前运行时环境中不可用时发出警告。doctor --fix 可以用 skills.entries.<skill>.enabled=false 禁用这些不可用的技能；改为安装/配置缺失的需求以保持技能活跃。
• 如果启用了沙箱模式但 Docker 不可用，doctor 报告高优先级警告并提供修复建议（install Docker 或 openclaw config set agents.defaults.sandbox.mode off）。
• 如果存在旧版沙箱注册表文件（~/.openclaw/sandbox/containers.json 或 ~/.openclaw/sandbox/browsers.json），doctor 报告它们；openclaw doctor --fix 将有效条目迁移到分片注册表目录，并隔离无效的旧版文件。
• 如果 gateway.auth.token/gateway.auth.password 由 SecretRef 管理且在当前命令路径中不可用，doctor 报告只读警告，不写入明文回退凭据。
• 如果修复路径中的渠道 SecretRef 检查失败，doctor 继续运行并报告警告而非提前退出。
• 在状态目录迁移后，当启用的默认 Telegram 或 Discord 账户依赖环境回退且 TELEGRAM_BOT_TOKEN 或 DISCORD_BOT_TOKEN 对 doctor 进程不可用时，doctor 发出警告。
• Telegram allowFrom 用户名自动解析（doctor --fix）需要当前命令路径中存在可解析的 Telegram token。如果 token 检查不可用，doctor 报告警告并跳过该轮的自动解析。

macOS：launchctl 环境变量覆盖问题

如果你之前运行过 launchctl setenv OPENCLAW_GATEWAY_TOKEN ...（或 ...PASSWORD），该值会覆盖配置文件，导致持续出现"unauthorized"错误。

launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

相关文档

• CLI reference
• Gateway doctor

常见问题

openclaw doctor --fix 会修改我的配置文件吗？

会。--fix 会应用支持的修复，包括删除未知配置键、迁移旧版配置格式、重写模型引用和清理孤立状态。运行前会备份 ~/.openclaw/openclaw.json.bak。如果不希望修改，请使用 --lint 只读检查。

macOS 上 launchctl 环境变量导致认证失败怎么解决？

运行 launchctl getenv OPENCLAW_GATEWAY_TOKEN 和 launchctl getenv OPENCLAW_GATEWAY_PASSWORD 检查是否有残留的环境变量覆盖。如果有，用 launchctl unsetenv 清除，然后重新运行 openclaw doctor 确认问题消失。

在 Nix 模式下 doctor 能做什么？

Nix 模式（OPENCLAW_NIX_MODE=1）下，doctor --lint 等只读检查仍可用，但 doctor --fix、doctor --repair、doctor --yes 和 doctor --generate-gateway-token 被禁用，因为 openclaw.json 不可变。需要修改配置时，应编辑 Nix 源文件。