Doctor（诊断）

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

openclaw doctor

#

openclaw doctor --yes

无需提示接受默认值（包括重启/服务/沙箱修复步骤，如适用）。

openclaw doctor --repair

无需提示应用推荐的修复（安全时修复+重启）。

openclaw doctor --repair --force

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

openclaw doctor --non-interactive

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

openclaw doctor --deep

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

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

cat ~/.openclaw/openclaw.json

- git 安装的可选运行前更新（仅交互模式）。

- UI 协议新鲜度检查（协议架构较新时重建控制 UI）。

- 健康检查+重启提示。

- 技能状态摘要（符合条件/缺失/已阻止）。

- 旧版值的配置规范化。

- OpenCode Zen 提供商覆盖警告（'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'models.providers.opencode'</code>'）。

- 旧版磁盘状态迁移（会话/代理目录/WhatsApp 认证）。

- 状态完整性和权限检查（会话、转录、状态目录）。

- 本地运行时配置文件权限检查（chmod 600）。

- 模型认证健康：检查 OAuth 过期，可刷新过期令牌，并报告认证配置文件的冷却/禁用状态。

- 额外工作区目录检测（'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/openclaw'</code>'）。

- 启用沙箱时的沙箱镜像修复。

- 旧版服务迁移和额外网关检测。

- 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。

- 渠道状态警告（从运行中的网关探测）。

- Supervisor 配置审计（launchd/systemd/schtasks）和可选修复。

- 网关运行时最佳实践检查（Node vs Bun，版本管理器路径）。

- 网关端口冲突诊断（默认 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>'）。

- 开放 DM 策略的安全警告。

- 未设置 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.auth.token'</code>' 时的网关认证警告（本地模式；提供令牌生成）。

- Linux 上的 systemd linger 检查。

- 源码安装检查（pnpm 工作区不匹配、缺少 UI 资源、缺少 tsx 二进制文件）。

- 写入更新的配置+向导元数据。

#

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

#

如果配置包含旧版值格式（例如没有渠道特定覆盖的 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.ackReaction'</code>'），doctor 会将其规范化为当前架构。

#

ReferenceGatewayDoctorPage.step06.p3

ReferenceGatewayDoctorPage.step06.p4

当配置包含已弃用的键时，其他命令将拒绝运行并要求您运行 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>'。

Doctor 将：

- 解释发现了哪些旧版键。

- 显示它应用的迁移。

- 用更新的架构重写 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/openclaw.json'</code>'。

Gateway 在启动时检测到异常的旧版配置格式时也会自动运行 doctor 迁移，因此旧配置无需人工干预即可修复。

当前迁移：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.allowFrom'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channels.whatsapp.allowFrom'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.requireMention'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channels.whatsapp/telegram/imessage.groups."*".requireMention'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.historyLimit'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.groupChat.historyLimit'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.mentionPatterns'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.groupChat.mentionPatterns'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.queue'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.queue'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.bindings'</code>' → 顶级 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.agents'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.defaultAgentId'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list[].default'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.agentToAgent'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.agentToAgent'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.transcribeAudio'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.media.audio.models'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings[].match.accountID'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings[].match.accountId'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'identity'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list[].identity'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agent.*'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.*'</code>' (tools/elevate/exec/sandbox/subagents)

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agent.model'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'allowedModels'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'modelAliases'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'modelFallbacks'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'imageModelFallbacks'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.models'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.model.primary/fallbacks'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.imageModel.primary/fallbacks'</code>'

#

如果您手动添加了 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'models.providers.opencode'</code>'（或 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'opencode-zen'</code>'），它会覆盖 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'@mariozechner/pi-ai'</code>' 中内置的 OpenCode Zen 目录。这可以强制所有模型使用单一 API 或零成本。Doctor 会警告您可以删除覆盖并恢复按模型的 API 路由+成本。

#

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

- 会话存储+转录：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/sessions/'</code>' 到 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agents/'<agentId>'/sessions/'</code>'

- 代理目录：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agent/'</code>' 到 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agents/'<agentId>'/agent/'</code>'

- WhatsApp 认证状态（Baileys）：

