Doctor

openclaw doctorOpenClaw 是 OpenClaw 的修复和迁移工具。它修复过时的配置/状态，检查健康状况，并提供可执行的修复步骤。

快速开始

openclaw doctor

无头和自动化模式

--yes--fix--lint--fix --force--non-interactive--deep

openclaw doctor --yes

在不提示的情况下接受默认值（包括适用时的重启/服务/沙盒修复步骤）。

openclaw doctor --fix

在不提示的情况下应用推荐的修复（在安全的情况下进行修复和重启）。

openclaw doctor --lint
openclaw doctor --lint --json

运行用于 CI 或预检自动化的结构化健康检查。此模式是 只读的：它不会提示、修复、迁移配置、重启服务或 触及状态。

openclaw doctor --fix --force

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

openclaw doctor --non-interactive

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

openclaw doctor --deep

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

如果您想在写入之前审查更改，请先打开配置文件：

cat ~/.openclaw/openclaw.json

只读 lint 模式

openclaw doctor --lint 是 openclaw doctor --fix 的适用于自动化的兄弟命令。两者都使用 doctor 健康检查，但它们的立场 不同：

模式	提示	写入配置/状态	输出	用于
openclaw doctor	是	否	友好的健康报告	人工检查状态
openclaw doctor --fix	有时	是，带有修复策略	友好的修复日志	正在应用批准的修复
openclaw doctor --lint	否	否	结构化发现	CI、预检和审查门禁

现代化的健康检查可能会提供可选的 repair() 实现。 doctor --fix 在存在这些修复时应用它们，并继续对尚未迁移的检查使用现有的 doctor 修复流程。 结构化修复合约还将修复报告与检测分离开来：detect() 报告当前发现，而 repair() 可以报告更改、配置/文件差异和非文件副作用。这为未来的 doctor --fix --dry-run 和差异输出保持迁移路径畅通，而无需让 lint 检查计划变更。

示例：

openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --only core/doctor/gateway-config --json

JSON 输出包括：

• ok：是否有任何可见的发现达到选定的严重性阈值
• checksRun：执行的健康检查数量
• checksSkipped：由 --only 或 --skip 跳过的检查
• findings：具有 checkId、severity、message 的结构化诊断，以及 可选的 path、line、column、ocPath 和 fixHint

退出代码：

• 0：在选定阈值或之上没有发现
• 1：一个或多个发现达到选定阈值
• 2：在发出 lint 发现之前的命令/运行时失败

使用 --severity-min info|warning|error 来控制打印内容和导致非零 lint 退出的原因。使用 --only <id> 进行狭义的预检门控，并使用 --skip <id> 临时排除嘈杂的检查，同时保持 lint 运行的其余部分处于活动状态。 Lint 输出选项，如 --json、--severity-min、--only 和 --skip，必须与 --lint 配对；常规的 doctor 和 repair 运行会拒绝它们。

功能（摘要）

Health, UI, and updates

• 可选的 git 安装预更新（仅限交互模式）。
• UI 协议新鲜度检查（当协议架构较新时重建 Control UI）。
• 健康检查 + 重启提示。
• Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。

配置和迁移

• 针对旧版值的配置标准化。
• 将对话配置从旧的扁平 talk.* 字段迁移到 talk.provider + `talk.providers.

。 - 浏览器迁移检查，针对旧版 Chrome 扩展配置和 Chrome MCP 就绪状态。 - OpenCode 提供商覆盖警告（models.providers.opencode/models.providers.opencode-go）。 - Codex OAuth 遮蔽警告（models.providers.openai-codex）。 - 针对 OAuth Codex OpenAI 配置文件的 OAuth TLS 先决条件检查。 - 当 plugins.allow 具有限制性但工具策略仍请求通配符或插件拥有的工具时，发出插件/工具允许列表警告。 - 旧版磁盘状态迁移（会话/代理目录/WhatsApp 身份验证）。 - 旧版插件清单契约键迁移（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders→contracts）。 - 旧版 cron 存储迁移（jobId、schedule.cron、顶级 delivery/payload 字段、payload provider、简单的 notify: truewebhook 回退作业）。 - 旧版全代理运行时策略清理；提供商/模型运行时策略是活动的路由选择器。 - 启用插件时清理过时的插件配置；当设置为plugins.enabled=false` 时，过时的插件引用将被视为非活动的容器配置并被保留。

状态和完整性

