其他检查和修复

除其他页面中记录的运行姿态和维护模式外，openclaw doctor 还会执行以下剩余检查和修复。

模式与提示¶

• 在 Nix 模式（OPENCLAW_NIX_MODE=1）下，只读 doctor 检查仍然可用，但 doctor --fix、doctor --repair、doctor --yes 和 doctor --generate-gateway-token 会被禁用，因为 openclaw.json 是不可变的。请改为编辑此安装的 Nix 源；对于 nix-openclaw，请使用代理优先的快速开始。
• 交互式提示（keychain/OAuth 修复等）仅在 stdin 是 TTY 且未设置 --non-interactive 时运行。无头运行（cron、Telegram、无终端）会跳过提示。
• 独立的非交互模式会跳过提示，但不会跳过完整的 provider-catalog 或 runtime-tool 验证。更新时的可选检查可以带警告延迟。已构建的 checkout 运行会复用这些检查中可用的已编译插件条目；有意的源覆盖仍会执行源代码。参见开发调试。
• --lint 比 --non-interactive 更严格：始终只读，从不提示，从不应用安全迁移。当你希望 doctor 进行更改时，请使用 doctor --fix 或 doctor --repair。
• 默认情况下，Doctor 在检查 secrets 时不会执行 exec SecretRefs。只有当你有意希望 doctor 运行这些已配置的 secret 解析器时，才使用 --allow-exec（无论是否带 --lint）。

配置写入与备份¶

• 在 npm 全局安装中，Doctor 会报告位于已安装包旁边的保留 .openclaw.package-backup-*.databases 目录（以及 .openclaw-package-backup-*.databases，这是清理失败后将其归档使用的名称），并显示其常规文件总大小（以字节和人类可读单位表示）以及每个目录的带引号的删除命令。扫描是有界的；不完整的大小是下限。如果在找到任何快照之前检查不完整，Doctor 会发出警告，并要求你手动列出 npm 全局根目录，包括隐藏条目。缺少全局根目录不会产生警告。这仅为警告，包括使用 --fix 时：在手动删除之前，请确认没有更新正在进行，并且没有恢复操作需要这些快照。由更新器驱动的 Doctor 运行会延迟此检查，以免报告活动更新的快照；请在更新稳定后运行独立的 Doctor。
• 任何配置写入（包括 --fix 修复）都会将备份轮换到 ~/.openclaw/openclaw.json.bak（带有编号的 .bak.1...bak.4 环形备份）。--fix 还会删除 schema 验证报告的未知配置键，并列出每个删除项；在更新进行时，它会跳过此操作，以免在迁移完成前剥离部分写入的升级状态。
• 如果 openclaw.json 无法解析，且无法恢复最后已知良好的配置，doctor --fix 会保持文件不变，并以错误退出，而不是写入部分替换。错误会指向 openclaw config validate 以获取精确的解析位置，并说明如何编辑或重新生成配置。

Gateway 与服务修复¶

• 当另一个 supervisor 拥有 gateway 生命周期时，请设置 OPENCLAW_SERVICE_REPAIR_POLICY=external。让该所有者停止 Gateway，以状态拥有者账户运行 Doctor，然后通过该所有者重启。Doctor 会跳过原生维护检查和服务变更，包括 install/start/restart/bootstrap 和旧版服务清理；它会保留 Gateway/state 协调器和 agent-database 租约检查，报告服务健康状态，并应用非服务修复。参见现有系统 LaunchDaemons。
• Doctor 和 gateway status --deep 会区分不可用的 launchd 域、缺失的 systemd 用户总线以及原生探测访问被拒绝。有关运行时环境、dbus-user-session 和外部 supervisor 的指导，请参见Gateway 和服务恢复。
• Doctor 会报告受管 Gateway 已应用的堆限制，以及用于当前主机或容器内存限制的自适应推导。在非修复运行中，请使用 openclaw gateway status 获取相同报告。
• 当管理器报告某个单元被屏蔽或以其他方式未加载时，Doctor 和 openclaw gateway status 会跳过 systemd 内容修复建议。已加载单元检查、管理器查询失败后的可读文件回退，以及无关的备份或凭据诊断仍保持活动。
• 在 Linux 上，doctor 会忽略非活动的额外 gateway 类 systemd 单元，并在 systemd gateway 服务处于活动状态时不重写 command/entrypoint 元数据；显式修复会在协调安装漂移之前停止符合条件的服务。请使用 openclaw gateway install --force 重写受管基础单元。如果 systemd drop-in 覆盖了 ExecStart= 或 WorkingDirectory=，请使用 systemctl --user cat <unit>.service 检查它，并自行更新或删除该 drop-in；重新安装基础单元不会替换它。Environment= drop-in 仍受支持。
• doctor --fix --non-interactive 会保留已安装的启动器和环境，但先前运行服务中符合条件的安装漂移除外，包括更新修复期间。另外，Linux 策略刷新会备份过时的 OpenClaw 单元设置，确认 daemon-reload，并在维护前验证有效的关闭超时。操作员 drop-in 保持不变。较短或未知的常驻关闭预算会使用有界生命周期排空；报告的写入保管会拒绝截止停止，而中断的回合会产生警告。已停止的服务保留其启动器和停止状态；其 Linux 策略可以在不激活的情况下刷新。对于缺失的服务，请运行 openclaw gateway install；或者从预期安装运行 openclaw gateway install --force，以替换其启动器和受管环境。

