跳转至

其他检查与修复

以下内容列出了 openclaw doctor 在其他页面记录的姿态和维护模式之外执行的其余检查与修复。

模式与提示

  • 在 Nix 模式(OPENCLAW_NIX_MODE=1)下,只读的 doctor 检查仍然可用,但 doctor --fix、doctor --repair、doctor --yes 和 doctor --generate-gateway-token 会被禁用,因为 openclaw.json 是不可变的。请改为编辑此安装的 Nix 源;对于 nix-openclaw,请使用 agent-first 的快速入门。
  • 交互式提示(钥匙串/OAuth 修复等)仅当 stdin 是 TTY 且未设置 --non-interactive 时才会运行。无头运行(cron、Telegram、无终端)会跳过提示。
  • 独立的非交互模式会跳过提示,但不会跳过完整的 provider-catalog 或运行时工具验证。更新时的可选检查可以带警告延迟。构建的 checkout 运行会为此类检查复用可用的已编译插件条目;有意的源码覆盖仍会执行源码。请参阅开发调试。
  • --lint 比 --non-interactive 更严格:始终只读,从不提示,从不应用安全迁移。当你希望 doctor 进行更改时,请使用 doctor --fix 或 doctor --repair。
  • 默认情况下,Doctor 在检查机密时不会执行 exec SecretRefs。仅当你有意让 doctor 运行那些配置的机密解析器时,才使用 --allow-exec(可搭配 --lint 或不搭配)。

配置写入与备份

更新历史检查与协调是尽力而为的维护。失败时打印警告,并允许独立的 Doctor 修复和插件注册表变更继续进行。可写运行还会尝试将警告保存到最新的现有 SQLite 更新运行中,而不改变其结果或活动时间戳,也不会创建新的运行。只读运行不写入历史。数据库完整性、迁移和未结算进程清理检查仍会保护变更操作。

快照工作进程使用执行 CLI 的运行时。原生工作进程继承未更改的工作目录,避免了在 sudo -u 切换用户后可能失败的冗余目录更改。生成被拒绝时会指明运行时和工作目录;请检查服务用户的可执行权限和目录访问权限。磁盘空间或 XDG_CACHE_HOME 的指引适用于快照存储失败,而非运行时启动权限。

检查完成后,doctor --fix 会收尾自身的检查工作进程,同时保留维护所有权,然后检查是否可以移除已放弃的更新器运行时。独立的 OpenClaw 进程、Worker 线程和 shared-broker 工作仍会阻止移除。Doctor 会报告持有者的 PID,并请你让它们的工作完成后再重新运行 openclaw doctor --fix。

  • 在 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 以获取精确的解析位置,并解释如何编辑或重新生成配置。

网关与服务修复

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

会话状态与定时任务

  • 状态完整性检查会检测会话目录中的孤立转录文件。将它们归档为 .deleted.<timestamp> 需要交互式确认;--fix、--yes 和无头运行会将其保留在原处。
  • Doctor 会扫描历史 ~/.openclaw/cron/jobs.json 存储以及先前配置的旧版存储位置,查找旧的定时任务结构,将任务和隔离记录导入 SQLite,并归档已迁移的 JSON 文件。
  • Doctor 会报告带有显式 payload.model 覆盖的定时任务,包括 provider 命名空间计数以及与 agents.defaults.model 的不匹配情况,以便在认证或计费调查期间,未继承默认模型的计划任务可见。
  • Doctor 会报告仍标记为进行中(state.runningAtMs)的定时任务,这可能导致 openclaw cron list 将它们显示为 running。此检查为只读:如果当前没有 Gateway 正在执行标记的任务,下一次 cron 服务启动时会记录中断的运行并清除该标记。

