Skip to main content
openclaw doctor 是 OpenClaw 的修复和迁移工具。它会修复过时的配置和状态、检查健康状况，并提供可执行的修复步骤。

​
快速开始

​
无头和自动化模式

在不提示的情况下接受默认值（如适用，包括重启／服务／沙箱修复步骤）。
要在写入前查看更改，请先打开配置文件：

​
只读 lint 模式

openclaw doctor --lint 是 openclaw doctor --fix 面向自动化的对应模式。它们共享同一个 Doctor 规则注册表，但选择或执行规则的方式并不相同： 默认情况下，doctor --lint 运行广泛且安全的自动化配置文件：检查静态、本地，并且对 CI 或预检输出有用的项目。它会跳过建议性检查、依赖环境的检查、依赖实时服务的检查、账户／工作区清单检查，以及历史清理检查等选择性检查。如果需要完整的已注册 lint 审计（包括这些选择性检查），请使用 doctor --lint --all；如果需要针对特定检查，请使用 --only <id>。 doctor --fix 不使用 lint 默认配置文件，也不接受 --all。它会运行 Doctor 的有序修复流程：现代健康检查可以提供可选的 repair() 实现，而较旧的领域仍使用其传统的 Doctor 修复流程。某些 lint 发现仅用于诊断，因此某项检查出现在 --lint --all 中，并不意味着 --fix 会修改该领域。该契约将 detect()（报告发现）与 repair()（报告变更／差异／副作用）分离开来，从而为未来的 doctor --fix --dry-run 保留了实现空间，而不会将 lint 检查变成变更规划器。 一些内置检查在内部默认禁用，这样它们仍可用于 --all、--only 和 Doctor 修复流程，同时不会成为默认 doctor --lint 自动化配置文件的一部分。发现的严重性仍会按每条发现分别输出（info、warning 或 error）；默认选择并不代表严重性级别。
JSON 输出字段：
  • ok：是否有任何发现达到所选严重性阈值
  • checksRun／checksSkipped：数量（因配置文件、--only 或 --skip 而跳过）
  • findings：结构化诊断信息，包含 checkId、severity、message，以及可选的 path、line、column、ocPath、source、target、requirement、fixHint
退出码： 标志：
  • --severity-min info|warning|error（默认值为 warning）：控制输出内容以及导致非零退出码的内容。
  • --all：运行所有已注册的 lint 检查，包括默认自动化集合中排除的选择性检查。
  • --only <id>（可重复）：仅运行指定检查 ID；未知 ID 将作为错误发现报告。
  • --skip <id>（可重复）：排除某项检查，同时保持其余运行继续进行。
  • --json、--severity-min、--all、--only 和 --skip 要求使用 --lint；普通的 openclaw doctor 和 --fix 运行会拒绝这些选项。