会话状态与 cron¶

• 状态完整性检查会检测 sessions 目录中的孤立 transcript 文件。将它们归档为 .deleted.<timestamp> 需要交互式确认；--fix、--yes 和无头运行会将它们保留在原位。
• Doctor 会扫描历史 ~/.openclaw/cron/jobs.json 存储以及先前配置的旧版存储位置，查找旧版 cron 作业形状，将作业和隔离记录导入 SQLite，并归档已迁移的 JSON 文件。
• Doctor 会报告带有显式 payload.model 覆盖的 cron 作业，包括 provider-namespace 计数以及与 agents.defaults.model 的不匹配，以便在身份验证或计费调查期间，可以看到未继承默认模型的计划作业。
• 当已配置的后端支持原生工具捕获时，Doctor 会报告自动捕获的作业工具列表，其中不包含任何原生能力。较早的捕获可能省略原生工具；有意受限的作业可以保持原样。Doctor 从不扩大这些列表，包括使用 --fix 时。要更改列表，请从持有这些工具的授权会话中使用 openclaw cron edit <id> --tools "<complete list>" --json，包括作业应保留的每个工具。
• Doctor 会报告仍标记为进行中（state.runningAtMs）的 cron 作业，这可能导致 openclaw cron list 将它们显示为 running。此检查是只读的：如果当前没有 Gateway 正在执行已标记的作业，下一次 cron 服务启动会记录中断的运行并清除标记。

工具与通道策略¶

• Doctor 每次运行检查一次活动工具模式，在集群中共享插件注册，同时检查每个代理的工具工厂、策略和所选模型。失败的插件注册和清理会产生发现项，而不会隐藏健康代理的结果。如果模型需要实时提供商发现，Doctor 会报告其模型特定的模式检查已被推迟；正常经过身份验证的代理使用会执行该发现。独立 lint 保留其只读目录检查。更新时的检查可以通过记录警告来推迟。
• Doctor 报告名为 image 的旧图像检查策略条目。openclaw doctor --fix 将受支持的配置允许/拒绝面和持久化自动化 toolsAllow 条目重写为 view_image；仅旧名称的通配符模式（例如 image*）会被保留并增加显式的 view_image，而已经覆盖两个名称的模式保持不变。运行时仅暴露规范名称。
• 在 Linux 上，当用户的 crontab 仍在运行未维护的旧版 ~/.openclaw/bin/ensure-whatsapp.sh 时，doctor 会发出警告；当 cron 缺少 systemd 用户总线环境时，它可能会错误报告 Gateway inactive。
• 当 WhatsApp 启用时，doctor 可以报告 Gateway 压力和检测到的本地 TUI 客户端。这些观察结果不会识别原因，也不会将某个客户端连接到该 Gateway。在决定是否关闭客户端之前，请检查 Gateway 诊断；Doctor 不会停止它们。
• 当存在 HTTP(S) 代理环境变量但 tools.web.fetch.useTrustedEnvProxy 被禁用时，doctor 会说明 web_fetch 仍使用直接路由，运行一个简短的直接 TLS 连接探测，并指明显式选择加入项。它永远不会自动启用代理信任。

模型与身份验证¶