• 会话锁文件检查和陈旧锁清理。
• 会话记录修复，针对受影响的 2026.4.24 构建版本创建的重复提示重写分支。
• 卡住的子代理重启恢复墓碑检测，支持 --fixOAuth 清除陈旧的中止恢复标志，这样启动时就不会继续将子进程视为重启中止。
• 状态完整性和权限检查（会话、记录、状态目录）。
• 本地运行时的配置文件权限检查（chmod 600）。
• 模型认证健康检查：检查 OAuth 过期时间，可刷新即将过期的令牌，并报告认证配置文件的冷却/禁用状态。
• 额外的工作区目录检测（~/openclaw）。

Gateway(网关)、服务和监控程序

• 启用沙箱隔离时的沙箱镜像修复。
• 旧版服务迁移和额外的 Gateway(网关) 检测。
• Matrix 渠道旧版状态迁移（在 --fix / --repairGateway(网关) 模式下）。
• Gateway(网关) 运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
• 渠道状态警告（从正在运行的 Gateway(网关) 探测）。
• 特定于渠道的权限检查位于 openclaw channels capabilitiesDiscord 下；例如，Discord 语音频道权限使用 `openclaw channels capabilities —channel discord —target channel:

WhatsAppGateway(网关)TUI 进行审计。 - 针对在本地 TUI 客户端仍在运行时 Gateway(网关) 事件循环健康状况下降的 WhatsApp 响应能力检查；—fixTUI 仅停止已验证的本地 TUI 客户端。 - 针对主模型、回退、心跳/子代理/压缩覆盖、钩子、渠道模型覆盖和会话路由固定中的旧版 openai-codex/ 模型引用的 Codex 路由修复；—fix将它们重写为openai/OpenAI，删除过时的会话/全代理运行时固定，并在默认 Codex 驱动程序上保留规范的 OpenAI 代理引用。 - 监控程序配置审计（launchd/systemd/schtasks），可选择修复。 - 网关服务的嵌入式代理环境清理，这些服务在安装或更新期间捕获了 shell HTTP_PROXY/HTTPS_PROXY/NO_PROXYGateway(网关)BunGateway(网关) 值。 - Gateway(网关) 运行时最佳实践检查（Node 与 Bun，版本管理器路径）。 - Gateway(网关) 端口冲突诊断（默认 18789`）。

Auth, security, and pairing

• 针对开放私信策略的安全警告。
• 本地令牌模式的 Gateway(网关) 身份验证检查（当不存在令牌源时提供令牌生成功能；不会覆盖令牌 SecretRef 配置）。
• 设备配对故障检测（挂起的首次配对请求、挂起的角色/范围升级、过时的本地设备令牌缓存漂移，以及配对记录的身份验证漂移）。

Workspace and shell

• Linux 上的 systemd linger 检查。
• 工作区引导文件大小检查（针对上下文文件的截断/接近限制警告）。
• 默认代理的 Skills 就绪检查；报告缺少二进制文件、环境变量、配置或操作系统要求的允许 Skills，并且 --fix 可以在 skills.entriesAPI 中禁用不可用的 Skills。
• Shell 自动补全状态检查和自动安装/升级。
• 记忆搜索嵌入提供商的就绪检查（本地模型、远程 API 密钥或 QMD 二进制文件）。
• 源码安装检查（pnpm 工作区不匹配、缺少 UI 资产、缺少 tsx 二进制文件）。
• 写入更新的配置 + 向导元数据。

Dreams UI 回填和重置

控制 UI Dreams 场景包括用于基于事实的梦境工作流的 Backfill、Reset 和 Clear Grounded 操作。这些操作使用 Gateway(网关) 医生风格的 RPC 方法，但它们不是 RPCopenclaw doctorCLI CLI 修复/迁移的一部分。

它们的作用：

• Backfill 扫描活动工作区中的历史 memory/YYYY-MM-DD.md 文件，运行基于事实的 REM 日记传递，并将可逆的回填条目写入 DREAMS.md。
• Reset 仅从 DREAMS.md 中删除那些标记为回填的日记条目。
• Clear Grounded 仅删除来自历史重放且尚未累积实时回忆或日常支持的暂存仅基于事实的短期条目。

它们不会自己做的事情：

• 它们不编辑 MEMORY.md
• 它们不运行完整的医生迁移
• 除非您先显式运行暂存 CLI 路径，否则它们不会自动将基于事实的候选项暂存到实时短期推广存储中

如果您希望基于事实的历史回放能够影响常规深度推广通道，请改用 CLI 流程：

openclaw memory rem-backfill --path ./memory --stage-short-term

这会将基于事实的持久候选项暂存到短期梦境存储中，同时保持 DREAMS.md 作为审查界面。

详细行为和基本原理

