OpenClaw Doctor命令使用指南

OpenClaw Doctor（命令 openclaw doctor）是 OpenClaw 官方自带的修复与迁移工具，核心作用是检测并修复过时的配置、状态异常，检查系统运行健康状况，同时提供清晰可操作的修复步骤，帮你快速解决使用中的各类问题。

一、OpenClaw Doctor快速上手（基础用法）

最简洁的使用方式，直接运行命令即可启动工具，会交互式提示检测结果和修复建议：

openclaw doctor

二、OpenClaw Doctor自动化/无头模式（适配运维/脚本）

针对无需手动交互的场景（如自动化巡检、远程维护），提供多种便捷参数，无需手动确认即可完成操作：

自动接受所有默认修复建议（含重启服务、沙箱修复等）：

openclaw doctor –yes

自动应用推荐的安全修复（无需提示，修复后自动重启相关服务）：

openclaw doctor –repair

应用激进修复（强制覆盖自定义的 supervisor 配置，适合配置错乱场景）：

openclaw doctor –repair –force

无交互安全迁移（仅规范化配置、迁移磁盘状态，跳过需人工确认的重启、服务操作）：

openclaw doctor –non-interactive

注：检测到遗留状态需要迁移时，该模式会自动运行。

深度扫描（检测系统中额外的网关安装，适配 launchd、systemd 等服务）：

openclaw doctor –deep

温馨提示：如果想在工具修改配置前，先查看当前配置内容，可运行命令：

cat ~/.openclaw/openclaw.json

三、OpenClaw Doctor核心功能介绍

OpenClaw Doctor 功能全面，覆盖配置、状态、服务、认证等全场景检测与修复，具体包括：

1、Git 安装预检更新（仅交互模式下提供，可选择更新工具版本）；

2、UI 协议新鲜度检查（当协议架构更新时，自动重建 Control UI）；

3、系统健康检查（检测异常并提示重启）；

4、Skills 状态汇总（显示合格、缺失、被阻止的 Skills）；

5、配置规范化（修复过时的遗留配置值，适配当前版本架构）；

6、OpenCode Zen 提供商覆盖警告（避免手动配置覆盖内置目录，导致模型调用异常）；

7、遗留磁盘状态迁移（迁移旧版会话、智能体、WhatsApp 认证等目录到新路径）；

8、状态完整性与权限检查（确保会话、转录、配置目录可正常读写，权限合规）；

9、模型认证健康检查（检测 OAuth 令牌过期，可刷新即将过期的令牌，报告认证状态）；

10、额外工作区目录检测（提醒存在多个工作区可能导致的历史记录分割问题）；

11、沙箱镜像修复（启用沙箱时，检测并修复 Docker 镜像缺失问题）；

12、遗留服务迁移与额外网关检测（清理旧版服务，提示安装当前版本网关）；

13、网关运行时检查（检测服务是否安装但未运行、端口冲突等问题）；

14、渠道状态警告（从运行中的网关探测渠道异常，提供修复建议）；

15、Supervisor 配置审计与修复（检查 launchd/systemd/schtasks 配置，修复过时设置）；

16、网关运行时最佳实践检查（提醒 Node/Bun 运行环境可能存在的问题）；

17、网关端口冲突诊断（检测默认端口 18789 是否被占用）；

18、安全警告（提醒私信开放策略、网关认证缺失等安全风险）；

19、Linux 系统 systemd linger 检查（确保网关在用户注销后仍能正常运行）；

20、源码安装检查（检测 pnpm 工作区、UI 资源、tsx 二进制文件是否缺失）；

21、配置持久化（写入所有修改后的配置和向导元数据，确保生效）。

四、OpenClaw Doctor详细功能说明

1、可选更新（仅 Git 安装版）

如果你的 OpenClaw 是通过 Git 检出安装的，且在交互模式下运行 Doctor，工具会先提示你是否更新（包括 fetch、rebase、build 操作），方便你快速升级到最新版本。

2、配置规范化与遗留键迁移

如果你的配置文件包含旧版格式（比如没有特定渠道覆盖的 messages.ackReaction），Doctor 会自动将其转换为当前版本的规范格式；若配置中包含已废弃的键，其他命令会拒绝运行，必须通过 openclaw doctor 迁移修复。

工具会清晰说明：发现了哪些遗留键、执行了哪些迁移操作，然后用新版本架构重写配置文件 ~/.openclaw/openclaw.json。

当前支持的迁移项（旧键 → 新键）：

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

补充：OpenCode Zen 提供商覆盖警告

如果手动添加了 models.providers.opencode（或 opencode-zen），会覆盖工具内置的 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）

注：迁移过程是幂等的（重复运行不会出错），工具会保留旧文件夹作为备份并发出提醒；网关 / CLI 启动时会自动迁移会话和智能体目录，无需手动操作，但 WhatsApp 认证仅能通过 openclaw doctor 迁移。

4、状态完整性检查（核心操作，避免数据丢失）

