Doctor

openclaw doctor 是 OpenClaw 的修复 + 迁移工具。它会修复陈旧的 config/state，检查健康状况，并给出可执行的修复步骤。

快速开始

openclaw doctor

Headless / automation

openclaw doctor --yes

在不提示的情况下接受默认值（在适用时包括 restart/service/sandbox 的修复步骤）。

openclaw doctor --repair

在不提示的情况下应用推荐修复（在安全时包含 repairs + restarts）。

openclaw doctor --repair --force

也应用更激进的修复（会覆盖自定义 supervisor configs）。

openclaw doctor --non-interactive

在无提示模式下运行，并且只应用安全迁移（config 归一化 + 磁盘 state 移动）。会跳过需要人工确认的 restart/service/sandbox 操作。 检测到 legacy state migrations 时会自动运行。

openclaw doctor --deep

扫描系统服务中是否存在额外的 gateway installs（launchd/systemd/schtasks）。

如果你希望在写入前先审阅变更，请先打开 config 文件：

cat ~/.openclaw/openclaw.json

它会做什么（概览）

• 可选：对 git 安装进行 pre-flight update（仅交互模式）。
• UI protocol 新鲜度检查（当协议 schema 更新时重建 Control UI）。
• 健康检查 + 重启提示。
• Skills 状态摘要（可用/缺失/被阻止）。
• 对 legacy values 做 config 归一化。
• OpenCode Zen provider override 警告（models.providers.opencode）。
• legacy 的磁盘 state 迁移（sessions/agent dir/WhatsApp auth）。
• state 完整性与权限检查（sessions、transcripts、state dir）。
• 本地运行时对 config 文件权限检查（chmod 600）。
• 模型鉴权健康：检查 OAuth 过期、可刷新即将过期 token、报告 auth-profile 冷却/禁用状态。
• 额外 workspace dir 检测（~/openclaw）。
• sandboxing 启用时的沙箱镜像修复。
• legacy service 迁移与额外 gateway 检测。
• gateway runtime 检查（service 已安装但未运行；缓存的 launchd label）。
• channel 状态警告（从运行中的 gateway probe）。
• supervisor config 审计（launchd/systemd/schtasks），并可选修复。
• gateway runtime 最佳实践检查（Node vs Bun、版本管理器路径）。
• gateway 端口冲突诊断（默认 18789）。
• 针对开放 DM policy 的安全警告。
• 本地模式下未设置 gateway.auth.token 的 gateway auth 警告（提供生成 token 的选项）。
• Linux 上的 systemd linger 检查。
• 源码安装检查（pnpm workspace mismatch、缺失 UI assets、缺失 tsx binary）。
• 写回更新后的 config + wizard metadata。

详细行为与动机

0）可选更新（git installs）

如果这是一个 git checkout 且 doctor 在交互式运行，它会在运行 doctor 之前，询问你是否要先更新（fetch/rebase/build）。

1）Config 归一化

如果 config 包含旧版的 value 形态（例如 messages.ackReaction 没有按 channel 覆盖），doctor 会把它归一化到当前 schema。

2）Legacy config key 迁移

当 config 包含已废弃的 keys 时，其它命令会拒绝运行，并提示你执行 openclaw doctor。

Doctor 会：

• 解释发现了哪些 legacy keys。
• 展示它应用了哪些迁移。
• 以更新后的 schema 重写 ~/.openclaw/openclaw.json。

当 Gateway 在启动时检测到 legacy config 格式，也会自动运行这些 doctor migrations，因此陈旧配置无需人工介入即可修复。

当前迁移：

• 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
• 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

2b）OpenCode Zen provider overrides

如果你手动添加了 models.providers.opencode（或 opencode-zen），它会覆盖内置的 OpenCode Zen catalog（来自 @mariozechner/pi-ai）。这可能会把所有模型强制路由到同一个 API，或把成本归零。doctor 会给出警告，便于你移除 override 并恢复按模型的 API 路由 + 成本。

3）Legacy state 迁移（磁盘布局）

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

• Sessions store + transcripts：
  • 从 ~/.openclaw/sessions/ 到 ~/.openclaw/agents/<agentId>/sessions/
• Agent dir：
  • 从 ~/.openclaw/agent/ 到 ~/.openclaw/agents/<agentId>/agent/