- 从旧版 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/credentials/*.json'</code>'（不包括 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'oauth.json'</code>'）

- 到 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/credentials/whatsapp/'<accountId>'/...'</code>'（默认账户 ID：'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'default'</code>'）

这些迁移是尽力而为且幂等的。Doctor 会警告它将所有旧文件夹保留为备份。Gateway/CLI 在启动时也会自动迁移旧版会话+代理目录，因此无需手动运行 doctor 即可将历史/认证/模型放置在按代理的路径中。WhatsApp 认证仅通过 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>' 有意迁移。

#

状态目录是运维的核心。如果它消失，会话、凭据、日志和配置将丢失（除非在其他地方备份）。

Doctor 检查：

- <strong>缺少状态目录</strong>：警告灾难性状态丢失，提示重新创建目录，提醒无法恢复丢失的数据。

- '<strong>'状态目录权限'</strong>'：验证可写，提供修复权限建议（如果检测到所有者/组不匹配，输出 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'chown'</code>' 提示）。

- '<strong>'缺少会话目录'</strong>'：'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'sessions/'</code>' 和会话存储目录保存历史记录，需要避免 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'ENOENT'</code>' 崩溃。

- <strong>转录不匹配</strong>：当最近的会话条目缺少转录文件时发出警告。

- <strong>主会话"单行 JSONL"</strong>：当主记录只有一行时标记（历史未累积）。

- '<strong>'多个状态目录'</strong>'：当主目录中存在多个 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw'</code>' 文件夹，或 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'OPENCLAW_STATE_DIR'</code>' 指向其他位置时发出警告（历史可能分散在安装之间）。

- '<strong>'远程模式提醒'</strong>'：如果 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.mode=remote'</code>'，Doctor 提醒在远程主机上运行（状态在那里）。

- '<strong>'配置文件权限'</strong>'：如果 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/openclaw.json'</code>' 存在且可被组/世界读取，建议收紧为 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'600'</code>'。

#

Doctor 检查认证存储中的 OAuth 配置文件，在令牌接近/已过期时发出警告，并可在安全时刷新它们。如果 Anthropic Claude 密码配置文件已过期，建议运行 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'claude setup-token'</code>'（或粘贴设置令牌）。刷新提示仅在交互式运行（TTY）时出现。'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--non-interactive'</code>' 跳过刷新尝试。

Doctor 还报告因以下原因暂时不可用的认证配置文件：

- 短期冷却（速率限制/超时/认证失败）

- 长期禁用期（计费/信用失败）

#

如果设置了 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.gmail.model'</code>'，Doctor 会根据模型目录和白名单验证模型引用，如果无法解析或不允许则发出警告。

#

如果启用了沙箱，Doctor 会检查 Docker 镜像，如果没有当前镜像，则提供构建或切换到当前镜像名称的建议。

#

Doctor 检测旧版网关服务（launchd/systemd/schtasks）并提供删除它们并在当前网关端口上安装 OpenClaw 服务的建议。它还可以扫描额外的类网关服务并打印清理提示。配置中命名的 OpenClaw 网关服务被视为一等公民，不会被标记为"额外"。

#

如果提供商在没有白名单的情况下对 DM 开放，或策略设置危险，Doctor 会发出警告。

#

如果作为 systemd 用户服务运行，Doctor 会检查 linger 是否已启用，以便网关在注销后保持活动状态。

#

Doctor 打印工作区中当前符合条件/缺失/已阻止技能的简要摘要。

#

如果本地网关缺少 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.auth'</code>'，Doctor 会发出警告并提供生成令牌的建议。使用 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --generate-gateway-token'</code>' 强制创建令牌以用于自动化。

#

Doctor 运行健康检查，如果不健康，在检查后提供重启网关的建议。

#

如果网关健康，Doctor 运行渠道状态探测并报告警告及建议的修复。

#

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

注意：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>' 在重写 supervisor 配置前会提示。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --yes'</code>' 接受默认修复提示。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --repair'</code>' 无提示应用推荐的修复。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --repair --force'</code>' 覆盖自定义 supervisor 配置。

- 您始终可以通过 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw gateway install --force'</code>' 强制完全重写。

#

Doctor 检查服务运行时（PID，上次退出状态），如果服务已安装但实际未运行则发出警告。它还检查网关端口（默认 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>'）上的端口冲突，报告可能的原因（网关已在运行，SSH 隧道）。

#

如果网关服务使用 Bun 或版本管理的 Node 路径运行，Doctor 会发出警告（'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'nvm'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'fnm'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'volta'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'asdf'</code>' 等）。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径可能会在升级后损坏，因为服务不加载 shell 初始化。Doctor 建议迁移到系统 Node 安装（如果有）（Homebrew/apt/choco）。

#

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

#

Doctor 建议在迷失时使用工作区内存系统，如果工作区尚未在 git 下，则打印备份提示。

有关工作区结构和 git 备份的完整指南，请参阅 '<a href="/concepts/agent-workspace" className="text-emerald-400 hover:text-emerald-300 transition-colors">'/concepts/agent-workspace'</a>'（推荐私有 GitHub 或 GitLab）。