0. 可选更新（git 安装）

如果这是一个 git checkout 版本并且 doctor 正在交互式运行，它会在运行 doctor 之前提议进行更新（fetch/rebase/build）。

1. 配置规范化

如果配置包含旧版值形状（例如没有特定于 覆盖的 messages.ackReaction），doctor 会将其规范化为当前架构。

这包括旧版 Talk 平面字段。当前的公共 Talk 语音配置是 talk.provider + `talk.providers.

，实时语音配置是 talk.realtime.*。Doctor 会将旧的 talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey 形状重写为提供商映射，并将旧的顶层实时选择器（talk.mode、talk.transport、talk.brain、talk.model、talk.voice）重写为 talk.realtime`。

当 `plugins.allow` 非空且工具策略使用通配符或插件拥有的工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 仅匹配实际加载的插件中的工具；它不会绕过独占插件允许列表。Doctor 会为迁移的旧版允许列表配置写入 `plugins.bundledDiscovery: "compat"`，以保留现有的捆绑提供商行为，然后指向更严格的 `"allowlist"` 设置。

2. 遗留配置键迁移

当配置包含已弃用的键时，其他命令将拒绝运行并要求您运行 openclaw doctor。

Doctor 将执行以下操作：

• 解释找到了哪些遗留键。
• 显示它应用的迁移。
• 使用更新的架构重写 ~/.openclaw/openclaw.jsonGateway(网关)。

Gateway(网关) 启动时会拒绝遗留的配置格式并要求您运行 openclaw doctor --fix；它不会在启动时重写 openclaw.json。Cron 任务存储迁移也由 openclaw doctor --fix 处理。

当前的迁移：

• 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
• channels.telegram.requireMention → channels.telegram.groups."*".requireMention
• routing.queue → messages.queue
• routing.bindings → 顶级 bindings
• routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
• 遗留 talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + `talk.providers.

- 遗留顶级实时 Talk 选择器 (talk.mode/talk.transport/talk.brain/talk.model/talk.voice) + talk.provider/talk.providers→talk.realtime -routing.agentToAgent→tools.agentToAgent -routing.transcribeAudio→tools.media.audio.models -messages.tts.

(openai/elevenlabs/microsoft/edge) → messages.tts.providers.

-messages.tts.provider: “edge”和messages.tts.providers.edge→messages.tts.provider: “microsoft”和messages.tts.providers.microsoft -channels.discord.voice.tts.

(openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.

-channels.discord.accounts.

.voice.tts.

(openai/elevenlabs/microsoft/edge) → channels.discord.accounts.

.voice.tts.providers.

-plugins.entries.voice-call.config.tts.

(openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.

-plugins.entries.voice-call.config.tts.provider: “edge”和plugins.entries.voice-call.config.tts.providers.edge→provider: “microsoft”和providers.microsoft -plugins.entries.voice-call.config.provider: “log”→”mock” -plugins.entries.voice-call.config.twilio.from→plugins.entries.voice-call.config.fromNumber -plugins.entries.voice-call.config.streaming.sttProvider→plugins.entries.voice-call.config.streaming.provider -plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold→plugins.entries.voice-call.config.streaming.providers.openai. -bindings[].match.accountID→bindings[].match.accountId - 对于具有命名accounts但保留单帐户顶级渠道值的渠道，将这些帐户范围的值移动到为该渠道选择的提升帐户中（对于大多数渠道为accounts.defaultMatrix；Matrix 可以保留现有的匹配命名/默认目标） - 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 - 移除agents.defaults.llm；对于慢速提供商/模型超时，使用 models.providers.

.timeoutSeconds，并且当整个运行必须持续更长时间时，将代理/运行超时保持在该值之上 - browser.ssrfPolicy.allowPrivateNetwork→browser.ssrfPolicy.dangerouslyAllowPrivateNetwork -browser.profiles..driver: “extension”→”existing-session” - 移除browser.relayBindHost(遗留扩展中继设置) - 遗留models.providers..api: “openai”→”openai-completions”(Gateway 启动也会跳过其api设置为未来或未知枚举值的提供商，而不是失败关闭) - 移除plugins.entries.codex.config.codexDynamicToolsProfile`；Codex 应用服务器始终保持 Codex 原生工作区工具为原生

Doctor 警告还包括多帐户渠道的帐户默认指南：

- 如果配置了两个或更多 `channels.

.accounts条目且没有channels.

.defaultAccount或accounts.default，Doctor 会警告回退路由可能会选择意外的帐户。 - 如果 channels.

.defaultAccount` 设置为未知的帐户 ID，Doctor 会发出警告并列出已配置的帐户 ID。

