Doctor

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

快速开始

openclaw doctor

无人值守 / 自动化

openclaw doctor --yes

接受默认选项，不提示确认（包括重启、服务和 Sandbox 修复步骤）。

openclaw doctor --repair

自动应用推荐的修复，不提示确认（在安全的情况下进行修复和重启）。

openclaw doctor --repair --force

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

openclaw doctor --non-interactive

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

openclaw doctor --deep

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

如果你想在写入前查看变更，可以先打开配置文件：

cat ~/.openclaw/openclaw.json

功能概览

  • 可选的预检更新（仅限 git 安装，交互模式）。
  • UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
  • 健康检查 + 重启提示。
  • Skill 状态摘要（符合条件/缺失/被阻止）。
  • 旧配置值的规范化。
  • OpenCode Zen Provider 覆盖警告（models.providers.opencode）。
  • 旧磁盘状态迁移（Session/Agent 目录/WhatsApp 认证）。
  • 状态完整性和权限检查（Session、记录、状态目录）。
  • 配置文件权限检查（本地运行时检查 chmod 600）。
  • 模型认证健康检查：检查 OAuth 过期、刷新即将过期的 Token，报告认证配置的冷却/禁用状态。
  • 额外 Workspace 目录检测（~/openclaw）。
  • 启用 Sandbox 时的镜像修复。
  • 旧服务迁移和额外 Gateway 检测。
  • Gateway 运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
  • Channel 状态警告（从运行中的 Gateway 探测）。
  • Supervisor 配置审计（launchd/systemd/schtasks），可选修复。
  • Gateway 运行时最佳实践检查（Node vs Bun、版本管理器路径）。
  • Gateway 端口冲突诊断（默认 18789）。
  • 开放 DM 策略的安全警告。
  • Gateway 认证警告（本地模式下未设置 gateway.auth.token 时提供 Token 生成）。
  • Linux 上的 systemd linger 检查。
  • 源码安装检查（pnpm workspace 不匹配、缺失 UI 资源、缺失 tsx 二进制文件）。
  • 写入更新的配置和向导元数据。

详细行为和原理

0) 可选更新（git 安装）

如果这是 git 检出的版本，且 doctor 在交互模式下运行，它会在运行检查前提供更新选项（fetch/rebase/build）。

1) 配置规范化

如果配置包含旧的值格式（例如 messages.ackReaction 没有 Channel 特定的覆盖），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
  • 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 覆盖

如果你手动添加了 models.providers.opencode（或 opencode-zen），它会覆盖来自 @mariozechner/pi-ai 的内置 OpenCode Zen 目录。这可能会强制所有模型使用单一 API 或将成本归零。Doctor 会发出警告，以便你移除覆盖并恢复每个模型的 API 路由和成本。

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

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

  • Session 存储 + 记录：
    • 从 ~/.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 在启动时也会自动迁移旧的 Session 和 Agent 目录，所以历史记录、认证和模型会落在每个 Agent 的路径下，无需手动运行 doctor。WhatsApp 认证只能通过 openclaw doctor 迁移。

4) 状态完整性检查（Session 持久化、路由和安全）

状态目录是操作的核心。如果它消失了，你会丢失 Session、凭证、日志和配置（除非你在其他地方有备份）。

Doctor 检查：

  • 状态目录缺失：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。
  • 状态目录权限：验证可写性；提供修复权限的选项（当检测到所有者/组不匹配时发出 chown 提示）。
  • Session 目录缺失：sessions/ 和 Session 存储目录是持久化历史记录和避免 ENOENT 崩溃所必需的。
  • 记录不匹配：当最近的 Session 条目缺少记录文件时发出警告。
  • 主 Session “1 行 JSONL”：当主记录只有一行时标记（历史记录没有累积）。
  • 多个状态目录：当多个 ~/.openclaw 文件夹存在于不同的主目录中，或 OPENCLAW_STATE_DIR 指向其他地方时发出警告（历史记录可能在安装之间分裂）。
  • 远程模式提醒：如果 gateway.mode=remote，doctor 会提醒你在远程主机上运行它（状态在那里）。
  • 配置文件权限：如果 ~/.openclaw/openclaw.json 对组/其他用户可读，会发出警告并提供收紧到 600 的选项。

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

Doctor 检查认证存储中的 OAuth 配置，在 Token 即将过期或已过期时发出警告，并在安全时刷新它们。如果 Anthropic Claude Code 配置过期，它会建议运行 claude setup-token（或粘贴 setup-token）。刷新提示仅在交互运行（TTY）时出现；--non-interactive 会跳过刷新尝试。

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

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

6) Hooks 模型验证

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

7) Sandbox 镜像修复

启用 Sandbox 时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。

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

Doctor 检测旧的 Gateway 服务（launchd/systemd/schtasks），并提供移除它们并使用当前 Gateway 端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway 服务并打印清理提示。以配置文件命名的 OpenClaw Gateway 服务被视为一等公民，不会被标记为”额外”。

9) 安全警告

当 Provider 对 DM 开放且没有白名单时，或策略配置存在危险时，Doctor 会发出警告。

10) systemd linger（Linux）

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

11) Skill 状态

Doctor 会打印当前 Workspace 的符合条件/缺失/被阻止的 Skill 的快速摘要。

12) Gateway 认证检查（本地 Token）

当本地 Gateway 缺少 gateway.auth 时，Doctor 会发出警告并提供生成 Token 的选项。在自动化中使用 openclaw doctor --generate-gateway-token 强制创建 Token。

13) Gateway 健康检查 + 重启

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

14) Channel 状态警告

如果 Gateway 健康，doctor 会运行 Channel 状态探测并报告警告和建议的修复。

15) Supervisor 配置审计 + 修复

Doctor 检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少或过时的默认值（例如 systemd 的 network-online 依赖和重启延迟）。当发现不匹配时，它会推荐更新，并可以将服务文件/任务重写为当前默认值。

注意：

  • openclaw doctor 在重写 supervisor 配置前会提示。
  • openclaw doctor --yes 接受默认的修复提示。
  • openclaw doctor --repair 应用推荐的修复，不提示。
  • openclaw doctor --repair --force 覆盖自定义的 supervisor 配置。
  • 你始终可以通过 openclaw gateway install --force 强制完全重写。

16) Gateway 运行时 + 端口诊断

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

17) Gateway 运行时最佳实践

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

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

Doctor 持久化任何配置更改，并标记向导元数据以记录 doctor 运行。

19) Workspace 提示（备份 + 记忆系统）

当缺少 Workspace 记忆系统时，Doctor 会建议添加，如果 Workspace 尚未在 git 下，会打印备份提示。

查看 /concepts/agent-workspace 获取 Workspace 结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。