​
它做什么（摘要）

  • Git 安装的可选预更新（仅限交互模式）。
  • UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
  • 健康检查＋重启提示。
  • 仅报告问题的 skill 和 plugin 提示；正常的清单保留在 openclaw skills check 和 openclaw plugins list 中。
  • 针对旧版值形状的配置规范化。
  • 将旧版扁平 talk.* 字段中的 Talk 配置迁移到 talk.provider＋talk.providers.<provider>。
  • 浏览器迁移检查：旧版 Chrome 扩展配置、自有 native-bootstrap 注册漂移，以及 Chrome MCP 就绪状态。
  • OpenCode provider 覆盖警告（models.providers.opencode／opencode-zen／opencode-go）。
  • 旧版 OpenAI Codex provider/profile 迁移（openai-codex → openai），以及针对过时 models.providers.openai-codex 的遮蔽警告。
  • OpenAI Codex OAuth profile 的 OAuth TLS 前置条件检查。
  • 当 plugins.allow 具有限制性，但工具策略仍要求通配符工具或 plugin 所有的工具时，发出 Plugin／工具 allowlist 警告。
  • 旧版磁盘状态迁移（sessions／agent 目录／WhatsApp auth）。
  • 已弃用的 QMD memory 配置和派生 workspace 清理；请参阅从 QMD 迁移。
  • 旧版 plugin manifest contract key 迁移（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders → contracts）。
  • 旧版 cron store 迁移（jobId、schedule.cron、顶层 delivery／payload 字段、payload provider、notify: true webhook 回退任务）。
  • 将旧版 workspace TOOLS.md 迁移到 AGENTS.md 的 ## Tools 部分，并在移除原文件前将其归档到 state 目录下。
  • 修复 Codex CLI runtime pin（agentRuntime.id: "codex-cli" → "codex"），涵盖 agents.defaults、agents.entries.* 和 models.providers.*（包括单模型条目）。
  • 在 plugin 已启用时清理过时的 plugin 配置；当 plugins.enabled=false 时，过时的 plugin 引用会作为无效的隔离配置保留。
  • 检查 session lock 文件并清理过时的 lock。
  • 修复受影响的 2026.4.24 构建所创建的重复 prompt-rewrite 分支对应的 session transcript。
  • 检测卡住的主 session 和 subagent 重启恢复 tombstone。Doctor 会报告被阻塞的 session，并且只修复与现有 tombstone 冲突的过时 aborted 标记；不会重新启用自动恢复。
  • 状态完整性和权限检查（sessions、transcripts、state 目录）。
  • 在本地运行时检查配置文件权限（chmod 600）。
  • Model auth 健康检查：检查 OAuth 过期状态，可刷新即将过期的 token，并报告 auth-profile 冷却／禁用状态。
  • 在启用 sandboxing 时修复 sandbox image。
  • 旧版服务迁移和额外 Gateway 检测。
  • Matrix channel 旧版状态迁移（在 --fix／--repair 模式下）。
  • Gateway runtime 检查（服务已安装但未运行；缓存的 launchd label）。
  • Channel 状态警告（从正在运行的 Gateway 探测）。
  • Channel 专属权限检查位于 openclaw channels capabilities 下；例如，Discord voice channel 权限通过 openclaw channels capabilities --channel discord --target channel:<channel-id> 进行审计。
  • 检查 WhatsApp 在 Gateway event-loop 健康状况下降且本地 TUI client 仍在运行时的响应能力；--fix 只会停止已验证的本地 TUI client。
  • 修复旧版 primary model、fallback、image／video generation model、heartbeat／subagent／compaction override、hook、channel model override 和 session route pin 中的 Codex 路由 openai-codex/* model ref；--fix 会将其重写为 openai/*，把 openai-codex:* auth profile／顺序迁移到 openai:*，移除过时的 session／whole-agent runtime pin，并让修复后的有效路由决定 Codex 是否兼容。
  • Supervisor 配置审计（launchd／systemd／schtasks），可选择修复。
  • 清理 Gateway 服务中嵌入的 proxy 环境：这些服务在安装或更新期间捕获了 shell 的 HTTP_PROXY／HTTPS_PROXY／NO_PROXY 值。
  • Gateway runtime 检查（不受支持的旧版 Bun 服务、版本管理器路径）。
  • Gateway 端口冲突诊断（默认端口 18789）。
  • 开放 DM 策略的安全警告。
  • 本地 token 模式的 Gateway 认证检查（当不存在 token 来源时提供生成 token；不会覆盖 token SecretRef 配置）。
  • 设备配对问题检测（待处理的首次配对请求、待处理的角色／范围升级、陈旧的本地 device-token 缓存漂移，以及已配对记录的认证漂移）。
  • 在 Linux 上检查 systemd linger。
  • Workspace bootstrap 文件大小检查（针对上下文文件的截断／接近限制警告）。
  • 检查默认 agent 的 Skills 就绪状态；报告缺少 bin、env、配置或 OS 要求的 allowed skills，并且 --fix 可以在 skills.entries 中禁用不可用的 skill。
  • Shell 补全状态检查以及自动安装／升级。
  • Memory search embedding provider 就绪状态检查（本地 model 或远程 API key）。
  • Source install 检查（pnpm workspace 不匹配、缺少 UI 资源、缺少 tsx binary）。
  • 写入更新后的配置＋wizard metadata。

​
Dreams UI 回填和重置

The Control UI Dreams scene includes Backfill、Reset、and Clear Grounded actions for the grounded dreaming workflow。These use gateway doctor-style RPC methods but are not part of openclaw doctor CLI repair/migration。 None of these edit MEMORY.md、run full doctor migrations、or stage grounded candidates into the live short-term promotion store on their own。To feed grounded historical replay into the normal deep promotion lane，use the CLI flow instead：
That stages grounded durable candidates into the short-term dreaming store while DREAMS.md stays the review surface。

​
详细行为和原理

如果这是一个 git checkout，并且 doctor 以交互方式运行，它会在执行 doctor 前提供更新（fetch/rebase/build）的选项。
Doctor 会将旧版值形状规范化为当前 schema。当前 Talk 语音配置为 talk.provider + talk.providers.<provider>，实时语音配置位于 talk.realtime.* 下。Doctor 会将旧的 talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey 形状重写到 provider 映射中，并将旧版顶层实时选择器（talk.mode、talk.transport、talk.brain、talk.model、talk.voice）重写到 talk.realtime 中。当 plugins.allow 非空且工具策略使用通配符或由插件拥有的工具条目时，Doctor 还会发出警告。tools.allow: ["*"] 只匹配实际加载的插件中的工具；它不会绕过专属插件 allowlist。
当配置包含已弃用且存在有效迁移的键时，其他命令会拒绝运行，并要求你运行 openclaw doctor。Doctor 会解释发现了哪些旧键，显示它应用的迁移，并使用更新后的 schema 重写 ~/.openclaw/openclaw.json。Gateway 启动会拒绝旧版配置格式，并要求你运行 openclaw doctor --fix；它不会在启动时重写 openclaw.json。Cron 任务存储迁移也由 openclaw doctor --fix 处理。
Doctor 只会在某个键退役后的大约两个月内提供自动迁移。更早的旧键（例如最初的 routing.queue、routing.bindings、routing.agents/defaultAgentId、 routing.transcribeAudio、顶层 agent.*，或多 agent 配置形状之前的顶层 identity）不再有迁移路径；现在使用这些键的配置会验证失败，而不是被重写。在 doctor 可以继续之前，请根据当前配置参考手动修复这些键。
有效迁移：
上述 plugins.entries.voice-call.config.* 行由 Voice Call 插件自身在每次配置加载时规范化，而不是由 openclaw doctor 规范化。该插件还会记录一条指向 openclaw doctor --fix 的启动警告，但 doctor 当前不会针对这些键重写 openclaw.json；运行时实际应用更改的是插件自身的规范化逻辑。
多账号频道的账号默认值指导：
  • 如果配置了两个或更多 channels.<channel>.accounts 条目，但没有 channels.<channel>.defaultAccount 或 accounts.default，doctor 会警告回退路由可能选择到意外的账号。
  • 如果 channels.<channel>.defaultAccount 被设置为未知的账号 ID，doctor 会警告并列出已配置的账号 ID。
如果你在匹配的官方外部插件已安装并启用时，手动添加了 models.providers.opencode、opencode-zen 或 opencode-go，它会覆盖该插件提供的目录。这可能会强制模型使用错误的 API，或将成本归零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型进行的 API 路由和成本计算。如果没有匹配的插件，该条目仍是有效的独立自定义 provider。
如果扩展驱动配置仍携带已退役的 relay cdpUrl，doctor 会在保留 driver: "extension" 的同时移除该 URL；当前扩展 relay 会自行管理其端点。Doctor 还会移除已退役的 browser.relayBindHost 设置。当启用 browser.extensionRelay.allowLegacyAuth 时，Doctor 会发出警告。请将配对的 Chrome 扩展和外部 CDP 客户端升级到 Browser Relay Authentication v2，然后将该标志设置为 false。V2 客户端不会降级到旧版身份验证。当稳定版 Chrome 扩展副本和所属的 native-host 注册已存在时，doctor 会报告注册漂移。openclaw doctor --fix 可能会修复该所属注册，但它绝不会为每个 OpenClaw 用户安装 host，也绝不会覆盖同名的外部 manifest 或 launcher。首次设置请使用 openclaw browser extension install。当使用 defaultProfile: "user" 或已配置的 existing-session profile 时，Doctor 还会审计主机本地的 Chrome MCP 路径：
  • 检查默认自动连接配置下，Google Chrome 是否安装在同一台主机上
  • 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告
  • 提醒你在浏览器 inspect 页面中启用远程调试（例如 chrome://inspect/#remote-debugging、brave://inspect/#remote-debugging 或 edge://inspect/#remote-debugging）
Doctor 无法代你启用 Chrome 端的设置。主机本地 Chrome MCP 仍要求 gateway/node 主机上存在基于 Chromium 的 144+ 浏览器，在本地运行，并启用远程调试，同时在浏览器中批准首次 attach 的同意提示。此处的就绪检查仅涵盖本地 attach 前置条件。Existing-session 保留当前 Chrome MCP 路由限制；responsebody、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP profile。此检查不适用于 Docker、sandbox、remote-browser 或其他无头流程，这些流程继续使用原始 CDP。
当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否验证证书链。如果探测因证书错误失败（例如 UNABLE_TO_GET_ISSUER_CERT_LOCALLY、证书过期或自签名证书），doctor 会打印平台特定的修复指导。在使用 Homebrew Node 的 macOS 上，通常的修复方式是 brew postinstall ca-certificates。使用 --deep 时，即使 gateway 健康，探测也会运行。
如果你之前在 models.providers.openai-codex 下添加了旧版 OpenAI transport 设置，它们可能会遮蔽内置的 Codex OAuth provider 路径。当 Doctor 发现这些旧 transport 设置与 Codex OAuth 同时存在时，会发出警告，以便你移除或重写过时的 transport 覆盖并恢复当前的路由行为。自定义代理和仅包含 header 的覆盖仍受支持，不会触发此警告，但这些由用户编写的请求路由不符合隐式 Codex 选择条件。
Doctor 会检查旧版 openai-codex/* 模型引用。原生 Codex harness 路由使用规范的 openai/* 模型引用，但仅有此前缀绝不会选择 Codex。当运行时策略未设置或为 auto 时，只有精确的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由，且没有用户编写的请求覆盖时，才符合条件。请参阅 OpenAI implicit agent runtime。在 --fix / --repair 模式下，doctor 会重写受影响的默认 agent 和按 agent 引用，包括主模型、回退、图像/视频生成模型、heartbeat/subagent/compaction 覆盖、hooks、频道模型覆盖以及陈旧的持久化会话路由状态：
  • openai-codex/gpt-* 变为 openai/gpt-*。
  • Codex 意图会移动到针对 provider/model 的 agentRuntime.id: "codex" 条目，用于修复后的 agent 模型引用。
  • 陈旧的整个 agent 运行时配置和持久化会话运行时固定值会被移除，因为运行时选择以 provider/model 为范围。
  • 除非修复后的旧模型引用需要 Codex 路由来保留旧的身份验证路径，否则现有 provider/model 运行时策略会被保留。
  • 现有模型回退列表会被保留，并重写其中的旧版条目；复制的按模型设置会从旧键移动到规范的 openai/* 键。
  • 持久化会话的 modelProvider/providerOverride、model/modelOverride、回退通知和 auth-profile 固定值会在所有已发现的 agent 会话存储中修复。
  • Doctor 会单独修复过时的 agentRuntime.id: "codex-cli" 固定值（这是一个独立的旧版运行时 ID），将其在 agents.defaults、agents.entries.* 和 models.providers.* 模型条目中改为 "codex"。
  • /codex ... 表示“从聊天中控制或绑定原生 Codex 对话”。
  • /acp ... 或 runtime: "acp" 表示“使用外部 ACP/acpx 适配器”。
当你把已配置模型或运行时从某个插件拥有的 route（例如 Codex）迁移走后，Doctor 还会扫描已发现的 agent 会话存储中的陈旧自动创建 route 状态。openclaw doctor --fix 可以清除自动创建的陈旧状态，例如 modelOverrideSource: "auto" 模型 pin、运行时模型元数据、固定的 harness id、CLI 会话绑定，以及在其所属 route 不再配置时的自动 auth-profile 覆盖。显式用户选择或旧的会话模型选择会被报告出来供人工审查，并保持不变；如果该 route 不再被需要，可通过 /model ...、/new 切换，或重置会话。
Doctor 可以将旧的磁盘布局迁移到当前结构：
  • Sessions store + transcripts：从 ~/.openclaw/sessions/ 到 ~/.openclaw/agents/<agentId>/sessions/
  • Agent dir：从 ~/.openclaw/agent/ 到 ~/.openclaw/agents/<agentId>/agent/
  • WhatsApp auth state（Baileys）：从旧版 ~/.openclaw/credentials/*.json（oauth.json 除外）到 ~/.openclaw/credentials/whatsapp/<accountId>/...（默认账号 ID：default）
  • Signed device identity：从 ~/.openclaw/identity/device.json 进入 state/openclaw.sqlite 中的 primary device_identities 行；单独的 device-auth 文件保持不变
这些迁移是尽力而为且幂等的；当 doctor 将任何旧文件夹作为备份保留时，会发出警告。Gateway/CLI 也会在启动时自动迁移旧版 sessions + agent dir，使历史记录、身份验证和模型进入按 agent 划分的路径，无需手动运行 doctor。WhatsApp 身份验证仅通过 openclaw doctor 迁移，这是有意的。Talk provider/provider-map 规范化会按结构相等性进行比较，因此仅键顺序不同不再触发重复的无操作 doctor --fix 更改。
Doctor 会扫描所有已安装的插件 manifest，查找已弃用的顶层 capability 键（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders）。发现后，它会提供将这些键移动到 contracts 对象并原地重写 manifest 文件的选项。此迁移是幂等的；如果 contracts 已包含相同值，则会移除旧键，而不会重复数据。
Doctor 还会在将规范行导入 SQLite 之前，检查旧版 cron 任务存储（~/.openclaw/cron/jobs.json）中的旧任务形状。当前 cron 清理包括：
  • jobId → id
  • schedule.cron → schedule.expr
  • 顶层 payload 字段（message、model、thinking……）→ payload
  • 顶层 delivery 字段（deliver、channel、to、provider……）→ delivery
  • payload 中的 provider delivery 别名 → 明确的 delivery.channel
  • 旧版 notify: true webhook 回退任务 → 当已退役的原始 cron.webhook 值有效时，转换为明确的 webhook delivery；announce 任务保留其聊天 delivery，并获得 delivery.completionDestination。随后 Doctor 会移除旧配置键。如果没有可用的旧版 webhook，不指向目标的任务会移除无效的顶层 notify 标记（现有 delivery，包括 announce，会被保留），因为运行时 delivery 从不读取该标记。
Gateway 还会在加载时清理格式错误的 cron 行，使有效任务继续运行。格式错误的行会在从活动调度中移除它们的同一事务中，被隔离到共享 SQLite 状态数据库；doctor 会报告这些记录，并导入旧版本留下的 jobs-quarantine.json sidecar 文件。Gateway 启动会规范化运行时投影并忽略顶层 notify 标记，但会将持久化 cron 状态留给 doctor 修复。对于没有迁移目标的任务（delivery.mode 为 none/缺失、旧版 webhook 目标不可用，或已有 announce/chat delivery），Doctor 会移除无效标记并保持现有 delivery 不变，因此重复运行 doctor --fix 时不会再针对同一任务重复发出警告。在 Linux 上，doctor 还会在用户的 crontab 仍调用旧版 ~/.openclaw/bin/ensure-whatsapp.sh 时发出警告。这个宿主机本地脚本不受当前 OpenClaw 维护，而且当 cron 无法访问 systemd 用户总线时，可能会向 ~/.openclaw/logs/whatsapp-health.log 写入虚假的 Gateway inactive 消息。请使用 crontab -e 删除过时的 crontab 条目；当前健康检查请使用 openclaw channels status --probe、openclaw doctor 和 openclaw gateway status。
Doctor 会扫描每个 agent 会话目录，查找会话异常退出后遗留的过时写锁文件。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍存活、锁的年龄，以及是否被认为已过时（PID 已终止、所有者元数据格式错误、超过 30 分钟，或已证明存活的 PID 属于非 OpenClaw 进程）。在 --fix / --repair 模式下，它会自动移除所有者已终止、孤立、已复用、旧格式错误或属于非 OpenClaw 进程的锁。仍由存活的 OpenClaw 进程持有的旧锁会被报告但保留，以避免 doctor 截断活动的 transcript writer。
Doctor 会扫描 agent 会话 JSONL 文件，查找由 2026.4.24 prompt transcript rewrite bug 造成的重复分支结构：一个带有 OpenClaw 内部运行时上下文的已放弃 user turn，以及一个包含相同可见用户提示的活动同级分支。在 --fix / --repair 模式下，doctor 会在原文件旁边为每个受影响文件创建备份，并将转写重写为活动分支，这样 gateway 历史和 memory 读取器就不再会看到重复 turn。
State directory 是运行时的核心。如果它消失，除非你在其他地方有备份，否则会丢失 sessions、凭据、日志和配置。Doctor 会检查：
  • State dir missing：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。
  • State dir permissions：验证目录是否可写；提供修复权限的选项（检测到所有者/组不匹配时还会给出 chown 提示）。
  • macOS cloud-synced state dir：当状态路径位于 iCloud Drive（~/Library/Mobile Documents/com~apple~CloudDocs/...）或 ~/Library/CloudStorage/... 下时发出警告，因为同步路径可能导致 I/O 变慢以及锁/同步竞争。
  • Linux SD 或 eMMC state dir：当状态路径解析到 mmcblk* 挂载源时发出警告，因为 SD/eMMC 支持的随机 I/O 可能更慢，并且在 session 和凭据写入期间磨损更快。
  • Linux volatile state dir：当状态路径解析到 tmpfs 或 ramfs 时发出警告，因为 sessions、凭据、配置和 SQLite 状态（包括 WAL/journal sidecar）会在重启时消失。Docker overlay 挂载不会被标记，因为只要容器仍在运行，其可写层会在主机重启后持久存在。
  • Session dirs missing：需要 sessions/ 和 session store 目录来持久化历史并避免 ENOENT 崩溃。
  • Transcript mismatch：当最近的 session 条目缺少 transcript 文件时发出警告。
  • Main session “1-line JSONL”：当主 transcript 只有一行时进行标记（历史记录没有累积）。
  • Multiple state dirs：当不同 home 目录下存在多个 ~/.openclaw 文件夹，或 OPENCLAW_STATE_DIR 指向其他位置时发出警告（历史可能在不同安装之间分裂）。
  • Remote mode reminder：如果 gateway.mode=remote，doctor 会提醒你在远程主机上运行它（状态位于远程主机）。
  • Config file permissions：如果 ~/.openclaw/openclaw.json 对组或所有用户可读，会发出警告并提供将权限收紧到 600 的选项。
Doctor 会检查认证存储中的 OAuth 配置文件，警告 token 即将过期/已过期的情况，并在安全时刷新它们。如果 Anthropic OAuth/token 配置文件过期，它会建议使用 Anthropic API key 或 Anthropic setup-token 路径。刷新提示只会在交互式运行（TTY）时出现；--non-interactive 会跳过刷新尝试。当 OAuth 刷新永久失败时（例如 refresh_token_reused、invalid_grant，或 provider 提示你重新登录），doctor 会报告需要重新认证，并打印要运行的确切 openclaw models auth login --provider ... 命令。Doctor 还会报告因短暂冷却期（速率限制/超时/认证失败）或较长时间禁用（计费/额度失败）而暂时不可用的 auth profiles。旧版 Codex OAuth profiles 的 token 位于 macOS Keychain 中（这是基于文件的 sidecar 布局之前的旧版 onboarding），只能由 doctor 修复。请从交互式终端运行一次 openclaw doctor --fix，将基于 Keychain 的旧版 token 内联迁移到 auth-profiles.json；之后，embedded turns（Telegram、cron、sub-agent dispatch）会将它们解析为规范的 OpenAI OAuth profiles。
如果设置了 hooks.gmail.model，doctor 会根据目录和 allowlist 验证模型引用，并在该引用无法解析或不被允许时发出警告。
启用沙箱时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。
在 openclaw doctor --fix / openclaw doctor --repair 模式下，Doctor 会移除旧版由 OpenClaw 生成的插件依赖暂存状态：过时的生成依赖根目录、旧安装阶段目录、早期捆绑插件依赖修复代码产生的包本地残留，以及可能遮蔽当前捆绑 manifest 的孤立或恢复的、由 npm 管理的捆绑 @openclaw/* 插件副本。Doctor 还会将宿主 openclaw 包重新链接到声明 peerDependencies.openclaw 的 npm 管理插件中，使 openclaw/plugin-sdk/* 等包本地运行时导入在更新或 npm 修复后仍能解析。当配置引用了可下载插件，但本地插件注册表找不到它们时，Doctor 还可以重新安装缺失的插件（包括实质性的 plugins.entries、已配置的频道/provider/search 设置以及已配置的 agent runtimes）。在包更新期间，doctor 会避免在核心包替换时重新安装插件包；如果配置的插件仍需要恢复，请在更新后再次运行 openclaw doctor --fix。除下方容器镜像启动例外外，gateway 启动和配置重新加载不会运行包修复；插件安装仍属于明确的 doctor/install/update 工作。容器化 gateway 启动有一个范围有限的升级例外：当 openclaw gateway run 在新的 OpenClaw 版本上启动时，它会在就绪前运行安全状态迁移和现有的核心包之后插件收敛，然后记录每个版本的检查点。此启动过程可以清理过时的捆绑插件记录、修复本地插件链接、在收敛路径需要时重新安装已配置的插件包，并检查活动插件 payload。如果启动无法安全修复，请使用同一镜像，并针对相同的挂载状态/配置运行一次 openclaw doctor --fix，然后再正常重启容器。
Doctor 会检测旧的 gateway 服务（launchd/systemd/schtasks），并提供移除它们并使用当前 gateway 端口安装 OpenClaw 服务的选项。它还可以扫描额外的、类似 gateway 的服务并打印清理提示。带有 profile 名称的 OpenClaw gateway 服务被视为一等公民，不会被标记为“额外”。在 Linux 上，如果用户级 gateway 服务缺失但系统级 OpenClaw gateway 服务存在，doctor 不会自动安装第二个用户级服务。请使用 openclaw gateway status --deep 或 openclaw doctor --deep 检查，然后移除重复项，或者当系统 supervisor 承担 gateway 生命周期时设置 OPENCLAW_SERVICE_REPAIR_POLICY=external。
当 Matrix 频道账号存在待处理或可操作的旧状态迁移时，doctor（在 --fix / --repair 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧 Matrix 状态迁移和旧加密状态准备。这两个步骤都不会致命；错误会被记录下来，启动会继续。在只读模式（不带 --fix 的 openclaw doctor）下，这项检查会被完全跳过。
Doctor 会在正常健康检查过程中检查设备配对状态，并报告：
  • 待处理的首次配对请求
  • 已配对设备待处理的角色或 scope 升级
  • 设备 ID 仍匹配但设备身份不再匹配已批准记录时的公钥不匹配修复
  • 已批准角色缺少活动 token 的已配对记录
  • scope 偏离已批准配对基线的已配对 token
  • 当前机器的本地缓存设备 token 条目早于 gateway 端 token 轮换，或携带过时的 scope 元数据
Doctor 不会自动批准配对请求，也不会自动轮换设备 token。它会打印确切的后续步骤：
  • 使用 openclaw devices list 检查待处理请求
  • 使用 openclaw devices approve <requestId> 批准具体请求
  • 使用 openclaw devices rotate --device <deviceId> --role <role> 轮换新 token
  • 使用 openclaw devices remove <deviceId> 移除并重新批准过时记录
这一区分了首次配对、待处理的角色/scope 升级，以及过时的 token/设备身份漂移，解决了常见的“已配对但仍提示需要配对”问题。
Doctor 仅在发现警告时才会发出 Security note，例如某个 provider 对没有 allowlist 的私信开放，或策略配置存在危险。请使用 openclaw security audit 获取完整的安全清单。
如果作为 systemd 用户服务运行，doctor 会确保启用 lingering，以便 gateway 在退出登录后仍保持存活。
Doctor 会为默认 agent 打印问题和操作，而不是健康状态清单：
  • Skills：列出已允许但不可用的 skill 名称；使用 openclaw skills check 查看要求详情和完整计数。
  • Plugins：仅报告出错的插件 ID；使用 openclaw plugins list 查看已加载、已导入、已禁用和捆绑插件清单。
  • Plugin compatibility warnings：标记与当前运行时存在兼容性问题的插件。
  • Plugin diagnostics：显示插件注册表发出的所有加载时警告或错误。
  • TaskFlow recovery：显示需要手动检查或取消的可疑托管 TaskFlows。
  • Claude CLI：仅报告二进制文件、身份验证、profile、工作区或项目目录问题；不会显示健康探测详情。
Doctor 会检查工作区 bootstrap 文件（例如 AGENTS.md、CLAUDE.md 或其他注入的上下文文件）是否接近或超出配置的字符预算。它会按文件报告原始字符数与注入后字符数、截断百分比、截断原因（max/file 或 max/total），以及注入字符总数占总预算的比例。当文件被截断或接近上限时，doctor 会打印针对 agents.defaults.bootstrapMaxChars 和 agents.defaults.bootstrapTotalMaxChars 的调优建议。
Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全：
  • 如果 shell profile 使用的是较慢的动态补全模式（source <(openclaw completion ...)），doctor 会将其升级为更快的缓存文件变体。
  • 如果 profile 中已配置补全但缓存文件缺失，doctor 会自动重新生成缓存。
  • 如果完全没有配置补全，doctor 会提示安装它（仅交互模式；--non-interactive 会跳过）。
运行 openclaw completion --write-state 可手动重新生成缓存。
当 openclaw doctor --fix 移除缺失的频道插件时，它还会移除引用该插件的悬空频道范围配置：channels.<id> 条目、指定该频道的 heartbeat 目标，以及 agents.*.models["<channel>/*"] 覆盖。这可以防止频道运行时已消失但配置仍要求 gateway 绑定该频道而导致的 Gateway 启动循环。
Doctor 会检查本地 gateway token 身份验证是否就绪。
  • 如果 token 模式需要 token 且不存在 token 来源，doctor 会提供生成 token 的选项。
  • 如果 gateway.auth.token 由 SecretRef 管理但不可用，doctor 会发出警告且不会用明文覆盖它。
  • openclaw doctor --generate-gateway-token 仅在没有配置 token SecretRef 时强制生成。
某些修复流程需要在不削弱运行时 fail-fast 行为的前提下检查已配置的凭据。
  • openclaw doctor --fix 使用与 status 系列命令相同的只读 SecretRef 摘要模型来执行目标配置修复。
  • 示例：Telegram allowFrom / groupAllowFrom 的 @username 修复会在可用时尝试使用已配置的 bot 凭据。
  • 如果 Telegram bot token 通过 SecretRef 配置但在当前命令路径中不可用，doctor 会报告该凭据已配置但不可用，并跳过自动解析，而不是崩溃或错误地报告 token 缺失。
Doctor 会运行健康检查，并在 gateway 看起来不健康时提供重启它的选项。
Doctor 会检查已配置的 memory search embedding provider 是否已为默认 agent 就绪。具体行为取决于配置的 provider：
  • Explicit local provider：检查本地模型文件或已识别的远程/可下载模型 URL。如果缺失，会建议切换到远程 provider。
  • Explicit remote provider（openai、voyage 等）：验证环境或 auth store 中是否存在 API key。如果缺失，会打印可操作的修复提示。
  • Legacy auto provider：将 memorySearch.provider: "auto" 视为 OpenAI，检查 OpenAI 是否就绪，并由 doctor --fix 将其重写为 provider: "openai"。
当存在缓存的 gateway 探测结果时（即检查时 gateway 是健康的），doctor 会将其结果与 CLI 可见配置交叉引用，并指出任何差异。Doctor 不会在默认路径上发起新的 embedding ping；如需实时 provider 检查，请使用深度 memory 状态命令。使用 openclaw memory status --deep 可在运行时验证 embedding 就绪性。
如果 gateway 健康，doctor 会运行频道状态探测并报告带有建议修复的警告。
Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少或使用过时的默认值（例如 systemd network-online 依赖和重启延迟）。发现不匹配时，它会建议更新，并可以将服务文件/任务重写为当前默认值。说明：
  • openclaw doctor 在重写 supervisor 配置前会询问。
  • openclaw doctor --yes 接受默认修复提示。
  • openclaw doctor --fix 无提示应用建议的修复（--repair 是别名）。
  • openclaw doctor --fix --force 覆盖自定义 supervisor 配置。
  • OPENCLAW_SERVICE_REPAIR_POLICY=external 让 doctor 对 gateway 服务生命周期保持只读。它仍会报告服务健康状态并运行非服务修复，但会跳过服务安装/启动/重启/bootstrap、supervisor 配置重写和旧服务清理，因为外部 supervisor 负责该生命周期。
  • 在 macOS 上，同标签的系统 LaunchDaemon 会阻止用户 LaunchAgent 的安装、启动、重启和 bootstrap 修复。Doctor 会报告系统所有者并停止服务恢复；--force 不会绕过此所有权边界。请参阅 Existing system LaunchDaemons。
  • 在 Linux 上，当匹配的 systemd gateway unit 处于活动状态时，doctor 不会重写 command/entrypoint 元数据。在重复服务扫描期间，它还会忽略处于非活动状态的非旧版额外 gateway 类 unit，以避免伴随服务文件产生清理噪声。
  • 如果 token 身份验证需要 token 且 gateway.auth.token 由 SecretRef 管理，doctor 服务安装/修复会验证 SecretRef，但不会将解析出的明文 token 值持久化到 supervisor 服务环境元数据中。
  • Doctor 会检测由托管 .env/SecretRef 支持的服务环境值，这些值曾被旧版 LaunchAgent、systemd 或 Windows Scheduled Task 安装内联嵌入，并重写服务元数据，使这些值从运行时来源加载，而不是从 supervisor 定义中加载。
  • Doctor 会检测服务命令是否在 gateway.port 更改后仍固定使用旧的 --port，并将服务元数据重写为当前端口。
  • 如果 token 身份验证需要 token 且配置的 token SecretRef 未解析，doctor 会阻止安装/修复路径，并提供可操作的指导。
  • 如果同时配置了 gateway.auth.token 和 gateway.auth.password，但未设置 gateway.auth.mode，doctor 会阻止安装/修复，直到明确设置 mode。
  • 对于 Linux 用户 systemd unit，doctor 的 token 漂移检查会在比较服务身份验证元数据时同时包括 Environment= 和 EnvironmentFile= 来源。
  • 当配置由较新版本写入时，Doctor 服务修复会拒绝从较旧的 OpenClaw 二进制文件重写、停止或重启 gateway 服务。请参阅 Gateway troubleshooting。
  • 你始终可以通过 openclaw gateway install --force 强制进行完整重写。
Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 gateway 端口（默认 18789）上的端口冲突，并报告可能原因（gateway 已在运行、SSH 隧道）。
当 gateway 服务运行在 Bun 或版本管理的 Node 路径（nvm、fnm、volta、asdf 等）上时，Doctor 会发出警告。Bun 无法打开 OpenClaw 的 node:sqlite 状态存储，因此修复会将旧版 Bun 服务迁移到 Node。版本管理器路径可能在升级后失效，因为服务不会加载 shell 初始化配置。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。新安装或修复的 macOS LaunchAgents 会使用规范的系统 PATH（/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin），而不是复制交互式 shell PATH，因此 Homebrew 管理的系统二进制文件仍可用，同时 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会改变 Node 子进程的解析结果。Linux 服务仍会保留明确的环境根目录（NVM_DIR、FNM_DIR、VOLTA_HOME、ASDF_DATA_DIR、BUN_INSTALL、PNPM_HOME）和稳定的用户 bin 目录，但只有在磁盘上存在这些目录时，推测出的版本管理器回退目录才会被写入服务 PATH。
Doctor 会持久化任何配置更改，并标记向导元数据以记录这次 doctor 运行。
当缺少工作区记忆系统时，doctor 会建议使用它；如果工作区还不在 git 下，则会打印备份提示。有关工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab），请参见 /concepts/agent-workspace。

​
相关