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

详细行为和原�?

0) 可选更新（git 安装�?

如果�?git 签出�?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
  • 对于具有命名 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

2b) OpenCode Zen 提供商覆�?

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

3) 旧版状态迁移（磁盘布局�?

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

  • 会话存储 + 成绩单：
    • �?~/.openclaw/sessions/ �?~/.openclaw/agents/<agentId>/sessions/
  • 代理目录�?
    • �?~/.openclaw/agent/ �?~/.openclaw/agents/<agentId>/agent/
  • WhatsApp 认证状态（Baileys）：
    • 从旧�?~/.openclaw/credentials/*.json（除�?oauth.json�?
    • �?~/.openclaw/credentials/whatsapp/<accountId>/...（默认账�?ID：default�?

这些迁移是尽力而为且幂等的；当 doctor 留下任何旧版文件夹作为备份时 会发出警告。Gateway/CLI 也在启动时自动迁�? 旧版会话 + 代理目录，以便历�?认证/模型进入 每个代理路径，无需手动运行 doctor。WhatsApp 认证仅通过 openclaw doctor 迁移是有意为之的�?

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

状态目录是操作脑干。如果它消失了，您会失去 会话、凭据、日志和配置（除非您在其他地方有备份）�?

Doctor 检查：

  • **状态目录缺�?*：警告灾难性状态丢失，提示重新创建 目录，并提醒您无法恢复丢失的数据�?
  • **状态目录权�?*：验证可写性；提供修复权限 （并在检测到所有�?组不匹配时发�?chown 提示）�?
  • 会话目录缺失：sessions/ 和会话存储目录是 持久化历史和避免 ENOENT 崩溃所必需的�?
  • 成绩单不匹配：警告最近会话条目缺�? 成绩单文件�?
  • 主会�?单行 JSONL”：标记主成绩单只有一�? 时（历史未累积）�?
  • **多个状态目�?*：警告跨主目录存在多�?~/.openclaw 文件�? �?OPENCLAW_STATE_DIR 指向其他地方时（历史可能�? 安装之间分裂）�?
  • 远程模式提醒：如�?gateway.mode=remote，doctor 提醒您在远程主机上运行它（状态在那里）�?
  • 配置文件权限：警�?~/.openclaw/openclaw.json �? �?世界可读的，并提供收紧到 600�?

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

Doctor 检查认证存储中�?OAuth 配置文件，在令牌 即将过期/已过期时发出警告，并在安全时可以刷新它们。如�?Anthropic Claude Code 配置文件过时，它建议运行 claude 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 会发出警告�?

10) systemd linger（Linux�?

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

11) 技能状�?

Doctor 打印当前工作区符合条件的/缺失�?阻止的技能快速摘要�?

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

当本�?Gateway 上缺�?gateway.auth 时，Doctor 会发出警告并提供 生成令牌。使�?openclaw doctor --generate-gateway-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 配置�?
  • 您始终可以通过 openclaw gateway install --force 强制完全重写�?

16) Gateway 运行�?+ 端口诊断

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

17) Gateway 运行时最佳实�?

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

18) 配置写入 + 向导元数�?

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

19) 工作区提示（备份 + 内存系统�?

当缺少时，Doctor 建议工作区内存系统，并在工作�? 不在 git 下时打印备份提示�?

有关工作区结构和 git 备份的完整指南，请参�? /concepts/agent-workspace（推荐私�?GitHub �?GitLab）�?