2b. OpenCode 提供商 overrides

如果您手动添加了 models.providers.opencode、opencode-zen 或 opencode-go，它将覆盖 @earendil-works/pi-ai 中的内置 OpenCode 目录。这可能会导致模型被强制使用错误的 API 或使费用归零。Doctor 会发出警告，以便您移除该覆盖并恢复按模型的 API 路由和费用。

2c. Browser migration and Chrome MCP readiness

如果您的浏览器配置仍然指向已移除的 Chrome 扩展路径，Doctor 会将其规范化为当前主机本地的 Chrome MCP 附加模型：

• browser.profiles.*.driver: "extension" 变为 "existing-session"
• browser.relayBindHost 被移除

当您使用 defaultProfile: "user" 或配置的 existing-session 配置文件时，Doctor 还会审计主机本地的 Chrome MCP 路径：

• 检查同一主机上是否安装了 Google Chrome（适用于默认自动连接配置文件）
• 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告
• 提醒您在浏览器检查页面启用远程调试（例如 chrome://inspect/#remote-debugging、brave://inspect/#remote-debugging 或 edge://inspect/#remote-debugging）

Doctor 无法为您启用 Chrome 端的设置。主机本地 Chrome MCP 仍然需要：

• 网关/节点主机上安装基于 Chromium 的浏览器 144+
• 浏览器在本地运行
• 在该浏览器中启用远程调试
• 在浏览器中批准第一次附加同意提示

此处的就绪性仅涉及本地附加的先决条件。现有会话保持当前的 Chrome MCP 路由限制；responsebody、PDF 导出、下载拦截和批量操作等高级路由仍然需要托管浏览器或原始 CDP 配置文件。

此检查 不 适用于 Docker、沙盒、远程浏览器或其他无头流程。这些流程继续使用原始 CDP。

OAuth2d. OAuth TLS 先决条件

当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈是否能验证证书链。如果探测因证书错误（例如 UNABLE_TO_GET_ISSUER_CERT_LOCALLYmacOS、过期证书或自签名证书）而失败，doctor 会打印特定于平台的修复指南。在带有 Homebrew Node 的 macOS 上，修复方法通常是 brew postinstall ca-certificates。使用 --deep 时，即使网关运行正常，探测也会运行。

OAuth2e. Codex OAuth 提供商覆盖

如果您之前在 models.providers.openai-codexOAuthOAuth 下添加了旧版 OpenAI 传输设置，它们可能会覆盖较新版本自动使用的内置 Codex OAuth 提供商路径。当 Doctor 在 Codex OAuth 旁边看到这些旧的传输设置时，会发出警告，以便您删除或重写过时的传输覆盖，并恢复内置的路由/回退行为。仍然支持自定义代理和仅标头覆盖，并且不会触发此警告。

2f. Codex 路由修复