工具与频道策略

  • Doctor 每次运行只检查一次活动工具 schema,在检查每个 agent 的工具工厂、策略和所选模型时,在整个 fleet 中共享插件注册。当 agent 在同一个捕获的配置代数内解析到相同的插件源时,模型准备也会共享 provider 注册和配置快照;不同的插件选择和显式的工作区注册表所有者保持独立。失败的插件注册和清理会产生发现,而不会隐藏健康 agent 的结果。如果某个模型需要实时 provider 发现,Doctor 会报告其模型特定的 schema 检查已被推迟;正常的已认证 agent 使用会执行该发现。独立运行的 lint 保留其只读目录检查。更新时的检查可以推迟,并记录警告。
  • Doctor 会报告名为 image 的旧版图像检查策略条目。openclaw doctor --fix 会将受支持的配置 allow/deny 表面和持久化的自动化 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 意图转移到 provider/model 作用域的 agentRuntime.id: "codex" 条目上,移除过期的整个 agent/会话运行时固定,并让修复后的 OpenAI agent 引用保持使用 Codex 认证路由,而不是直接使用 OpenAI API 密钥进行认证。
  • Doctor 还会修复首选媒体选择中的已退役模型名称,并在后备列表、模型映射、媒体槽位和会话 provider/model 对中转换 CLI 编码的模型引用。迁移后的 agent 选择会保留每个模型的运行时选择;显式的规范化运行时和会话运行时覆盖优先。规范化条目在冲突中获胜,同时保留缺失的嵌套设置。这些引用修复会保留账户固定、自定义命名空间的模型 ID 和会话绑定。
  • 当活动模型引用指定了已知 provider 但该 provider 的本地目录中缺少该引用时,Doctor 会报告一个信息类发现。离线时不贡献目录行的 provider(例如 OpenRouter,其目录在运行时发现)会被跳过,因为其中未列出的 id 并不构成拼写错误的证据。
  • doctor --fix 会在移除旧字段之前,将仅限 Claude 的旧对话 ID 移入以 provider 为键的会话绑定中。现有绑定及其恢复元数据优先。空或有歧义的绑定会保留保存,并带有协调警告,而安全的会话会迁移。当 Doctor 清除配置路由之外的过期 Claude 路由状态时,它也会清除旧字段,以便迁移无法恢复该对话。升级后、恢复仅包含旧字段的会话之前,请运行此修复;运行时查找和正常保存使用以 provider 为键的绑定。
  • doctor --fix 会迁移现有共享和 agent SQLite 存储以及旧版 JSON 导入中已退役的认证 provider 和配置文件标识符。它会保留凭据和账户元数据,对冲突使用未使用的配置文件 ID,并同时更新配置引用和轮换状态。现有的迁移收据会在存储遍历中断或配置写入失败时保留已验证的账户映射;重试时不会采用已更改的账户。显式空的配置顺序保持为空。无法读取的存储和未解析的凭据领域保持不变,并附有诊断信息;独立的安全存储仍可迁移。
  • 当 auth.order.<provider> 列表非空但引用的配置文件全部消失,而兼容的已存储凭据仍然存在时,Doctor 会报告此情况。doctor --fix 仅删除这些过期的覆盖,恢复自动的按 agent 凭据选择;显式空的顺序、部分有效的列表以及没有兼容已存储凭据的顺序保持不变。如果活动的 SQLite 认证存储无法读取或格式错误,Doctor 会说明其跳过此修复的原因。如果运行中的 Gateway 的配置重载模式不会自动应用写入,请在重新检查认证状态之前重启该 Gateway。
  • 当 doctor --fix 移除过期的 agent 本地 OAuth 副本以使 agent 继承共享账户时,它会保留该账户在 agent 保存的认证顺序中的位置。已移除副本的本地冷却和成功状态会被清除;共享凭据和其他本地账户保持不变。这同样适用于 Doctor 在更新期间运行的情况。

插件和技能

  • doctor --fix 在维护期间回收被遗弃的旧版插件捕获和保留的更新器运行时。仅凭不熟悉的启动器语法不会阻止清理,前提是可通过可读的工作目录和包证据确定该进程无关。绝对入口点路径仍然需要可读的外部包身份。OpenClaw 身份、入口点和模块引用、捕获/运行时路径以及原生捕获托管会保留活动工件。无法读取的同用户参数,或未解析的工作目录、脚本、包或服务标记证据,会导致清理被跳过并发出警告;证据检查失败永远不会被视为进程无关的证明。
  • 首次写入的原生会话目录隐私偏好不会启用插件或扩展 plugins.allow。当已启用的 Codex 条目仅包含目录退出选项,并匹配 OpenClaw 2026.9.3/9.4 中可能的意外启用时,Doctor 会发出警告。此签名无法区分旧的自动写入和有意选择,因此 --fix 会保留它。如果你没有启用 Codex,请将 plugins.entries.codex.enabled 设置为 false,如果存在,请从 plugins.allow 中移除 codex,同时保留其他条目。
  • Doctor 会保留其他安装或配置可能仍在使用的旧版共享插件运行时缓存,并仅移除真正悬空的插件运行时符号链接。对于声明 openclaw 为对等依赖的受管 npm 插件,它会重新链接宿主 openclaw 包。它还会修复配置中引用的缺失可下载插件(plugins.entries、已配置的渠道、已配置的提供商/搜索设置、已配置的代理运行时)。在包更新期间,doctor 会跳过包管理器插件修复,直到包替换完成;如果某个已配置插件仍需要恢复,请在之后重新运行 openclaw doctor --fix。如果下载失败,doctor 会报告安装错误,并保留已配置的插件条目以供下次修复尝试。
  • doctor --fix 还会使用与 openclaw update 相同的插件更新器,将 OpenClaw 目录中已漂移的活动官方 npm 插件更新到已安装的 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 app-server 始终将 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 app-server 启动使用按代理隔离的主目录;如有需要,请先安装 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、浏览器和修剪覆盖。当代理的显式主模型省略回退项,从而禁用默认的回退链时,它也会发出警告;这两个诊断在旧版名册规范化后使用规范代理路径。
  • 如果存在已退役的沙箱注册表文件或分片目录(~/.openclaw/sandbox/containers.json、~/.openclaw/sandbox/browsers.json、~/.openclaw/sandbox/containers/ 或 ~/.openclaw/sandbox/browsers/),Doctor 会报告它们,并且 --fix 会拒绝操作而不更改其内容。请先升级到 2026.9.7 并在原始主机上运行 openclaw doctor --fix;参见 旧版状态迁移。

密钥和渠道凭据

  • 如果 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 会报告警告并跳过该次运行的自动解析。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw