跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
快速开始

openclaw doctor

​
无头和自动化模式

openclaw doctor --yes
不提示即接受默认值（包括适用时的重启/服务/沙箱修复步骤）。
如果你想在写入前审查更改，请先打开配置文件： 
cat ~/.openclaw/openclaw.json

​
它会做什么（摘要）

  • 对 git 安装执行可选的预检更新（仅交互模式）。
  • UI 协议新鲜度检查（当协议 schema 较新时重建 Control UI）。
  • 健康检查 + 重启提示。
  • Skills Status 摘要（可用/缺失/被阻止）和插件 Status。
  • 针对旧版值的配置规范化。
  • 将 Talk 配置从旧版扁平 talk.* 字段迁移到 talk.provider + talk.providers.<provider>。
  • 浏览器迁移检查，覆盖旧版 Chrome 扩展配置和 Chrome MCP 就绪状态。
  • OpenCode 提供商覆盖警告（models.providers.opencode / models.providers.opencode-go）。
  • Codex OAuth 遮蔽警告（models.providers.openai-codex）。
  • OpenAI Codex OAuth profile 的 OAuth TLS 前置条件检查。
  • 当 plugins.allow 具有限制性但工具策略仍请求通配符或插件拥有的工具时，发出插件/工具 allowlist 警告。
  • 旧版磁盘状态迁移（会话/agent 目录/WhatsApp auth）。
  • 旧版插件清单契约键迁移（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders → contracts）。
  • 旧版 cron 存储迁移（jobId、schedule.cron、顶层 delivery/payload 字段、payload provider、简单 notify: true webhook fallback jobs）。
  • 旧版智能体 runtime-policy 迁移到 agents.defaults.agentRuntime 和 agents.list[].agentRuntime。
  • 启用插件时清理过期插件配置；当 plugins.enabled=false 时，过期插件引用会被视为惰性的 containment 配置并被保留。
  • 会话锁文件检查和过期锁清理。
  • 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话 transcript。
  • 检测卡住的 subagent 重启恢复 tombstone，支持使用 --fix 清除过期的已中止恢复标志，避免启动时继续将子进程视为 restart-aborted。
  • 状态完整性和权限检查（会话、transcript、状态目录）。
  • 本地运行时检查配置文件权限（chmod 600）。
  • 模型 auth 健康：检查 OAuth 过期状态，可刷新即将过期的 token，并报告 auth-profile cooldown/disabled 状态。
  • 额外工作区目录检测（~/openclaw）。
  • 启用沙箱隔离时修复沙箱镜像。
  • 旧版服务迁移和额外 Gateway 网关检测。
  • Matrix 渠道旧版状态迁移（在 --fix / --repair 模式下）。
  • Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd label）。
  • 渠道 Status 警告（从正在运行的 Gateway 网关探测）。
  • supervisor 配置审计（launchd/systemd/schtasks），可选择修复。
  • 清理 Gateway 网关服务的嵌入式 proxy 环境，这些服务在安装或更新期间捕获了 shell HTTP_PROXY / HTTPS_PROXY / NO_PROXY 值。
  • Gateway 网关运行时最佳实践检查（Node vs Bun，版本管理器路径）。
  • Gateway 网关端口冲突诊断（默认 18789）。
  • 针对开放私信策略的安全警告。
  • local token 模式的 Gateway 网关 auth 检查（当不存在 token 来源时提供 token 生成；不会覆盖 token SecretRef 配置）。
  • 设备配对问题检测（待处理的首次配对请求、待处理的 role/scope 升级、过期本地 device-token 缓存漂移，以及 paired-record auth 漂移）。
  • Linux 上的 systemd linger 检查。
  • 工作区 bootstrap 文件大小检查（针对 context 文件的截断/接近限制警告）。
  • 默认智能体的 Skills 就绪检查；报告缺少 bin、env、配置或 OS 要求的已允许 Skills，并且 --fix 可在 skills.entries 中禁用不可用的 Skills。
  • shell completion Status 检查和自动安装/升级。
  • 记忆搜索 embedding 提供商就绪检查（本地模型、远程 API key 或 QMD binary）。
  • 源码安装检查（pnpm workspace mismatch、缺失 UI assets、缺失 tsx binary）。
  • 写入更新后的配置 + 向导元数据。

​
Dreams UI 回填和重置

Control UI 的 Dreams scene 包含用于 grounded dreaming 工作流的 Backfill、Reset 和 Clear Grounded 操作。这些操作使用 Gateway 网关 doctor-style RPC 方法，但它们不是 openclaw doctor CLI 修复/迁移的一部分。 它们会做什么：
  • Backfill 扫描活动工作区中的历史 memory/YYYY-MM-DD.md 文件，运行 grounded REM diary pass，并将可逆的回填条目写入 DREAMS.md。
  • Reset 只从 DREAMS.md 中移除那些已标记的回填 diary 条目。
  • Clear Grounded 只移除来自历史 replay、尚未积累 live recall 或 daily support 的 staged grounded-only short-term 条目。
它们本身不会做什么：
  • 它们不会编辑 MEMORY.md
  • 它们不会运行完整 doctor 迁移
  • 它们不会自动将 grounded candidates stage 到 live short-term promotion store，除非你先显式运行 staged CLI path
如果你想让 grounded historical replay 影响正常的 deep promotion lane，请改用 CLI 流程： 
openclaw memory rem-backfill --path ./memory --stage-short-term
这会将 grounded durable candidates stage 到 short-term dreaming store，同时将 DREAMS.md 保留为审查界面。

​
详细行为和理由

如果这是 git checkout 且 doctor 正在交互式运行，它会在运行 doctor 前提供更新（fetch/rebase/build）选项。
如果配置包含旧版值形状（例如没有渠道专属覆盖的 messages.ackReaction），doctor 会将它们规范化为当前 schema。这包括旧版 Talk 扁平字段。当前公开的 Talk 配置是 talk.provider + talk.providers.<provider>。Doctor 会将旧的 talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey 形状重写到 provider map 中。当 plugins.allow 非空且工具策略使用 通配符或插件拥有的工具条目时，Doctor 也会发出警告。tools.allow: ["*"] 只匹配 实际加载的插件中的工具；它不会绕过独占插件 allowlist。Doctor 会为已迁移的 旧版 allowlist 配置写入 plugins.bundledDiscovery: "compat"， 以保留现有内置提供商行为，然后指向更严格的 "allowlist" 设置。
当配置包含已弃用键时，其他命令会拒绝运行，并要求你运行 openclaw doctor。Doctor 将会：
  • 说明发现了哪些旧版键。
  • 显示它应用的迁移。
  • 使用更新后的 schema 重写 ~/.openclaw/openclaw.json。
Gateway 网关在启动时检测到旧版配置格式时，也会自动运行 doctor 迁移，因此过期配置无需人工干预即可修复。Cron job store 迁移由 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
  • 缺少可见回复策略的已配置渠道配置 → messages.groupChat.visibleReplies: "message_tool"
  • 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.<provider>
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • messages.tts.<provider>（openai/elevenlabs/microsoft/edge）→ messages.tts.providers.<provider>
  • messages.tts.provider: "edge" 和 messages.tts.providers.edge → messages.tts.provider: "microsoft" 和 messages.tts.providers.microsoft
  • channels.discord.voice.tts.<provider>（openai/elevenlabs/microsoft/edge）→ channels.discord.voice.tts.providers.<provider>
  • channels.discord.accounts.<id>.voice.tts.<provider>（openai/elevenlabs/microsoft/edge）→ channels.discord.accounts.<id>.voice.tts.providers.<provider>
  • plugins.entries.voice-call.config.tts.<provider>（openai/elevenlabs/microsoft/edge）→ plugins.entries.voice-call.config.tts.providers.<provider>
  • 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.default；Matrix 可以保留现有的匹配命名/默认目标）
  • identity → agents.list[].identity
  • agent.* → agents.defaults + tools.*（工具/提升权限/执行/沙箱/子智能体）
  • agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks
  • 移除 agents.defaults.llm；对慢速提供商/模型超时使用 models.providers.<id>.timeoutSeconds
  • browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
  • browser.profiles.*.driver: "extension" → "existing-session"
  • 移除 browser.relayBindHost（旧版插件中继设置）
  • 旧版 models.providers.*.api: "openai" → "openai-completions"（Gateway 网关启动时也会跳过 api 设置为未来或未知枚举值的提供商，而不是关闭失败）