状态目录（~/.openclaw）是 OpenClaw 运行的核心，包含会话、凭据、日志和配置，一旦丢失会导致数据不可恢复。Doctor 会重点检查以下内容：

状态目录缺失：提示灾难性数据丢失，建议重新创建目录，并说明无法恢复已丢失的数据；
目录权限：验证目录是否可写，若权限异常，提供修复选项（如 chown 调整所有者 / 组）；
会话目录缺失：提醒缺少会话存储目录，避免因目录缺失导致程序崩溃；
转录不匹配：警告最近的会话条目缺少转录文件，可能影响历史记录完整性；
主会话异常：标记主转录仅 1 行的情况（说明历史记录未正常累积）；
多个状态目录：提醒存在多个 ~/.openclaw 文件夹或 OPENCLAW_STATE_DIR 指向异常，可能导致历史记录分割；
远程模式提醒：若 gateway.mode=remote，提示需在远程主机上运行 Doctor（状态存储在远程）；
配置文件权限：若 ~/.openclaw/openclaw.json 对其他用户可读，提醒收紧权限到 600（仅当前用户可读写）。

5、模型认证健康检查（避免授权失效）

Doctor 会检查认证存储中的 OAuth 配置文件，当令牌即将过期或已过期时发出警告，并在安全场景下提供刷新选项；若 Anthropic Claude Code 配置文件过期，会提示运行 claude setup-token 重新生成令牌或粘贴新令牌。

同时，工具会报告暂时无法使用的认证配置文件，原因包括：

短暂冷却（如速率限制、超时、认证失败）；
长期禁用（如账单异常、信用额度不足）。

注：令牌刷新提示仅在交互式终端（TTY）中出现，–non-interactive 模式会跳过刷新尝试。

6、沙箱镜像修复

当启用沙箱功能时，Doctor 会检查 Docker 镜像是否存在，若镜像缺失，会提供两种修复选项：构建新镜像，或切换到旧版镜像名称。

7、网关服务迁移与清理

工具会检测系统中遗留的网关服务（如旧版 launchd、systemd、schtasks 服务），提供删除旧服务、安装当前版本网关服务的选项；同时扫描额外的类网关服务，给出清理提示（OpenClaw 官方命名的网关服务不会被标记为 “额外”）。

8、安全警告

当模型提供商对私信开放但未设置允许列表，或策略配置存在安全风险时，Doctor 会及时发出警告，提醒你调整配置，避免安全隐患。

9、systemd linger 检查（仅 Linux 系统）

如果网关通过 systemd 用户服务运行，Doctor 会确保启用 linger 功能，这样即使用户注销，网关也能持续运行，避免服务中断。

10、 Skills状态检查

工具会快速汇总当前工作区的 Skills 状态，清晰显示哪些 Skills 合格、哪些缺失、哪些被阻止，方便你快速排查功能异常。

11、网关认证检查（本地令牌）

如果本地网关缺少 gateway.auth 配置（本地模式），Doctor 会发出警告，并提供生成令牌的选项；自动化场景中，可使用 openclaw doctor –generate-gateway-token 强制创建令牌。

12、网关健康检查与重启

Doctor 会运行网关健康检测，若发现网关运行异常（如服务未响应），会提供重启网关的选项，帮你快速恢复服务。

13、渠道状态警告

若网关运行正常，工具会进一步探测各渠道（如 WhatsApp、Telegram）的状态，报告异常问题，并给出针对性的修复建议。

14、Supervisor 配置审计与修复

检查系统中已安装的 supervisor 配置（launchd、systemd、schtasks），是否缺少或存在过时的默认设置（如 systemd 的 network-online 依赖、重启延迟）。若发现不匹配，会建议更新，并可自动将服务文件 / 任务重写为当前默认配置。

注意事项：

重写 supervisor 配置前，工具会主动提示确认；
openclaw doctor –yes 会自动接受所有修复提示；
openclaw doctor –repair 会直接应用推荐修复，无需提示；
openclaw doctor –repair –force 会强制覆盖自定义的 supervisor 配置；
也可通过 openclaw gateway install –force 强制重写所有网关服务配置。

15、网关运行时与端口诊断

检查网关服务运行状态（如 PID、最后退出状态），若服务已安装但未运行，发出警告；
检测网关默认端口（18789）是否存在冲突，报告可能的原因。

16、网关运行时最佳实践提示

当网关服务在 Bun 或版本管理的 Node 路径（如 nvm、fnm、volta、asdf）上运行时，工具会发出警告。原因是：WhatsApp、Telegram 渠道需要依赖 Node，而版本管理器路径可能在升级后失效（服务无法加载 shell 初始化配置）。若有系统级 Node 安装（如 Homebrew、apt、choco 安装），工具会提供迁移选项。

17、配置写入与向导元数据

所有通过 Doctor 修改的配置，都会被持久化保存，同时工具会标记向导元数据，记录本次 Doctor 运行的相关信息，方便后续排查问题。