• WhatsApp 鉴权状态（Baileys）：
  • 从 legacy ~/.openclaw/credentials/*.json（不含 oauth.json）
  • 到 ~/.openclaw/credentials/whatsapp/<accountId>/...（默认 account id：default）

这些迁移是 best-effort 且幂等的；当它把 legacy 文件夹保留为备份时，会输出 warnings。 Gateway/CLI 也会在启动时自动迁移 legacy sessions + agent dir，以便 history/auth/models 落在 per-agent 路径下，而不需要手动运行 doctor。 WhatsApp auth 则刻意只允许通过 openclaw doctor 迁移。

4）State 完整性检查（session 持久化、路由与安全）

state directory 是运行时的“脑干”。如果它丢了，你会失去 sessions、credentials、logs 与 config（除非你在其它地方有备份）。

Doctor 会检查：

• State dir 缺失：警告灾难性的 state 丢失风险；提示重建目录，并提醒无法恢复丢失数据。
• State dir 权限：验证可写性；可修复权限（当检测到 owner/group 不匹配时也会给出 chown 提示）。
• Session dirs 缺失：sessions/ 与 session store 目录是持久化历史、防止 ENOENT 崩溃所必需的。
• Transcript mismatch：当近期 session 条目缺少 transcript 文件时报警。
• Main session “1-line JSONL”：当 main transcript 只有一行时提示（历史没有累积）。
• 多个 state dirs：当多个 home 目录下存在多个 ~/.openclaw，或 OPENCLAW_STATE_DIR 指向其它位置时报警（历史会在不同安装之间分裂）。
• Remote mode 提示：如果 gateway.mode=remote，doctor 会提醒你在远端主机上运行它（state 存在那里）。
• Config 文件权限：当 ~/.openclaw/openclaw.json 对 group/world 可读时报警，并提供收紧到 600 的选项。

5）模型鉴权健康（OAuth 过期）

Doctor 会检查 auth store 中的 OAuth profiles；当 tokens 即将过期/已过期时告警，并在安全时可刷新。 如果 Anthropic Claude Code profile 过旧，它会建议运行 claude setup-token（或粘贴 setup-token）。 刷新提示只会在交互式（TTY）运行时出现；--non-interactive 会跳过刷新尝试。

Doctor 也会报告暂时不可用的 auth profiles，常见原因：

• 短暂 cooldown（限流/超时/鉴权失败）
• 更长 disable（计费/余额失败）

6）Hooks 模型校验

如果设置了 hooks.gmail.model，doctor 会基于 catalog 与 allowlist 校验该 model 引用，并在无法解析或被禁用时告警。

7）沙箱镜像修复

当启用 sandboxing 时，doctor 会检查 Docker images，并在当前镜像缺失时建议构建或切换到 legacy names。

8）Gateway service 迁移与清理提示

Doctor 会检测 legacy gateway services（launchd/systemd/schtasks），并提供移除它们、以及用当前 gateway port 安装 OpenClaw service 的选项。 它也会扫描额外的 gateway-like services 并给出清理提示。 带 profile 的 OpenClaw gateway services 视为一等公民，不会被标记为 “extra”。

9）安全警告

当某个 provider 对 DMs 开放且没有 allowlist，或 policy 配置得很危险时，doctor 会输出警告。

10）systemd linger（Linux）

如果以 systemd user service 运行，doctor 会确保启用 lingering，以便 gateway 在登出后仍保持运行。

11）Skills 状态

doctor 会为当前 workspace 打印一份可用/缺失/被阻止 skills 的快速摘要。

12）Gateway 鉴权检查（本地 token）

当本地 gateway 缺少 gateway.auth 时，doctor 会警告并提供生成 token 的选项。 在自动化中可用 openclaw doctor --generate-gateway-token 强制生成 token。

13）Gateway 健康检查 + 重启

doctor 会执行健康检查；当 gateway 看起来不健康时，会提供重启选项。

14）Channel 状态警告

如果 gateway 健康，doctor 会进行 channel status probe，并报告 warnings 与建议修复。

15）Supervisor config 审计 + 修复

doctor 会检查已安装的 supervisor config（launchd/systemd/schtasks）是否缺少或过期默认项（例如 systemd 的 network-online 依赖与重启延迟）。当发现不匹配时，会推荐更新，并可把 service file/task 重写为当前默认值。

备注：

• openclaw doctor 在重写 supervisor config 前会提示。
• openclaw doctor --yes 接受默认修复提示。
• openclaw doctor --repair 在无提示下应用推荐修复。
• openclaw doctor --repair --force 会覆盖自定义 supervisor configs。
• 你也可以通过 openclaw gateway install --force 强制全量重写。

16）Gateway runtime + 端口诊断

doctor 会检查 service runtime（PID、上次退出状态），并在 service 已安装但实际未运行时告警。 它也会检查 gateway 端口（默认 18789）是否冲突，并报告可能原因（gateway 已在运行、SSH 隧道）。

17）Gateway runtime 最佳实践

doctor 会在 gateway service 运行于 Bun 或某个版本管理器的 Node 路径（nvm、fnm、volta、asdf 等）时报警。 WhatsApp + Telegram channels 需要 Node，而版本管理器路径可能在升级后失效，因为 service 不会加载你的 shell init。 当可用时，doctor 会建议迁移到系统安装的 Node（Homebrew/apt/choco）。

18）写入 config + wizard metadata

doctor 会落盘任何 config 变更，并写入 wizard metadata 以记录本次 doctor run。

19）Workspace 提示（备份 + memory 系统）

当缺少 workspace memory 系统时，doctor 会建议启用；当 workspace 未在 git 下时，会给出备份提示。

完整指南见 /concepts/agent-workspace（推荐使用私有 GitHub 或 GitLab）。