Doctor 警告还包括多账号渠道的账号默认值指导：
  • 如果配置了两个或更多 channels.<channel>.accounts 条目，但未配置 channels.<channel>.defaultAccount 或 accounts.default，Doctor 会警告回退路由可能选中意外的账号。
  • 如果 channels.<channel>.defaultAccount 设置为未知账号 ID，Doctor 会警告并列出已配置的账号 ID。
如果你手动添加了 models.providers.opencode、opencode-zen 或 opencode-go，它会覆盖来自 @mariozechner/pi-ai 的内置 OpenCode 目录。这可能会强制模型使用错误的 API，或将成本清零。Doctor 会发出警告，以便你移除该覆盖项并恢复按模型的 API 路由和成本。
如果你的浏览器配置仍指向已移除的 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 仍然需要：
  • Gateway 网关/节点主机上有基于 Chromium 的浏览器 144+
  • 浏览器在本地运行
  • 该浏览器中已启用远程调试
  • 在浏览器中批准首次附加同意提示
这里的就绪状态仅关乎本地附加前置条件。Existing-session 保持当前 Chrome MCP 路由限制；responsebody、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。此检查不适用于 Docker、沙箱、远程浏览器或其他无头流程。它们会继续使用原始 CDP。
配置 OpenAI Codex OAuth 配置文件后，Doctor 会探测 OpenAI 授权端点，验证本地 Node/OpenSSL TLS 栈能否验证证书链。如果探测因证书错误而失败（例如 UNABLE_TO_GET_ISSUER_CERT_LOCALLY、证书过期或自签名证书），Doctor 会输出特定于平台的修复指导。在 macOS 上使用 Homebrew Node 时，修复通常是 brew postinstall ca-certificates。使用 --deep 时，即使 Gateway 网关健康，探测也会运行。
如果你之前在 models.providers.openai-codex 下添加过旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth 同时存在时会发出警告，以便你移除或重写过时的传输覆盖项，并恢复内置路由/回退行为。自定义代理和仅标头覆盖仍受支持，且不会触发此警告。
启用内置 Codex 插件时，Doctor 还会检查 openai-codex/* 主模型引用是否仍通过默认 PI 运行器解析。当你希望通过 PI 使用 Codex OAuth/订阅凭证时，此组合是有效的，但它很容易与原生 Codex 应用服务器 harness 混淆。Doctor 会发出警告，并指向显式应用服务器形态：openai/* 加 agentRuntime.id: "codex" 或 OPENCLAW_AGENT_RUNTIME=codex。Doctor 不会自动修复此问题，因为两条路由都有效：
  • openai-codex/* + PI 表示“通过普通 OpenClaw 运行器使用 Codex OAuth/订阅凭证。”
  • openai/* + agentRuntime.id: "codex" 表示“通过原生 Codex app-server 运行嵌入式轮次。”
  • /codex ... 表示“从聊天中控制或绑定原生 Codex 对话。”
  • /acp ... 或 runtime: "acp" 表示“使用外部 ACP/acpx 适配器。”
如果出现该警告，请选择你原本打算使用的路由并手动编辑配置。当 PI Codex OAuth 是有意使用时，请保持该警告不变。
在你将配置的默认/回退模型或运行时从 Codex 这类插件拥有的路由移开后，Doctor 还会扫描活动会话存储中陈旧的自动创建路由状态。openclaw doctor --fix 可以清除自动创建的陈旧状态，例如 modelOverrideSource: "auto" 模型固定、运行时模型元数据、固定的 harness ID、CLI 会话绑定，以及拥有路由不再配置时的自动凭证配置覆盖。显式用户或旧版会话模型选择会被报告以供手动审查，并保持不变；当不再打算使用该路由时，请用 /model ...、/new 切换它们，或重置会话。
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 将任何旧版文件夹作为备份留在原处时，它会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + 智能体目录，因此历史记录/凭证/模型无需手动运行 Doctor 即可落到按智能体划分的路径中。WhatsApp 凭证有意只通过 openclaw doctor 迁移。Talk 提供商/provider-map 规范化现在按结构相等性比较，因此仅键顺序不同的差异不再触发重复的无操作 doctor --fix 更改。
Doctor 会扫描所有已安装插件清单，查找已弃用的顶级能力键（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders）。找到后，它会提示将它们移入 contracts 对象，并就地重写清单文件。此迁移是幂等的；如果 contracts 键已经有相同的值，则会移除旧版键，而不会重复数据。
Doctor 还会检查 cron 作业存储（默认是 ~/.openclaw/cron/jobs.json，覆盖时为 cron.store），查找调度器为了兼容性仍接受的旧作业形态。当前 cron 清理包括：
  • jobId → id
  • schedule.cron → schedule.expr
  • 顶级载荷字段（message、model、thinking、…）→ payload
  • 顶级递送字段（deliver、channel、to、provider、…）→ delivery
  • 载荷 provider 递送别名 → 显式 delivery.channel
  • 简单旧版 notify: true webhook 后备作业 → 显式 delivery.mode="webhook"，并设置 delivery.to=cron.webhook
Doctor 只会在不改变行为的情况下自动迁移 notify: true 作业。如果某个作业将旧版通知后备与现有的非 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 执行当前健康检查。
Doctor 会扫描每个智能体会话目录，查找过时的写入锁文件，也就是会话异常退出后留下的文件。对于找到的每个锁文件，它会报告：路径、PID、该 PID 是否仍然存活、锁的存在时长，以及是否被视为过时（PID 已死或超过 30 分钟）。在 --fix / --repair 模式下，它会自动移除过时的锁文件；否则会打印一条说明，并指示你使用 --fix 重新运行。
Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 提示词转录重写错误创建的重复分支形态：一个被废弃的用户轮次，包含 OpenClaw 内部运行时上下文，以及一个活跃的同级分支，包含相同的可见用户提示词。在 --fix / --repair 模式下，Doctor 会在原文件旁备份每个受影响文件，并将转录重写为活跃分支，这样 Gateway 网关历史记录和记忆读取器就不再看到重复轮次。
状态目录是运行中的关键中枢。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他地方有备份）。Doctor 会检查：
  • 状态目录缺失：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复缺失数据。
  • 状态目录权限：验证可写性；提供修复权限的选项（并在检测到所有者/组不匹配时发出 chown 提示）。
  • macOS 云同步状态目录：当状态解析到 iCloud Drive（~/Library/Mobile Documents/com~apple~CloudDocs/...）或 ~/Library/CloudStorage/... 下时发出警告，因为由同步支持的路径可能导致更慢的 I/O 和锁定/同步竞争。
  • Linux SD 或 eMMC 状态目录：当状态解析到 mmcblk* 挂载源时发出警告，因为由 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入下可能更慢且磨损更快。
  • 会话目录缺失：sessions/ 和会话存储目录是持久化历史记录并避免 ENOENT 崩溃所必需的。
  • 转录不匹配：当最近的会话条目缺少转录文件时发出警告。
  • 主会话“1 行 JSONL”：当主转录只有一行时标记（历史记录没有累积）。
  • 多个状态目录：当多个主目录中存在多个 ~/.openclaw 文件夹，或 OPENCLAW_STATE_DIR 指向其他位置时发出警告（历史记录可能会在安装之间拆分）。
  • 远程模式提醒：如果 gateway.mode=remote，Doctor 会提醒你在远程主机上运行它（状态位于那里）。
  • 配置文件权限：如果 ~/.openclaw/openclaw.json 可被组/全局读取，则发出警告并提供收紧到 600 的选项。
Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API key 或 Anthropic setup-token 路径。刷新提示只会在交互式运行（TTY）时出现；--non-interactive 会跳过刷新尝试。当 OAuth 刷新永久失败时（例如 refresh_token_reused、invalid_grant，或提供商提示你重新登录），Doctor 会报告需要重新认证，并打印要运行的确切 openclaw models auth login --provider ... 命令。Doctor 还会报告由于以下原因暂时不可用的认证配置文件：
  • 短暂冷却（速率限制/超时/认证失败）
  • 更长时间禁用（账单/额度失败）
如果设置了 hooks.gmail.model，Doctor 会根据目录和允许列表验证该模型引用，并在它无法解析或被禁止时发出警告。
启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。
Doctor 会在 openclaw doctor --fix / openclaw doctor --repair 模式下移除旧版 OpenClaw 生成的插件依赖暂存状态。这涵盖过时的生成依赖根目录、旧安装阶段目录、早期内置插件依赖修复代码留下的包本地残留，以及可能遮蔽当前内置清单的孤立或已恢复的托管 npm 内置 @openclaw/* 插件副本。当配置引用可下载插件但本地插件注册表找不到它们时，Doctor 也可以重新安装缺失的可下载插件。示例包括实际的 plugins.entries、已配置的渠道/提供商/搜索设置，以及已配置的 Agent Runtimes。在包更新期间，Doctor 会避免在核心包正在被替换时运行包管理器插件修复；如果配置的插件仍需恢复，请在更新后再次运行 openclaw doctor --fix。Gateway 网关启动和配置重载不会运行包管理器；插件安装仍是显式的 Doctor/安装/更新工作。
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。
当 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，Doctor（在 --fix / --repair 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式下（不带 --fix 的 openclaw doctor），此检查会被完全跳过。
Doctor 现在会在正常健康检查中检查设备配对状态。它会报告：
  • 待处理的首次配对请求
  • 已配对设备的待处理角色升级
  • 已配对设备的待处理作用域升级
  • 设备 ID 仍匹配但设备身份不再匹配已批准记录的公钥不匹配修复
  • 缺少已批准角色活跃令牌的配对记录
  • 作用域漂移出已批准配对基线的配对令牌
  • 当前机器上早于 Gateway 网关侧令牌轮换或携带过时作用域元数据的本地缓存设备令牌条目
Doctor 不会自动批准配对请求或自动轮换设备令牌。它会改为打印确切的后续步骤：
  • 使用 openclaw devices list 检查待处理请求
  • 使用 openclaw devices approve <requestId> 批准确切请求
  • 使用 openclaw devices rotate --device <deviceId> --role <role> 轮换新令牌
  • 使用 openclaw devices remove <deviceId> 移除并重新批准过时记录
这修复了常见的“已经配对但仍收到需要配对”缺口：Doctor 现在会区分首次配对、待处理的角色/作用域升级，以及过时令牌/设备身份漂移。
当提供商在没有允许列表的情况下向私信开放，或策略以危险方式配置时，Doctor 会发出警告。
如果作为 systemd 用户服务运行，Doctor 会确保已启用 linger，使 Gateway 网关在注销后仍保持运行。
Doctor 会打印默认智能体的工作区状态摘要：
  • Skills 状态：统计符合条件、缺少要求以及被允许列表阻止的 Skills。
  • 旧版工作区目录：当 ~/openclaw 或其他旧版工作区目录与当前工作区并存时发出警告。
  • 插件状态：统计已启用/已禁用/出错的插件；列出任何错误对应的插件 ID；报告内置插件能力。
  • 插件兼容性警告：标记与当前运行时存在兼容性问题的插件。
  • 插件诊断：呈现插件注册表在加载时发出的任何警告或错误。
Doctor 会检查工作区 bootstrap 文件（例如 AGENTS.md、CLAUDE.md 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（max/file 或 max/total），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，Doctor 会打印用于调优 agents.defaults.bootstrapMaxChars 和 agents.defaults.bootstrapTotalMaxChars 的提示。
当 openclaw doctor --fix 移除缺失的渠道插件时，它也会移除引用该插件的悬空渠道范围配置：channels.<id> 条目、命名该渠道的 Heartbeat 目标，以及 agents.*.models["<channel>/*"] 覆盖。这可以防止渠道运行时已消失但配置仍要求 Gateway 网关绑定到它而导致的 Gateway 网关启动循环。
Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全：
  • 如果 shell 配置文件使用缓慢的动态补全模式（source <(openclaw completion ...)），Doctor 会将其升级为更快的缓存文件变体。
  • 如果补全已在配置文件中配置但缓存文件缺失，Doctor 会自动重新生成缓存。
  • 如果完全没有配置补全，Doctor 会提示安装它（仅交互模式；使用 --non-interactive 时跳过）。
运行 openclaw completion --write-state 可手动重新生成缓存。
Doctor 会检查本地 Gateway 网关令牌认证就绪状态。
  • 如果令牌模式需要令牌且不存在令牌来源，Doctor 会提供生成令牌的选项。
  • 如果 gateway.auth.token 由 SecretRef 管理但不可用，Doctor 会发出警告，并且不会用明文覆盖它。
  • openclaw doctor --generate-gateway-token 仅在未配置令牌 SecretRef 时强制生成。
某些修复流程需要检查已配置的凭证，同时不削弱运行时快速失败行为。
  • openclaw doctor --fix 现在对定向配置修复使用与 status 系列命令相同的只读 SecretRef 摘要模型。
  • 示例：Telegram allowFrom / groupAllowFrom @username 修复会在可用时尝试使用已配置的机器人凭证。
  • 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。
Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提示重启。
Doctor 会检查已配置的记忆搜索嵌入提供商是否已为默认智能体就绪。行为取决于已配置的后端和提供商：
  • QMD 后端：探测 qmd 二进制文件是否可用且可启动。如果不可用，会输出修复指导，包括 npm 包和手动二进制路径选项。
  • 显式本地提供商：检查本地模型文件或可识别的远程/可下载模型 URL。如果缺失，建议切换到远程提供商。
  • 显式远程提供商（openai、voyage 等）：验证环境或认证存储中是否存在 API key。如果缺失，会输出可操作的修复提示。
  • 自动提供商：先检查本地模型可用性，然后按自动选择顺序尝试每个远程提供商。
当缓存的 Gateway 网关探测结果可用时（检查时 Gateway 网关处于健康状态），doctor 会将其结果与 CLI 可见配置交叉比对，并指出任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；当你需要实时提供商检查时，请使用深度记忆 Status 命令。使用 openclaw memory status --deep 在运行时验证嵌入就绪状态。
如果 Gateway 网关健康，doctor 会运行渠道 Status 探测，并报告警告及建议修复方式。
Doctor 会检查已安装的监督程序配置（launchd/systemd/schtasks），查看是否缺少默认值或默认值已过时（例如 systemd network-online 依赖和重启延迟）。发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。说明：
  • openclaw doctor 在重写监督程序配置前会提示。
  • openclaw doctor --yes 接受默认修复提示。
  • openclaw doctor --repair 应用建议修复且不提示。
  • openclaw doctor --repair --force 覆盖自定义监督程序配置。
  • OPENCLAW_SERVICE_REPAIR_POLICY=external 让 doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状态并运行非服务修复，但会跳过服务安装/启动/重启/引导、监督程序配置重写以及旧版服务清理，因为该生命周期由外部监督程序拥有。
  • 在 Linux 上，当匹配的 systemd Gateway 网关单元处于活动状态时，doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略非活动的非旧版额外类 Gateway 网关单元，因此配套服务文件不会产生清理噪音。
  • 如果令牌认证需要令牌，并且 gateway.auth.token 由 SecretRef 管理，doctor 服务安装/修复会验证 SecretRef，但不会将解析后的明文令牌值持久化到监督程序服务环境元数据中。
  • Doctor 会检测较旧的 LaunchAgent、systemd 或 Windows 计划任务安装以内联方式嵌入的托管 .env/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时来源加载，而不是从监督程序定义加载。
  • Doctor 会检测服务命令是否在 gateway.port 更改后仍固定旧的 --port，并将服务元数据重写为当前端口。
  • 如果令牌认证需要令牌且配置的令牌 SecretRef 未解析，doctor 会阻止安装/修复路径，并给出可操作指导。
  • 如果同时配置了 gateway.auth.token 和 gateway.auth.password，且未设置 gateway.auth.mode，doctor 会阻止安装/修复，直到显式设置模式。
  • 对于 Linux user-systemd 单元，doctor 令牌漂移检查现在会在比较服务认证元数据时同时包含 Environment= 和 EnvironmentFile= 来源。
  • 当配置最后由较新版本写入时，Doctor 服务修复会拒绝从较旧的 OpenClaw 二进制文件重写、停止或重启 Gateway 网关服务。参见 Gateway 网关故障排除。
  • 你始终可以通过 openclaw gateway install --force 强制完整重写。
Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 网关端口（默认 18789）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（nvm、fnm、volta、asdf 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径可能会在升级后失效，因为服务不会加载你的 shell 初始化。Doctor 会在系统 Node 安装可用时（Homebrew/apt/choco）提示迁移到它。新安装或修复的 macOS LaunchAgent 会使用规范的系统 PATH（/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin），而不是复制交互式 shell PATH，因此 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。

​
相关内容