Doctor

openclaw doctor 是 OpenClaw 的修复 + 迁移工具。它修复陈旧的配置/状态，检查健康状况，并提供可操作的修复步骤。

快速开始

openclaw doctor

无头 / 自动化

openclaw doctor --yes

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

openclaw doctor --repair

应用推荐的修复而不提示（修复 + 在安全时重启）。

openclaw doctor --repair --force

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

openclaw doctor --non-interactive

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

openclaw doctor --deep

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

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

cat ~/.openclaw/openclaw.json

它做什么（摘要）

  • Git 安装的可选预检更新（仅限交互式）。
  • UI 协议新鲜度检查（当协议模式较新时重建控制 UI）。
  • 健康检查 + 重启提示。
  • 技能状态摘要（符合条件/缺失/被阻止）。
  • 遗留值的配置规范化。
  • OpenCode Zen 提供商覆盖警告（models.providers.opencode）。
  • 遗留磁盘状态迁移（会话/agent 目录/WhatsApp 认证）。
  • 状态完整性和权限检查（会话、转录、状态目录）。
  • 配置文件权限检查（本地运行时 chmod 600）。
  • 模型认证健康：检查 OAuth 过期，可以刷新即将过期的令牌，并报告认证配置文件冷却/禁用状态。
  • 额外工作空间目录检测（~/openclaw）。
  • 启用沙盒时的沙盒镜像修复。
  • 遗留服务迁移和额外 gateway 检测。
  • Gateway 运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
  • 频道状态警告（从正在运行的 gateway 探测）。
  • 监督器配置审计（launchd/systemd/schtasks），带有可选修复。
  • Gateway 运行时最佳实践检查（Node vs Bun，版本管理器路径）。
  • Gateway 端口冲突诊断（默认 18789）。
  • 开放 DM 策略的安全警告。
  • 当未设置 gateway.auth.token 时的 Gateway 认证警告（本地模式；提供令牌生成）。
  • Linux 上的 systemd linger 检查。
  • 源安装检查（pnpm 工作空间不匹配、缺失 UI 资产、缺失 tsx 二进制文件）。
  • 写入更新的配置 + 向导元数据。

详细行为和原理

0) 可选更新（git 安装）

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

1) 配置规范化

如果配置包含遗留值形状（例如，没有频道特定覆盖的 messages.ackReaction），doctor 将它们规范化为当前模式。

2) 遗留配置键迁移

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

Doctor 将：

  • 解释找到了哪些遗留键。
  • 显示它应用的迁移。
  • 使用更新的模式重写 ~/.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 提供商覆盖

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

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

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

  • 会话存储 + 转录：
    • 从 ~/.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 目录，因此历史/认证/模型落在每个 agent 的路径中，无需手动运行 doctor。WhatsApp 认证仅通过 openclaw doctor 迁移。

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

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

Doctor 检查：

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

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

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

Doctor 还报告由于以下原因暂时无法使用的认证配置文件：

  • 短冷却（速率限制/超时/认证失败）
  • 更长的禁用（计费/信用失败）

6) Hooks 模型验证

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

7) 沙盒镜像修复

当启用沙盒时，doctor 检查 Docker 镜像，如果当前镜像缺失，则提供构建或切换到遗留名称的选项。

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

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

9) 安全警告

Doctor 在提供商对 DM 开放而没有白名单时，或在策略以危险方式配置时发出警告。

10) systemd linger（Linux）

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

11) 技能状态

Doctor 打印当前工作空间的符合条件/缺失/被阻止技能的快速摘要。

12) Gateway 认证检查（本地令牌）

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

13) Gateway 健康检查 + 重启

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

14) 频道状态警告

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

15) 监督器配置审计 + 修复

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

注意：

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

16) Gateway 运行时 + 端口诊断

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

17) Gateway 运行时最佳实践

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

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

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

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

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

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

← 返回文档首页