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

详细行为与设计考量

0) 可选更新（git 安装）

如果是 git checkout 且 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

Doctor 还会对多账户频道发出账户默认值的提示：

  • 如果 channels.<channel>.accounts 有两个以上条目但没设 channels.<channel>.defaultAccount 或 accounts.default，会警告回退路由可能选到意料之外的账户。
  • 如果 channels.<channel>.defaultAccount 指向未知的账户 ID，会警告并列出已配置的账户 ID。

2b) OpenCode 提供商覆盖

如果你手动添加了 models.providers.opencode、opencode-zen 或 opencode-go，会覆盖 @mariozechner/pi-ai 内置的 OpenCode 目录。这可能导致模型走错 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 组织的路径。WhatsApp 认证的迁移有意只通过 openclaw doctor 进行。

3b) 旧版 cron 存储迁移

Doctor 还会检查 cron 任务存储（默认 ~/.openclaw/cron/jobs.json，可通过 cron.store 覆盖）中的旧格式，调度器出于兼容仍然接受这些格式。

当前 cron 清理包括：

  • jobId → id
  • schedule.cron → schedule.expr
  • 顶层 payload 字段（message、model、thinking 等）→ payload
  • 顶层交付字段（deliver、channel、to、provider 等）→ delivery
  • payload 中的 provider 交付别名 → 显式 delivery.channel
  • 简单旧版 notify: true webhook 回退任务 → 显式 delivery.mode="webhook" + delivery.to=cron.webhook

Doctor 只在不改变行为的前提下自动迁移 notify: true 任务。如果一个任务同时有旧版 notify 回退和非 webhook 交付模式，doctor 会警告并留给你手动处理。

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

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

Doctor 检查项：

  • 状态目录缺失：警告灾难性状态丢失，提示重建目录，并提醒无法恢复丢失的数据。
  • 状态目录权限：验证可写性；提供权限修复（检测到 owner/group 不匹配时给出 chown 提示）。
  • macOS 云同步状态目录：当状态目录解析到 iCloud Drive（~/Library/Mobile Documents/com~apple~CloudDocs/...）或 ~/Library/CloudStorage/... 下时发出警告，因为云同步路径可能导致 I/O 变慢和锁/同步竞争。
  • Linux SD 或 eMMC 状态目录：当状态目录解析到 mmcblk* 挂载源时发出警告，因为 SD/eMMC 的随机 I/O 可能更慢且在会话和凭证写入下磨损更快。
  • 会话目录缺失：sessions/ 和会话存储目录是持久化历史、避免 ENOENT 崩溃所必需的。
  • 转录不匹配：当最近的会话条目有缺失的转录文件时发出警告。
  • 主会话 “1 行 JSONL”：当主转录只有一行时标记（历史没有在积累）。
  • 多个状态目录：当跨 home 目录存在多个 ~/.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) 沙箱镜像修复

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

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

Doctor 检测旧版 Gateway 服务（launchd/systemd/schtasks），提供移除并使用当前 Gateway 端口安装 OpenClaw 服务的选项。也能扫描多余的类 Gateway 服务并给出清理提示。按配置命名的 OpenClaw Gateway 服务被视为正式服务，不会被标记为”多余”。

9) 安全警告

当提供商对外开放 DM 但没有白名单，或策略配置存在风险时，doctor 发出警告。

10) systemd linger（Linux）

以 systemd 用户服务运行时，doctor 确保启用了 lingering，让 Gateway 在用户登出后继续运行。

11) Skills 状态

Doctor 打印当前工作区的 skills 快速摘要（可用/缺失/被阻止）。

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

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

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

12b) 只读 SecretRef 感知修复

部分修复流程需要检查已配置的凭证，同时不削弱运行时的快速失败行为。

  • openclaw doctor --fix 现在使用与 status 系列命令相同的只读 SecretRef 摘要模型进行定向配置修复。
  • 示例：Telegram allowFrom/groupAllowFrom 的 @username 修复会在可用时尝试使用已配置的 bot 凭证。
  • 如果 Telegram bot token 通过 SecretRef 配置但在当前命令路径下不可用，doctor 会报告凭证”已配置但不可用”并跳过自动解析，而非崩溃或错误报告 token 缺失。

13) Gateway 健康检查 + 重启

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

14) 频道状态警告

如果 Gateway 健康，doctor 执行频道状态探测并报告警告及建议修复。

15) Supervisor 配置审计 + 修复

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

说明：

  • openclaw doctor 在重写 supervisor 配置前会提示确认。
  • openclaw doctor --yes 接受默认的修复提示。
  • openclaw doctor --repair 免提示执行推荐修复。
  • openclaw doctor --repair --force 覆盖自定义 supervisor 配置。
  • 如果 token 认证需要 token 且 gateway.auth.token 由 SecretRef 管理，doctor 的服务安装/修复会验证 SecretRef 但不将解析后的明文 token 值持久化到 supervisor 服务环境元数据中。
  • 如果 token 认证需要 token 但配置的 token SecretRef 未解析，doctor 会阻止安装/修复并给出可操作的指导。
  • 如果同时配置了 gateway.auth.token 和 gateway.auth.password 但 gateway.auth.mode 未设置，doctor 会阻止安装/修复直到显式设置 mode。
  • 对于 Linux user-systemd 单元，doctor 的 token 漂移检查现在在比较服务认证元数据时会同时检查 Environment= 和 EnvironmentFile= 来源。
  • 你始终可以通过 openclaw gateway install --force 强制完全重写。

16) Gateway 运行时 + 端口诊断

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

17) Gateway 运行时最佳实践

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

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

Doctor 持久化所有配置变更并记录向导元数据以标记 doctor 运行。

19) 工作区提示（备份 + 记忆系统）

工作区记忆系统缺失时 doctor 会建议创建，工作区不在 git 下时给出备份提示。

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

arrow_back
上一页
Heartbeat
下一页
Logging
arrow_forward