• Doctor 将旧版 codex/* 和 openai-codex/* 模型引用重写为规范的 openai/* 引用，覆盖主要模型、回退项、模型允许列表、图像/视频生成模型、心跳/子代理/压缩覆盖项、钩子、通道模型覆盖项、cron 负载以及过期的会话/转录路由固定项。--fix 还会在安全时合并旧版 models.providers.codex 和 models.providers.openai-codex 配置，将旧版 openai-codex:* 身份验证配置文件和 auth.order.openai-codex 条目迁移到 openai:*，将 Codex 意图移动到提供商/模型范围的 agentRuntime.id: "codex" 条目上，移除过期的整个代理/会话运行时固定项，并让修复后的 OpenAI 代理引用继续使用 Codex 身份验证路由，而不是直接使用 OpenAI API 密钥身份验证。
• Doctor 还会修复首选媒体选择中已退役的模型名称，并转换回退列表、模型映射、媒体槽位以及会话提供商/模型对中的 CLI 编码模型引用。迁移后的代理选择保留每个模型的运行时选择；显式规范运行时和会话运行时覆盖项优先。规范条目在冲突中胜出，而缺失的嵌套设置会被保留。这些引用修复会保留账户固定项、自定义命名空间模型 ID 和会话绑定。
• 当活动模型引用命名了已知提供商，但缺失于该提供商的本地目录时，Doctor 会报告一条信息发现项。离线不提供目录行的提供商（例如 OpenRouter，其目录在运行时发现）会被跳过，因为那里未列出的 id 并不是拼写错误的证据。
• doctor --fix 在移除旧字段之前，将旧的仅限 Claude 的会话 ID 移动到以提供商为键的会话绑定中。现有绑定及其恢复元数据优先。空绑定或歧义绑定会保留并带有协调警告，同时安全会话会迁移。当 Doctor 清除配置路由之外的过期 Claude 路由状态时，它也会清除旧字段，以便迁移无法恢复该会话。在恢复仅具有旧字段的会话之前，请在升级后运行此修复；运行时查找和正常保存使用以提供商为键的绑定。
• doctor --fix 会迁移现有共享和代理 SQLite 存储以及旧版 JSON 导入中已退役的身份验证提供商和配置文件标识符。它保留凭据和账户元数据，对冲突使用未使用的配置文件 ID，并一起更新配置引用和轮换状态。现有迁移收据在存储路径中断或配置写入失败时保留已验证的账户映射；更改的账户不会在重试时被采用。显式空配置顺序保持为空。无法读取的存储和未解析的凭据域保持不变并带有诊断信息；独立的存储仍可以迁移。
• Doctor 报告非空的 auth.order.<provider> 列表，其中引用的配置文件全部消失，而兼容的已存储凭据存在。doctor --fix 仅删除这些过期覆盖项，恢复自动的每个代理凭据选择；显式空顺序、部分活动列表以及没有兼容已存储凭据的顺序保持不变。如果活动的 SQLite 身份验证存储无法读取或格式错误，doctor 会解释为何跳过此修复。如果其配置重载模式不会自动应用写入，请在重新检查身份验证状态之前重启正在运行的 Gateway。
• 当 doctor --fix 移除过期的代理本地 OAuth 副本，以便代理继承共享账户时，它会保留该账户在代理已保存身份验证顺序中的位置。已移除副本的本地冷却和成功状态会被清除；共享凭据和其他本地账户保持不变。当 Doctor 在更新期间运行时，这也适用。

插件与技能¶

• doctor --fix 在维护期间回收被遗弃的旧版插件捕获和保留的更新器运行时。仅不熟悉启动器语法不会阻止清理，如果可读的工作目录和包证据表明进程无关。绝对入口点路径仍然需要可读的外部包身份。OpenClaw 身份、入口点和模块引用、捕获/运行时路径以及原生捕获保管会保留活动工件。无法读取的同用户参数或未解析的工作目录、脚本、包或服务标记证据会使清理跳过并带有警告；证据检查失败永远不会被视为进程无关的证据。
• 首次写入的原生会话目录隐私偏好不会启用插件或扩展 plugins.allow。Doctor 在启用的 Codex 条目仅包含目录选择退出项，并匹配 OpenClaw 2026.9.3/9.4 中可能的意外启用时发出警告。此签名无法区分旧的自动写入和有意选择，因此 --fix 会保留它。如果你没有启用 Codex，请将 plugins.entries.codex.enabled 设置为 false，如果存在则从 plugins.allow 中移除 codex，并保留其他条目。
• Doctor 保留其他安装或配置文件可能仍在使用的旧版共享插件运行时缓存，并仅移除真正悬空的插件运行时符号链接。它会为声明它作为对等依赖的受管理 npm 插件重新链接主机 openclaw 包。它还会修复配置中引用的缺失可下载插件（plugins.entries、已配置通道、已配置提供商/搜索设置、已配置代理运行时）。在包更新期间，doctor 会跳过包管理器插件修复，直到包交换完成；如果已配置插件仍需要恢复，之后重新运行 openclaw doctor --fix。如果下载失败，doctor 会报告安装错误并保留已配置的插件条目，以便下次修复尝试。
• doctor --fix 还会使用与 openclaw update 相同的插件更新器，将漂移的活动官方 npm 插件从 OpenClaw 目录更新到已安装的 OpenClaw 版本。记录的非默认标签和比版本插件队列更新的固定项会保留其选定目标。它会报告每个结果并重新检查重启就绪状态。无法获取的插件会保持为带有失败原因的警告；其他插件仍可以修复，Doctor 可以完成。此修复不会更改第三方插件。正常的 Gateway 维护和重启策略 适用；当 Doctor 没有为你重启 Gateway 时，请遵循打印的重启命令。
• 当插件发现健康时，Doctor 通过从 plugins.allow/plugins.deny/plugins.entries 中移除缺失的插件 id，以及匹配的悬空通道配置、心跳目标和通道模型覆盖项，来修复过期的插件配置。
• Doctor 通过禁用受影响的 plugins.entries.<id> 条目并移除其无效的 config 负载来隔离无效的插件配置。Gateway 启动已经仅跳过该错误插件，因此其他插件和通道继续运行。
• Doctor 移除已退役的 plugins.entries.codex.config.codexDynamicToolsProfile；Codex 应用服务器始终将 Codex 原生工作区工具保持为原生。
• Doctor 自动迁移旧版扁平 Talk 配置（talk.voiceId、talk.modelId 等）到 talk.provider + talk.providers.<provider>。重复运行 doctor --fix 时，如果唯一差异是对象键顺序，则不再报告/应用 Talk 规范化。
• Doctor 包含内存搜索就绪检查，并可以在嵌入凭据缺失时推荐 openclaw configure --section model。
• Doctor 在未配置命令所有者时发出警告。命令所有者是允许运行仅限所有者的命令并批准危险操作的人类操作员账户。DM 配对仅允许某人与机器人交谈；如果你在首次所有者引导存在之前批准了发送者，请显式设置 commands.ownerAllowFrom。
• 当配置了 Codex 模式代理，并且操作员 Codex 主目录中存在个人 Codex CLI 资产时，Doctor 会报告一条信息说明。本地 Codex 应用服务器启动使用隔离的每个代理主目录；如有需要，先安装 Codex 插件，然后使用 openclaw migrate plan codex 清点应有意提升的资产。
• Doctor 在默认代理允许的技能在当前运行时环境中不可用时发出警告（缺少二进制文件、环境变量、配置或操作系统要求）。doctor --fix 可以使用 skills.entries.<skill>.enabled=false 禁用这些不可用的技能，并列出更改，而不要求你重复修复。更新器驱动的修复不会更改可选技能启用状态。如果你想保持技能活动，请改为安装/配置缺失的要求。
• 如果较早的 Doctor 运行禁用了可工作的 sag 技能，请使用 openclaw config set skills.entries.sag.enabled true 重新启用它。

沙箱¶

• 如果已启用沙箱模式但 Docker 不可用，doctor 会报告包含修复措施的高信号警告（install Docker 或 openclaw config set agents.defaults.sandbox.mode off）。
• doctor 会识别每个代理的 agents.entries.<id>.sandbox 中在共享作用域下被忽略的 Docker、浏览器和 prune 覆盖。它还会在某个代理的显式主模型省略回退、从而禁用默认回退链时发出警告；这两项诊断均使用旧版名册规范化后的规范代理路径。
• 如果存在旧版沙箱注册表文件或分片目录（~/.openclaw/sandbox/containers.json、~/.openclaw/sandbox/browsers.json、~/.openclaw/sandbox/containers/ 或 ~/.openclaw/sandbox/browsers/），doctor 会报告它们；--fix 会将有效条目迁移到 SQLite，并隔离无效的旧版文件。

密钥与渠道凭据¶

• 如果 gateway.auth.token/gateway.auth.password 由 SecretRef 管理，并且在当前命令路径中不可用，doctor 会报告只读警告，并且不会写入明文回退凭据。对于基于 exec 的 SecretRef，除非存在 --allow-exec，否则 doctor 会跳过执行。
• 如果修复路径中渠道 SecretRef 检查失败，doctor 会继续执行并报告警告，而不是提前退出。
• 在状态目录迁移后，如果已启用的默认 Telegram 或 Discord 账户依赖环境变量回退，且 TELEGRAM_BOT_TOKEN 或 DISCORD_BOT_TOKEN 对 doctor 进程不可用，doctor 会发出警告。
• Telegram allowFrom 用户名自动解析（doctor --fix）需要在当前命令路径中存在可解析的 Telegram Token。如果 Token 检查不可用，doctor 会报告警告，并在该次执行中跳过自动解析。