ClawCN - OpenClaw 中文版

主题

Doctor ​

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

快速入门 ​

bash
openclaw doctor

无头模式 / 自动化 ​

bash
openclaw doctor --yes

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

bash
openclaw doctor --repair

在不提示的情况下应用推荐的修复(在安全的情况下修复 + 重启)。

bash
openclaw doctor --repair --force

也应用激进修复(覆盖自定义的 supervisor 配置)。

bash
openclaw doctor --non-interactive

无提示运行,仅应用安全迁移(配置规范化 + 磁盘状态移动)。跳过需要人工确认的重启/服务/沙箱操作。 检测到遗留状态迁移时会自动运行。

bash
openclaw doctor --deep

扫描系统服务以查找额外的网关安装(launchd/systemd/schtasks)。

如果您想在写入之前查看更改,请先打开配置文件:

bash
cat ~/.openclaw/openclaw.json

功能概述 ​

  • Git 安装的可选预检更新(仅限交互模式)。
  • UI 协议新鲜度检查(当协议架构较新时重建 Control UI)。
  • 健康检查 + 重启提示。
  • Skills 状态摘要(合格/缺失/被阻止)。
  • 遗留值的配置规范化。
  • OpenCode Zen 提供商覆盖警告(models.providers.opencode)。
  • 遗留磁盘状态迁移(会话/代理目录/WhatsApp 认证)。
  • 状态完整性和权限检查(会话、转录、状态目录)。
  • 本地运行时的配置文件权限检查(chmod 600)。
  • 模型认证健康:检查 OAuth 过期,可刷新即将过期的令牌,并报告认证配置文件冷却/禁用状态。
  • 额外工作区目录检测(~/openclaw)。
  • 启用沙箱时的沙箱镜像修复。
  • 遗留服务迁移和额外网关检测。
  • 网关运行时检查(服务已安装但未运行;缓存的 launchd 标签)。
  • 通道状态警告(从运行中的网关探测)。
  • Supervisor 配置审计(launchd/systemd/schtasks)及可选修复。
  • 网关运行时最佳实践检查(Node vs Bun、版本管理器路径)。
  • 网关端口冲突诊断(默认 18789)。
  • 开放 DM 策略的安全警告。
  • 未设置 gateway.auth.token 时的网关认证警告(本地模式;提供令牌生成)。
  • 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。

网关在启动时检测到遗留配置格式时也会自动运行 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/
  • 代理目录:
    • 从 ~/.openclaw/agent/ 到 ~/.openclaw/agents/<agentId>/agent/
  • WhatsApp 认证状态(Baileys):
    • 从遗留 ~/.openclaw/credentials/*.json(除了 oauth.json)
    • 到 ~/.openclaw/credentials/whatsapp/<accountId>/...(默认账户 ID:default)

这些迁移是尽力而为且幂等的;当 doctor 将任何遗留文件夹作为备份保留时,会发出警告。网关/CLI 也会在启动时自动迁移遗留的会话 + 代理目录,以便历史记录/认证/模型落在每个代理的路径中,无需手动运行 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(或粘贴设置令牌)。刷新提示仅在交互式运行(TTY)时出现;--non-interactive 跳过刷新尝试。

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

  • 短暂冷却(速率限制/超时/认证失败)
  • 较长禁用(账单/信用失败)

6) Hooks 模型验证 ​

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

7) 沙箱镜像修复 ​

启用沙箱时,doctor 检查 Docker 镜像,并在当前镜像缺失时提供构建或切换到遗留名称的选项。

8) 网关服务迁移和清理提示 ​

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

9) 安全警告 ​

当提供商对 DM 开放而没有允许列表,或者策略以危险方式配置时,Doctor 会发出警告。

10) systemd linger(Linux) ​

如果作为 systemd 用户服务运行,doctor 确保启用了 lingering,以便网关在注销后保持活动状态。

11) Skills 状态 ​

Doctor 为当前工作区打印合格/缺失/被阻止 skills 的快速摘要。

12) 网关认证检查(本地令牌) ​

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

13) 网关健康检查 + 重启 ​

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

14) 通道状态警告 ​

如果网关健康,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) 网关运行时 + 端口诊断 ​

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

17) 网关运行时最佳实践 ​

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

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

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

19) 工作区提示(备份 + 记忆系统) ​

当缺少工作区记忆系统时,Doctor 会建议一个,如果工作区尚未处于 git 管理下,则打印备份提示。

有关工作区结构和 git 备份的完整指南(推荐私有 GitHub 或 GitLab),请参阅 /concepts/agent-workspace。