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 状态摘要（合格/缺失/阻塞）。
• 旧版值的配置规范化。
• 旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。
• OpenCode 提供商覆盖警告（models.providers.opencode / models.providers.opencode-go）。
• 旧版磁盘状态迁移（会话/agent 目录/WhatsApp 认证）。
• 旧版 cron store 迁移（jobId、schedule.cron、顶层 delivery/payload 字段、payload provider、简单 notify: true webhook 降级任务）。
• 状态完整性和权限检查（会话、转录、状态目录）。
• 本地运行时的配置文件权限检查（chmod 600）。
• 模型认证健康：检查 OAuth 过期，可以刷新即将过期的 token，并报告 auth-profile 冷却/禁用状态。
• 额外工作空间目录检测（~/openclaw）。
• 沙盒启用时的沙盒镜像修复。
• 旧版服务迁移和额外 Gateway 检测。
• Gateway 运行时检查（已安装服务但未运行；缓存的 launchd 标签）。
• 渠道状态警告（从运行中的 Gateway 探测）。
• Supervisor 配置审计（launchd/systemd/schtasks）加可选修复。
• Gateway 运行时最佳实践检查（Node vs Bun，版本管理器路径）。
• Gateway 端口冲突诊断（默认 18789）。
• 开放 DM 策略的安全警告。
• 本地 token 模式的 Gateway 认证检查（在没有 token 来源时提供生成；不覆盖 token SecretRef 配置）。
• Linux 上的 systemd linger 检查。
• 源码安装检查（pnpm 工作空间不匹配、缺失 UI 资产、缺失 tsx 二进制）。
• 写入更新的配置 + 向导元数据。

详细行为和原理

0）可选更新（git 安装）

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

1）配置规范化

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

2）旧版配置键迁移

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

Doctor 会：

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

Gateway 在启动时检测到旧版配置格式也会自动运行 doctor 迁移，无需手动干预就能修复过时的配置。

当前迁移：

• 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
• routing.agentToAgent → tools.agentToAgent
• routing.transcribeAudio → tools.media.audio.models
• bindings[].match.accountID → bindings[].match.accountId
• 对于有命名 accounts 但缺少 accounts.default 的渠道，在存在时将账户范围的顶层单账户渠道值移入 channels.<channel>.accounts.default
• 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+
• 浏览器在本地运行
• 在该浏览器中启用了远程调试
• 在浏览器中批准了首次附加同意提示

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 迁移。

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

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 Claude Code profile 过期，它建议运行 claude setup-token（或粘贴 setup-token）。刷新提示只在交互式运行时出现（TTY）；--non-interactive 跳过刷新尝试。

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

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

6）Hooks 模型验证

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

7）沙盒镜像修复

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

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

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

9）安全警告

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

10）systemd linger（Linux）

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

11）Skills 状态

Doctor 打印当前工作空间的合格/缺失/阻塞 skill 的快速摘要。

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 看起来不健康时提供重启。

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，它会帮你找到根源并给出修复建议。