Doctor

openclaw doctor 是 OpenClaw 的修复与迁移工具。它修复过时的配置/状态，检查健康状况，并提供可执行的修复步骤。

快速开始

openclaw doctor

无界面 / 自动化模式

openclaw doctor --yes

接受默认值而无需提示（包括适用时的重启/服务/沙盒修复步骤）。

openclaw doctor --repair

应用推荐的修复而无需提示（包括安全的修复 + 重启）。

openclaw doctor --repair --force

也应用激进的修复（覆盖自定义的 supervisor 配置）。

openclaw doctor --non-interactive

无提示运行，只应用安全的迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙盒操作。 检测到时自动运行旧版状态迁移。

openclaw doctor --deep

扫描系统服务以查找额外的 Gateway 安装（launchd/systemd/schtasks）。

如果你想在写入前审查更改，先打开配置文件：

cat ~/.openclaw/openclaw.json

功能概览

• 可选的 git 安装预检更新（仅交互式）。
• UI 协议新鲜度检查（当协议 schema 更新时重建控制 UI）。
• 健康检查 + 重启提示。
• Skills 状态摘要（合格/缺失/阻塞）以及插件状态。
• 旧版值的配置规范化。
• Talk 配置从旧版扁平字段（talk.*）到 talk.provider + talk.providers.<provider> 的迁移。
• 旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。
• OpenAI Codex OAuth profile 的 TLS 前置条件检查。
• OpenCode 提供商覆盖警告（models.providers.opencode / models.providers.opencode-go）。
• 旧版磁盘状态迁移（会话/agent 目录/WhatsApp 认证）。
• 旧版插件 Manifest 契约键迁移。
• 旧版 cron store 迁移（jobId、schedule.cron、顶层 delivery/payload 字段、payload provider、简单 notify: true webhook 降级任务）。
• 会话锁文件检查和失效锁清理。
• 状态完整性和权限检查（会话、转录、状态目录）。
• 本地运行时的配置文件权限检查（chmod 600）。
• 模型认证健康：检查 OAuth 过期，可以刷新即将过期的 token，并报告 auth-profile 冷却/禁用状态。
• 额外工作空间目录检测（~/openclaw）。
• 沙盒启用时的沙盒镜像修复。
• 旧版服务迁移和额外 Gateway 检测。
• Matrix 渠道旧版状态迁移（--fix / --repair 模式）。
• Gateway 运行时检查（已安装服务但未运行；缓存的 launchd 标签）。
• 渠道状态警告（从运行中的 Gateway 探测）。
• Supervisor 配置审计（launchd/systemd/schtasks）加可选修复。
• Gateway 运行时最佳实践检查（Node vs Bun，版本管理器路径）。
• Gateway 端口冲突诊断（默认 18789）。
• 开放 DM 策略的安全警告。
• 本地 token 模式的 Gateway 认证检查（在没有 token 来源时提供生成；不覆盖 token SecretRef 配置）。
• Linux 上的 systemd linger 检查。
• 工作区 Bootstrap 文件大小检查（截断/接近上限的上下文文件警告）。
• Shell 补全状态检查及自动安装/升级。
• 内存搜索 embedding 提供商就绪检查（本地模型、远程 API Key 或 QMD 二进制）。
• 源码安装检查（pnpm 工作空间不匹配、缺失 UI 资产、缺失 tsx 二进制）。
• 写入更新的配置 + 向导元数据。

详细行为和原理

0）可选更新（git 安装）

如果这是 git checkout 且 doctor 以交互式运行，它会在运行 doctor 前提供更新（fetch/rebase/build）。

1）配置规范化

如果配置包含旧版值的形态（例如没有渠道特定覆盖的 messages.ackReaction），doctor 会将其规范化为当前 schema。

这也包括旧版 Talk 扁平字段的迁移。当前公开的 Talk 配置格式为 talk.provider + talk.providers.<provider>。Doctor 将旧版 talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey 重写为提供商映射格式。

2）旧版配置键迁移

当配置包含已废弃的键时，其他命令会拒绝运行并要求你运行 openclaw doctor。

Doctor 会：

• 解释找到了哪些旧版键。
• 显示应用的迁移。
• 用更新的 schema 重写 ~/.openclaw/openclaw.json。

Gateway 在启动时检测到旧版配置格式也会自动运行 doctor 迁移，无需手动干预就能修复过时的配置。Cron 任务 store 迁移由 openclaw doctor --fix 处理。

当前迁移：

• routing.allowFrom → channels.whatsapp.allowFrom
• routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
• routing.groupChat.historyLimit → messages.groupChat.historyLimit
• routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
• routing.queue → messages.queue
• routing.bindings → 顶层 bindings
• routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
• 旧版 talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + talk.providers.<provider>
• routing.agentToAgent → tools.agentToAgent
• routing.transcribeAudio → tools.media.audio.models
• messages.tts.<provider>（openai/elevenlabs/microsoft/edge）→ messages.tts.providers.<provider>
• channels.discord.voice.tts.<provider> → channels.discord.voice.tts.providers.<provider>
• channels.discord.accounts.<id>.voice.tts.<provider> → channels.discord.accounts.<id>.voice.tts.providers.<provider>
• plugins.entries.voice-call.config.tts.<provider> → plugins.entries.voice-call.config.tts.providers.<provider>
• plugins.entries.voice-call.config.provider: "log" → "mock"
• plugins.entries.voice-call.config.twilio.from → plugins.entries.voice-call.config.fromNumber
• plugins.entries.voice-call.config.streaming.sttProvider → plugins.entries.voice-call.config.streaming.provider
• plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold → plugins.entries.voice-call.config.streaming.providers.openai.*
• bindings[].match.accountID → bindings[].match.accountId
• 对于有命名 accounts 但残留单账号顶层渠道值的渠道，将这些值移入为该渠道选定的账号（大多数渠道为 accounts.default；Matrix 可保留现有匹配的命名/默认目标）
• identity → agents.list[].identity
• agent.* → agents.defaults + tools.*（tools/elevated/exec/sandbox/subagents）
• agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks
• browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
• browser.profiles.*.driver: "extension" → "existing-session"
• 移除 browser.relayBindHost（旧版扩展 relay 设置）

2b）OpenCode 提供商覆盖

如果你手动添加了 models.providers.opencode、opencode-zen 或 opencode-go，它会覆盖 @mariozechner/pi-ai 中的内置 OpenCode 目录。这可能会强制模型使用错误的 API 或将成本清零。Doctor 发出警告，以便你删除覆盖并恢复每模型 API 路由 + 成本。

2c）浏览器迁移和 Chrome MCP 就绪状态

如果你的浏览器配置仍指向已删除的 Chrome 扩展路径，doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型：

• browser.profiles.*.driver: "extension" 变为 "existing-session"
• browser.relayBindHost 被移除

Doctor 还在你使用 defaultProfile: "user" 或配置的 existing-session profile 时审计主机本地 Chrome MCP 路径：

• 检查同一主机上是否安装了 Google Chrome（用于默认自动连接 profile）
• 检查检测到的 Chrome 版本，低于 Chrome 144 时发出警告
• 提醒你在浏览器 inspect 页面启用远程调试（例如 chrome://inspect/#remote-debugging）

Doctor 无法为你启用 Chrome 端的设置。主机本地 Chrome MCP 仍然需要：

• 同一 Gateway/节点主机上运行基于 Chromium 的浏览器 144+
• 浏览器在本地运行
• 在该浏览器中启用了远程调试
• 在浏览器中批准了首次附加同意提示

此处的就绪检查仅关于本地附加前置条件。已有会话保持当前 Chrome MCP 路由限制；responsebody、PDF 导出、下载拦截和批量操作等高级路由仍需托管浏览器或原始 CDP profile。

2d）OAuth TLS 前置条件

当配置了 OpenAI Codex OAuth profile 时，doctor 会探测 OpenAI 授权端点，验证本地 Node/OpenSSL TLS 栈能否验证证书链。若探测因证书错误失败（如 UNABLE_TO_GET_ISSUER_CERT_LOCALLY、证书过期或自签名证书），doctor 打印平台专属修复指引。macOS 使用 Homebrew Node 时，通常执行 brew postinstall ca-certificates 即可修复。使用 --deep 时，即使 Gateway 健康，探测也会运行。

3）旧版状态迁移（磁盘布局）

Doctor 可以将旧版磁盘布局迁移到当前结构：

• 会话 store + 转录：
  • 从 ~/.openclaw/sessions/ 迁移到 ~/.openclaw/agents/<agentId>/sessions/
• Agent 目录：
  • 从 ~/.openclaw/agent/ 迁移到 ~/.openclaw/agents/<agentId>/agent/
• WhatsApp 认证状态（Baileys）：
  • 从旧版 ~/.openclaw/credentials/*.json（除 oauth.json 外）
  • 迁移到 ~/.openclaw/credentials/whatsapp/<accountId>/...（默认账户 id：default）

这些迁移是尽力而为且幂等的；当 doctor 留下任何旧版文件夹作为备份时会发出警告。Gateway/CLI 也会在启动时自动迁移旧版会话 + agent 目录，无需手动运行 doctor 就能将历史/认证/模型放到每 agent 路径下。WhatsApp 认证只能通过 openclaw doctor 迁移。Talk 提供商/提供商映射规范化现在使用结构相等性比较，仅 key 顺序不同的变化不再触发重复的 doctor --fix 空操作。

3a）旧版插件 Manifest 迁移

Doctor 扫描所有已安装的插件 Manifest，查找废弃的顶层能力键（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders）。发现后提供将其移入 contracts 对象并原地重写 Manifest 文件的选项。此迁移是幂等的；若 contracts 键已含相同值，旧键被删除而不重复数据。

3b）旧版 cron store 迁移

Doctor 还会检查 cron 任务 store（默认为 ~/.openclaw/cron/jobs.json）中调度器仍为兼容性接受的旧版任务形态。

当前 cron 清理包括：

• jobId → id
• schedule.cron → schedule.expr
• 顶层 payload 字段（message、model、thinking ...）→ payload
• 顶层 delivery 字段（deliver、channel、to、provider ...）→ delivery
• payload provider delivery 别名 → 显式 delivery.channel
• 简单旧版 notify: true webhook 降级任务 → 显式 delivery.mode="webhook" 加 delivery.to=cron.webhook

Doctor 仅在不改变行为时自动迁移 notify: true 任务。若任务将旧版 notify 降级与现有非 webhook 投递模式组合，doctor 发出警告，留待人工处理。

3c）会话锁文件清理

Doctor 扫描每个 agent 会话目录，查找失效的写锁文件——会话异常退出时遗留的文件。对找到的每个锁文件报告：路径、PID、PID 是否仍存活、锁的存在时长，以及是否被认定为失效（PID 已死亡或锁存在超过 30 分钟）。在 --fix / --repair 模式下自动删除失效锁文件；否则打印提示并要求用 --fix 重新运行。

4）状态完整性检查

Doctor 检查：

• 状态目录缺失：警告灾难性状态丢失，提示重建目录。
• 状态目录权限：验证可写性；提供修复权限。
• macOS 云同步状态目录：当状态解析在 iCloud Drive 或 ~/Library/CloudStorage/... 下时发出警告。
• Linux SD 或 eMMC 状态目录：当状态解析到 mmcblk* 挂载源时发出警告，因为 SD 或 eMMC 随机 I/O 可能更慢且磨损更快。
• 会话目录缺失：sessions/ 和会话 store 目录需要存在。
• 转录不匹配：警告最近会话条目有缺失的转录文件。
• 主会话"单行 JSONL"：标记主转录只有一行（历史没有积累）时。

5）模型认证健康（OAuth 过期）

Doctor 检查认证 store 中的 OAuth profile，在 token 即将过期/已过期时发出警告，并在安全时刷新。如果 Anthropic OAuth/token profile 过期，它建议使用 Anthropic API Key 或旧版 Anthropic setup-token 路径。刷新提示只在交互式运行时出现（TTY）；--non-interactive 跳过刷新尝试。

Doctor 还检测失效的 Anthropic Claude CLI 状态。若旧版 anthropic:claude-cli 凭据字节仍存在于 auth-profiles.json 中，doctor 将其转换回 Anthropic token/OAuth profile，并重写失效的 claude-cli/... 模型引用。若字节已消失，doctor 删除失效配置并打印恢复命令。

Doctor 还报告由于以下原因暂时不可用的认证 profile：

• 短暂冷却（速率限制/超时/认证失败）
• 较长时间的禁用（账单/信用失败）

6）Hooks 模型验证

如果设置了 hooks.gmail.model，doctor 会针对目录和 allowlist 验证模型引用，并在无法解析或不被允许时发出警告。

7）沙盒镜像修复

当沙盒启用时，doctor 检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称。

7b）捆绑插件运行时依赖

Doctor 验证捆绑的插件运行时依赖（例如 Discord 插件的运行时包）是否存在于 OpenClaw 安装根目录。若缺失，doctor 报告这些包，并在 openclaw doctor --fix / openclaw doctor --repair 模式下安装它们。

8）Gateway 服务迁移和清理提示

Doctor 检测旧版 Gateway 服务（launchd/systemd/schtasks），并提供使用当前 Gateway 端口删除它们并安装 OpenClaw 服务。它还可以扫描额外的类 Gateway 服务并打印清理提示。以 profile 命名的 OpenClaw Gateway 服务被视为一等服务，不会被标记为"额外"。

8b）启动时 Matrix 迁移

当 Matrix 渠道账号有待处理或可执行的旧版状态迁移时，doctor（在 --fix / --repair 模式下）创建迁移前快照，然后执行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。两步骤均为非致命的；错误会被记录，启动继续。纯读取模式（不带 --fix 的 openclaw doctor）完全跳过此检查。

9）安全警告

当提供商向 DM 开放而没有 allowlist 时，或者策略以危险方式配置时，doctor 发出警告。

10）systemd linger（Linux）

如果作为 systemd 用户服务运行，doctor 确保 lingering 已启用，以便 Gateway 在注销后保持运行。

11）工作区状态（Skills、插件和旧版目录）

Doctor 打印默认 Agent 的工作区状态摘要：

• Skills 状态：统计合格、缺失需求、allowlist 阻塞的 skill 数量。
• 旧版工作区目录：当 ~/openclaw 或其他旧版工作区目录与当前工作区并存时发出警告。
• 插件状态：统计已加载/禁用/出错的插件；列出出错插件的 ID；报告捆绑插件能力。
• 插件兼容性警告：标记与当前运行时有兼容性问题的插件。
• 插件诊断：展示插件注册表在加载时发出的警告或错误。

11b）Bootstrap 文件大小

Doctor 检查工作区 Bootstrap 文件（如 AGENTS.md、CLAUDE.md 或其他注入的上下文文件）是否接近或超过配置的字符上限。报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（max/file 或 max/total），以及总注入字符占总上限的比例。当文件被截断或接近上限时，doctor 打印调整 agents.defaults.bootstrapMaxChars 和 agents.defaults.bootstrapTotalMaxChars 的建议。

11c）Shell 补全

Doctor 检查当前 Shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全：

• 若 Shell profile 使用慢速动态补全模式（source <(openclaw completion ...)），doctor 将其升级为更快的缓存文件模式。
• 若 profile 中已配置补全但缓存文件缺失，doctor 自动重新生成缓存。
• 若完全未配置补全，doctor 提示安装（仅交互式；--non-interactive 跳过）。

手动重新生成缓存：openclaw completion --write-state。

12）Gateway 认证检查（本地 token）

Doctor 检查本地 Gateway token 认证就绪状态。

• 如果 token 模式需要 token 且没有 token 来源，doctor 提供生成。
• 如果 gateway.auth.token 由 SecretRef 管理但不可用，doctor 发出警告且不会用明文覆盖它。
• openclaw doctor --generate-gateway-token 仅在未配置 token SecretRef 时强制生成。

13）Gateway 健康检查 + 重启

Doctor 运行健康检查，并在 Gateway 看起来不健康时提供重启。

13b）内存搜索就绪

Doctor 检查默认 Agent 的内存搜索 embedding 提供商是否就绪，行为取决于配置的后端和提供商：

• QMD 后端：探测 qmd 二进制是否可用并可启动。若不可用，打印修复指引，包括 npm 包和手动二进制路径选项。
• 显式本地提供商：检查本地模型文件或已知的远程/可下载模型 URL 是否存在。若缺失，建议切换到远程提供商。
• 显式远程提供商（openai、voyage 等）：验证环境变量或认证 store 中是否存在 API Key。若缺失，打印可执行的修复提示。
• 自动提供商：先检查本地模型可用性，然后按自动选择顺序尝试每个远程提供商。

若 Gateway 探测结果可用（检查时 Gateway 健康），doctor 将其与 CLI 可见配置交叉对比，并提示任何差异。

使用 openclaw memory status --deep 在运行时验证 embedding 就绪状态。

14）渠道状态警告

如果 Gateway 健康，doctor 运行渠道状态探测并报告带有建议修复的警告。

15）Supervisor 配置审计 + 修复

Doctor 检查已安装的 supervisor 配置（launchd/systemd/schtasks）中缺失或过期的默认值（例如 systemd 网络在线依赖和重启延迟）。发现不匹配时，它建议更新并可以将服务文件/任务重写为当前默认值。

注意：

• openclaw doctor 在重写 supervisor 配置前会提示。
• openclaw doctor --yes 接受默认的修复提示。
• openclaw doctor --repair 无提示应用推荐的修复。
• openclaw doctor --repair --force 覆盖自定义的 supervisor 配置。

16）Gateway 运行时 + 端口诊断

Doctor 检查服务运行时（PID、最后退出状态），并在服务已安装但实际未运行时发出警告。它还检查 Gateway 端口（默认 18789）的端口冲突并报告可能的原因（Gateway 已在运行、SSH 隧道）。

17）Gateway 运行时最佳实践

Doctor 在 Gateway 服务运行在 Bun 或版本管理的 Node 路径（nvm、fnm、volta、asdf 等）上时发出警告。WhatsApp + Telegram 渠道需要 Node，版本管理器路径在升级后可能会损坏，因为服务不加载你的 shell init。当系统 Node 安装可用时（Homebrew/apt/choco），doctor 提供迁移。

18）配置写入 + 向导元数据

Doctor 持久化所有配置更改，并在向导元数据上标记 doctor 运行记录。

19）工作空间提示（备份 + 内存系统）

Doctor 在缺失时建议工作空间内存系统，并在工作空间不在 git 下时打印备份提示。

完整的工作空间结构和 git 备份指南见 /openclaw/concepts/agent-workspace（推荐使用私有 GitHub 或 GitLab）。

---

小龙虾跑不起来？先养成好习惯：每次出问题先跑 openclaw doctor，它会帮你找到根源并给出修复建议。