Doctor 会检查遗留的 openai-codex/* 模型引用。原生 Codex harness 路由使用规范的 openai/* 模型引用；OpenAI 代理轮次通过 Codex 应用服务器 harness 而非 OpenClaw PI OpenAI 路径进行。

在 --fix / --repair 模式下，doctor 会重写受影响的默认代理和每个代理的引用，包括主模型、回退、心跳/子代理/压缩覆盖、钩子、渠道模型覆盖以及陈旧的持久化会话路由状态：

• openai-codex/gpt-* 变为 openai/gpt-*。
• Codex 意图会移动到提供程序/模型范围的 agentRuntime.id: "codex" 条目，用于修复后的代理模型引用，以便在模型引用变为 openai/* 后仍可选择 openai-codex:... 身份验证配置文件。
• 陈旧的整个代理运行时配置和持久化会话运行时固定项会被移除，因为运行时选择是提供程序/模型范围的。
• 除非修复后的遗留模型引用需要 Codex 路由以保留旧的身份验证路径，否则现有的提供程序/模型运行时策略将被保留。
• 现有的模型回退列表会被保留，但其遗留条目会被重写；复制的每个模型设置会从遗留键移动到规范的 openai/* 键。
• 持久化会话 modelProvider/providerOverride、model/modelOverride、回退通知和身份验证配置文件固定项将在所有发现的代理会话存储中得到修复。
• /codex ... 意味着“从聊天中控制或绑定原生 Codex 对话。”
• /acp ... 或 runtime: "acp" 意味着“使用外部 ACP/acpx 适配器。”

2g. 会话路由清理

Doctor 还会在您将配置的模型或运行时从插件拥有的路由（例如 Codex）移开后，扫描发现的代理会话存储中过时的自动创建的路由状态。

当其所属路由不再配置时，openclaw doctor --fix 可以清除自动创建的过时状态，例如 modelOverrideSource: "auto"CLI 模型固定、运行时模型元数据、固定的 harness id、CLI 会话绑定和自动 auth-profile 覆盖。显式的用户或遗留会话模型选择将报告以供手动审查并保持不变；当不再需要该路由时，请使用 /model ...、/new 切换它们，或重置会话。

3. 遗留状态迁移（磁盘布局）

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

• 会话存储 + 转录：
  • 从 ~/.openclaw/sessions/ 到 `~/.openclaw/agents/

/sessions/ - 代理目录： - 从/.openclaw/agent/到/.openclaw/agents/

/agent/ - WhatsApp 认证状态 (Baileys)： - 从遗留的/.openclaw/credentials/*.json（oauth.json除外） - 到/.openclaw/credentials/whatsapp/

/…（默认帐户 id：default`Gateway(网关)CLI）

这些迁移是尽力而为且幂等的；当 doctor 将任何遗留文件夹保留为备份时，它会发出警告。Gateway/CLI 还会在启动时自动迁移遗留的会话 + 代理目录，以便历史/认证/模型无需手动运行 doctor 即可落入 per-agent 路径。WhatsApp 认证有意仅通过 `openclaw doctor` 进行迁移。Talk 提供商/提供商-map 标准化现在通过结构相等性进行比较，因此仅键顺序的差异不再触发重复的无效 `doctor --fix` 更改。

3a. 传统插件清单迁移

Doctor 会扫描所有已安装的插件清单，查找已弃用的顶级功能键（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders）。如果找到这些键，它会建议将其移至 contracts 对象中，并就地重写清单文件。此迁移是幂等的；如果 contracts 键已具有相同的值，则会删除传统键而不会重复数据。

3b. 传统 cron 存储迁移

Doctor 还会检查 cron 作业存储（默认为 ~/.openclaw/cron/jobs.json，或者在覆盖时为 cron.store）中是否存在调度器为了兼容性仍然接受的旧作业格式。

当前的 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 回退作业 → 带有 delivery.to=cron.webhook 的显式 delivery.mode="webhook"

只有当可以在不改变行为的情况下自动迁移 notify: true 作业时，Doctor 才会执行迁移。如果作业将传统通知回退与现有的非 webhook 传递模式结合在一起，Doctor 会发出警告并将该作业留待人工审查。

在 Linux 上，如果用户的 crontab 仍然调用传统的 ~/.openclaw/bin/ensure-whatsapp.sh，Doctor 也会发出警告。该主机本地脚本不由当前的 OpenClaw 维护，并且当 cron 无法到达 systemd 用户总线时，可能会向 ~/.openclaw/logs/whatsapp-health.log 写入错误的 Gateway inactive 消息。请使用 crontab -e 删除过时的 crontab 条目；对于当前的健康检查，请使用 openclaw channels status --probe、openclaw doctor 和 openclaw gateway status。

3c. 会话锁清理

Doctor 会扫描每个代理会话目录，查找过期的写锁文件——即会话异常退出时遗留的文件。对于发现的每个锁文件，它会报告：路径、PID、PID 是否仍然存活、锁定时长，以及是否被视为过期（PID 已死、超过 30 分钟，或可证实属于非 OpenClaw 进程的存活 PID）。在 --fix / --repair 模式下，它会自动移除过期的锁文件；否则，它会打印一条注释并指示您使用 --fix 重新运行。

3d. 会话记录分支修复

Doctor 扫描代理会话 JSONL 文件，查找由 2026.4.24 提示记录重写错误引起的重复分支形状：一个包含 OpenClaw 内部运行时上下文的已废弃用户回合，以及一个包含相同可见用户提示的活动同级分支。在 --fix / --repair 模式下，doctor 会将每个受影响的文件在原位置旁边进行备份，并将记录重写为活动分支，以便网关历史和内存读取器不再看到重复的回合。

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

状态目录是运行的脑干。如果它消失，您将丢失会话、凭证、日志和配置（除非您在其他地方有备份）。

Doctor 会检查：

• 状态目录丢失：警告灾难性的状态丢失，提示重新创建目录，并提醒您它无法恢复丢失的数据。
• 状态目录权限：验证可写性；提供修复权限（并在检测到所有者/组不匹配时发出 chownmacOS 提示）。
• macOS 云同步状态目录：当状态解析位于 iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) 或 ~/Library/CloudStorage/...Linux 下时发出警告，因为同步支持的路径可能会导致 I/O 变慢以及锁定/同步竞争。
• Linux SD 或 eMMC 状态目录：当状态解析为 mmcblk* 挂载源时发出警告，因为在会话和凭证写入期间，基于 SD 或 eMMC 的随机 I/O 可能会变慢并加速磨损。
• 会话目录丢失：sessions/ 和会话存储目录是持久化历史记录和避免 ENOENT 崩溃所必需的。
• 逐字稿不匹配：当最近的会话条目缺少逐字稿文件时发出警告。
• 主会话“单行 JSONL”：当主逐字稿只有一行时标记（历史记录未累积）。
• 多个状态目录：当跨主目录存在多个 ~/.openclaw 文件夹或当 OPENCLAW_STATE_DIR 指向别处时发出警告（历史记录可能会在安装之间分裂）。
• 远程模式提醒：如果 gateway.mode=remote，doctor 会提醒您在远程主机上运行它（状态驻留在那里）。
• 配置文件权限：如果 ~/.openclaw/openclaw.json 是组/全局可读的，则发出警告并提供将其收紧为 600。

5. Model auth health (OAuth expiry)

Doctor 会检查 auth store 中的 OAuth 配置文件，在令牌即将过期或已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过时，它会建议使用 Anthropic API 密钥或 Anthropic setup-token 路径。刷新提示仅在交互运行（TTY）时出现；--non-interactive 会跳过刷新尝试。

当 OAuth 刷新永久失败时（例如 refresh_token_reused、invalid_grant 或提供商提示您重新登录），doctor 会报告需要重新认证，并打印出确切的 openclaw models auth login --provider ... 命令以供运行。

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

• 短期冷却（速率限制/超时/认证失败）
• 长期禁用（计费/信用失败）

6. Hooks 模型 validation

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

7. 沙箱 image repair

当启用 Docker 时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。

7b. 插件安装清理

Doctor 会移除 openclaw doctor --fix / openclaw doctor --repairnpm 模式下遗留的由 OpenClaw 生成的插件依赖暂存状态。这包括过时的生成的依赖根目录、旧的安装阶段目录、来自先前捆绑插件依赖修复代码的包本地碎片，以及可能覆盖当前捆绑清单的孤立或已恢复的托管 npm 捆绑 @openclaw/* 插件副本。Doctor 还会将主机 openclawnpm 包重新链接到声明了 peerDependencies.openclaw 的托管 npm 插件中，以便诸如 openclaw/plugin-sdk/*npm 之类的包本地运行时导入在更新或 npm 修复后继续解析。

当配置引用了插件但本地插件注册表找不到它们时，Doctor 也可以重新安装缺失的可下载插件。示例包括素材 plugins.entries、配置的渠道/提供商/搜索设置以及配置的代理运行时。在包更新期间，doctor 会避免在交换核心包时运行包管理器插件修复；如果配置的插件仍需要恢复，请在更新后再次运行 openclaw doctor --fixGateway(网关)。Gateway 启动和配置重新加载不会运行包管理器；插件安装仍然是显式的 doctor/install/update 工作。

Gateway(网关)8. Gateway(网关)服务迁移和清理提示

Doctor 会检测旧版 Gateway 服务（launchd/systemd/schtasks），并建议将其移除，同时使用当前的 Gateway 端口安装 OpenClaw 服务。它还可以扫描额外的类 Gateway 服务并打印清理提示。以配置文件命名的 OpenClaw Gateway 服务被视为一等服务，不会被标记为“额外”服务。

在 Linux 上，如果缺少用户级 Gateway 服务但存在系统级 OpenClaw Gateway 服务，doctor 不会自动安装第二个用户级服务。请使用 openclaw gateway status --deep 或 openclaw doctor --deep 进行检查，然后移除重复项，或者在系统管理器管理 Gateway 生命周期时设置 OPENCLAW_SERVICE_REPAIR_POLICY=external。

Matrix8b. 启动时 Matrix 迁移

当 Matrix 渠道账户具有待处理或可执行的旧版状态迁移时，doctor（在 --fix / --repairMatrix 模式下）会创建一个迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命的；错误会被记录，启动将继续。在只读模式下（不带 --fix 的 openclaw doctor），此检查将被完全跳过。

8c. 设备配对和认证漂移

Doctor 现在将检查设备配对状态作为常规健康检查的一部分。

它报告的内容包括：

• 待处理的首次配对请求
• 已配对设备的待处理角色升级
• 已配对设备的待处理范围升级
• 公钥不匹配修复，即设备 ID 仍然匹配，但设备身份不再匹配已批准的记录
• 缺少已批准角色的活动令牌的已配对记录
• 范围超出已批准配对基线的已配对令牌
• 当前机器的本地缓存设备令牌条目，这些条目早于网关端的令牌轮换或包含过时的范围元数据

Doctor 不会自动批准配对请求或自动轮换设备令牌。相反，它会打印确切的后续步骤：

• 使用 openclaw devices list 检查待处理的请求
• 使用 `openclaw devices approve

批准确切的请求 - 使用openclaw devices rotate —device

—role

轮换一个新令牌 - 使用openclaw devices remove

` 移除并重新批准过时的记录

这填补了常见的“已配对但仍提示需要配对”的漏洞：Doctor 现在区分了首次配对、待处理的角色/范围升级以及过时令牌/设备身份漂移。

9. 安全警告

当提供商在没有允许列表的情况下开放私信，或者策略以危险方式配置时，Doctor 会发出警告。

Linux10. systemd linger (Linux)

如果作为 systemd 用户服务运行，Doctor 会确保已启用 linger，以便网关在注销后保持运行。

11. 工作区状态（Skills、插件和旧版目录）

Doctor 会打印默认代理的工作区状态摘要：

• Skills 状态：统计符合条件的、缺少依赖的以及被允许列表阻止的 Skills。
• 旧版工作区目录：当 ~/openclaw 或其他旧版工作区目录与当前工作区并存时发出警告。
• 插件状态：统计已启用/已禁用/已出错的插件；列出任何出错的插件 ID；报告捆绑插件的功能。
• 插件兼容性警告：标记与当前运行时存在兼容性问题的插件。
• 插件诊断：显示插件注册器发出的任何加载时警告或错误。

11b. 引导文件大小

Doctor 会检查工作区引导文件（例如 AGENTS.md、CLAUDE.md 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数对比、截断百分比、截断原因（max/file 或 max/total），以及作为总预算一部分的总注入字符数。当文件被截断或接近限制时，doctor 会打印调整 agents.defaults.bootstrapMaxChars 和 agents.defaults.bootstrapTotalMaxChars 的提示。

11d. 过期渠道插件的清理

当 openclaw doctor --fix 移除缺失的渠道插件时，它也会移除引用该插件的无用渠道范围配置：`channels.

条目、命名该渠道的心跳目标以及agents.*.models[”

/*”]`Gateway(网关) 覆盖项。这可以防止 Gateway 启动循环，即渠道运行时已不存在但配置仍要求网关绑定到它。

11c. Shell 补全

Doctor 检查当前 Shell（zsh、bash、fish 或 PowerShell）是否安装了 Tab 补全功能：

• 如果 Shell 配置文件使用了缓慢的动态补全模式（source <(openclaw completion ...)），doctor 会将其升级为更快的缓存文件变体。
• 如果配置文件中配置了补全但缺少缓存文件，doctor 会自动重新生成缓存。
• 如果完全没有配置补全，doctor 会提示安装（仅限交互模式；使用 --non-interactive 时跳过）。

运行 openclaw completion --write-state 以手动重新生成缓存。

Gateway(网关)12. Gateway(网关) 认证检查（本地令牌）

Doctor 检查本地 Gateway(网关) 令牌认证就绪状态。

• 如果令牌模式需要令牌但不存在令牌源，doctor 会提议生成一个。
• 如果 gateway.auth.token 由 SecretRef 管理但不可用，doctor 会发出警告且不会用纯文本覆盖它。
• openclaw doctor --generate-gateway-token 仅在未配置令牌 SecretRef 时强制生成。

12b. 只读 SecretRef 感知修复

某些修复流程需要检查已配置的凭据，而不会削弱运行时的快速失败行为。

• openclaw doctor --fixTelegram 现在使用与 status 系列命令相同的只读 SecretRef 摘要模型来进行定向配置修复。
• 示例：Telegram allowFrom / groupAllowFrom @usernameTelegram 修复尝试在可用时使用已配置的机器人凭据。
• 如果 Telegram 机器人令牌通过 SecretRef 配置但在当前命令路径中不可用，doctor 会报告该凭据“已配置但不可用”，并跳过自动解析，而不是崩溃或将令牌错误报告为缺失。

Gateway(网关)13. Gateway(网关) 健康检查 + 重启

Doctor 运行健康检查，并在 Gateway(网关) 看起来不健康时提议重启它。

13b. 内存搜索准备情况

Doctor 会检查为默认代理配置的内存搜索嵌入提供商是否就绪。具体行为取决于配置的后端和提供商：

• QMD 后端：探测 qmd 二进制文件是否可用且可启动。如果不可用，会打印修复指南，包括 npm 包和手动二进制路径选项。
• 显式本地提供商：检查是否存在本地模型文件或可识别的远程/可下载模型 URL。如果缺失，建议切换到远程提供商。
• 显式远程提供商（openai、voyage 等）：验证环境或身份验证存储中是否存在 API 密钥。如果缺失，打印可执行的修复提示。
• 自动提供商：首先检查本地模型可用性，然后按自动选择顺序尝试每个远程提供商。

当存在缓存的网关探测结果时（检查时网关健康），doctor 会将其结果与 CLI 可见配置进行交叉比对，并记录任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；如果您希望对提供商进行实时检查，请使用深度内存状态命令。

使用 openclaw memory status --deep 在运行时验证嵌入准备情况。

14. 渠道状态警告

如果网关健康，doctor 会运行渠道状态探测并报告带有建议修复方案的警告。

15. Supervisor 配置审核 + 修复

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 服务生命周期保持只读。它仍然报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/引导、supervisor 配置重写和旧版服务清理，因为外部 supervisor 拥有该生命周期。
• 在 Linux 上，当匹配的 systemd gateway 单元处于活动状态时，doctor 不会重写命令/入口点元数据。它在重复服务扫描期间还会忽略处于非活动状态的非旧版额外类 gateway 单元，以免伴随服务文件产生清理干扰。
• 如果令牌身份验证需要令牌且 gateway.auth.token 由 SecretRef 管理，doctor 服务安装/修复会验证 SecretRef，但不会将解析后的纯文本令牌值持久保存到 supervisor 服务环境元数据中。
• Doctor 检测到较旧的 LaunchAgent、systemd 或 Windows 计划任务安装内嵌的受管 .env/SecretRef 支持的服务环境值，并重写服务元数据，以便这些值从运行时源而非 supervisor 定义加载。
• Doctor 检测到在 gateway.port 更改后服务命令仍固定使用旧的 --port 时，会将服务元数据重写为当前端口。
• 如果令牌身份验证需要令牌且配置的令牌 SecretRef 未解析，doctor 会通过可操作的指导阻止安装/修复路径。
• 如果同时配置了 gateway.auth.token 和 gateway.auth.password 且未设置 gateway.auth.mode，doctor 将阻止安装/修复，直到明确设置模式。
• 对于 Linux 用户 systemd 单元，doctor 令牌漂移检查现在在比较服务身份验证元数据时包括 Environment= 和 EnvironmentFile= 源。
• 当配置最后由较新版本写入时，Doctor 服务修复将拒绝重写、停止或重启来自较旧 OpenClawGateway(网关) 二进制文件的 Gateway 服务。请参阅 Gateway 故障排除。
• 您始终可以通过 openclaw gateway install --force 强制进行完整重写。

Gateway(网关)16. Gateway(网关) 运行时 + 端口诊断

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

Gateway(网关)17. Gateway(网关) 运行时最佳实践

当 Gateway(网关) 服务运行在 Bun 或受版本管理的 Node 路径（nvm、fnm、volta、asdfWhatsAppTelegrammacOS 等）上时，Doctor 会发出警告。WhatsApp + Telegram 频道需要 Node，且由于服务不会加载您的 shell 初始化文件，版本管理器路径在升级后可能会失效。当系统提供系统级 Node 安装（Homebrew/apt/choco）时，Doctor 会建议迁移到该安装。

新安装或修复后的 macOS LaunchAgents 使用规范系统 PATH（/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbinLinux），而不是复制交互式 shell PATH，因此 Homebrew 管理的系统二进制文件保持可用，而 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会影响 Node 子进程解析的路径。Linux 服务仍保留显式环境根目录（NVM_DIR、FNM_DIR、VOLTA_HOME、ASDF_DATA_DIR、BUN_INSTALL、PNPM_HOME）和稳定的用户 bin 目录，但推测的版本管理器回退目录只有在磁盘上存在这些目录时才会被写入服务 PATH。

18. 配置写入 + 向导元数据

Doctor 会保存所有配置更改，并标记向导元数据以记录此次 doctor 运行。

19. 工作区提示（备份 + 记忆系统）

Doctor 会在缺少工作区记忆系统时提示建议，如果工作区尚未受 git 管理，则会打印备份提示。

请参阅 /concepts/agent-workspace 以获取有关工作区结构和 git 备份的完整指南（推荐使用私有的 GitHub 或 GitLab）。

相关

• Gateway(网关) 运维手册
• Gateway(网关) 故障排除