跳转至

状态、会话与插件修复

检查 3-7b 涵盖旧版磁盘状态迁移、会话完整性、模型认证健康状态、沙箱镜像和插件安装。

检查 3-7b

3. 旧版状态迁移(磁盘布局)

支持的升级来源是 2026 年 7 月 1 日或之后发布的版本所写入的状态形状。七月 Doctor 导入器仍可能在会话行上留下 provider 和 lastProvider 别名。在运行 openclaw doctor --fix 之前,会话读取会以需要迁移的错误拒绝这些行;Doctor 会备份受影响的 SQLite 数据库,然后将这些别名连同其查询投影一起重写为规范的 delivery 状态。仍需要已弃用的 room → groupChannel 转换的行会被拒绝,且不修改原始存储:保留状态,安装 OpenClaw 2026.9.5,运行 openclaw doctor --fix,然后再次升级。即使旁边仍存在过时元数据,具有当前字段的行仍受支持。七月时期的 sessions.json 和 JSONL 转录导入仍受支持。

Doctor 可以将受支持的磁盘布局迁移到当前结构:

  • 会话行和转录:将旧版 sessions.json 和 JSONL 历史从每个代理的 sessions/ 目录或显式配置的存储导入到 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
  • 代理目录:从 ~/.openclaw/agent/ 到 ~/.openclaw/agents/<agentId>/agent/
  • WhatsApp 认证状态(Baileys):从旧版 ~/.openclaw/credentials/*.json(除 oauth.json 外)到 ~/.openclaw/credentials/whatsapp/<accountId>/...(默认账户 ID:default)
  • 签名设备身份:从 ~/.openclaw/identity/device.json 到 state/openclaw.sqlite 中的 primary device_identities 行;Doctor 还负责修复无效的规范行;Gateway 和 node-host 启动时会拒绝未导入的身份,而不是创建替代身份,并且不会改动单独的设备认证文件

六月之前的 tasks/runs.sqlite、flows/registry.sqlite 和 plugin-state/state.sqlite 数据库的导入已弃用。Doctor 不会改动这些文件。需要这些记录的旧安装应 通过 2026.9.5 升级,并在安装 latest 之前运行其 Doctor 迁移;六月及之后的版本已经使用共享状态数据库。

位于 plugins/installs.json 的 JSON 插件索引已弃用。Doctor 会保持其不变,并指导操作员在 2026.9.5 上带着更新前备份运行 openclaw doctor --fix。更新还会在停止正在运行的 Gateway 之前检查此原始文件。当前 SQLite 插件索引和安装记录仍受支持。

已弃用的 Skill Workshop 提案属于 Doctor,包括 openclaw update 期间的修复过程。Doctor 会将每个待处理或已隔离的草稿导出到 <agentDir>/workshop-skills/.archive/.retired-proposals/<proposal-id>/,删除已弃用的提案表,并移除 <state-dir>/skill-workshop/proposals/。正常 Gateway 和本地 CLI 启动不会改动这些产物。导出失败会保留表和文件并报告警告;修复原因后重新运行 openclaw doctor --fix。

被重写或截断的旧版审计原始归档不会阻止 Doctor 或更新最终处理。Doctor 会将其隔离到自身旁边,保留已清理的归档和现有 SQLite 记录,并只报告一次隔离路径。后续修复会继续。有关保留的备份和恢复限制,请参阅 旧版审计恢复。

SQLite 转录和归档中的历史内联助手指令由 Doctor 规范化,包括普通的 openclaw doctor --non-interactive。Gateway 和普通 CLI 启动不会改动这些历史字节。在不使用更新程序替换二进制文件时,如果旧历史仍包含回复、音频、TTS 或表情标记,请在重启前停止 Gateway,并对相同的状态/配置运行 Doctor。官方 容器镜像入口点 会在 Gateway 激活前自动运行 Doctor。此规范化保留其现有的完成游标和已停止写入器检查;它不会启用仅修复维护、服务更改或 exec-approval 迁移。

修复会在停止受管 Gateway 之前,从只读数据库快照准备保留归档媒体的规范化。未更改的归档不需要归档写事务。Doctor 会在现有迁移元数据中记录已验证的内容和文件标识,因此同一版本的另一次运行会跳过解析和读取未更改的归档副本。导入、恢复、已更改的文件和新版本会使这些事实失效;仍会检查规范 blob 摘要。实际修复保留已停止写入器权限和源重新验证。

自动发现不再导入代理之前的 ~/.openclaw/sessions/ 布局。显式会话存储路径仍受支持,包括位于该位置的已配置路径。

旧版会话文件导入和修复属于 Doctor。Gateway 启动会检查就绪状态,而不会导入这些文件;运行时会话访问仅使用 SQLite。无法读取的旧版会话索引及其转录会保留在原始路径,重复启动会以活动配置文件的 Doctor 命令拒绝就绪。停止 Gateway,备份其状态,修复指定源,并在重启前运行 openclaw doctor --fix。针对性迁移序列 提供检查和验证证据。当前 SQLite 维护不要求旧版文件保留在磁盘上。

当不可用的插件仍需要旧版会话文件时,Doctor 会在验证核心导入后保留这些原始文件。启动仅在其会话所有者具有匹配的已验证导入时才接受保留的文件。未使用的已配置代理不需要为另一个代理的历史创建空数据库。已更改、未分配或未导入的源行在启动前仍需要修复。

Deferred session import receipts bind the database inode and supported creation time, so a virtual filesystem device-number change after reboot does not invalidate a verified import. Retained source files keep their SHA-256 and size checks; normal SQLite edits and deletions remain authoritative. Doctor's import/recovery pass upgrades older device-and-inode receipts once in the existing receipt JSON. If the old physical identity no longer matches, Doctor verifies retained sources against canonical history before rebinding. A changed or incomplete database keeps its recovery warning and cannot replay retained sessions.

Doctor 在规划和会话后修复期间保留一个已准备好的插件选择。延迟的外部插件在已准入插件完成其修复期间保持延迟;更改维护范围不会添加计划外操作,也不会因操作顺序不匹配而阻止更新。当没有插件迁移被延迟且没有保留经验证的旧版会话源时,会话后插件修复会运行一次其检测器,并跳过完成认证流程。Gateway 启动时会报告待处理修复,但不会执行它们。

在归档保留的原始文件之前,Doctor 会针对当前发布事务重新检查待处理的插件迁移。如果这些义务在修复期间发生变化,原始文件仍受保护,Doctor 会报告该冲突以便后续修复。

当可用历史和会话元数据成功导入时,缺失的转录仍保持为警告,包括在插件迁移待处理期间。后续 Doctor 运行会保留当前 SQLite 编辑和删除,而不是重放保留的索引。缺失历史警告会在归档后继续保护该索引。如果先前缺失的转录出现,Doctor 会保留它,并在完成延迟迁移之前报告源冲突以供检查。

如果代理架构升级在数据库提交后被中断,请使用兼容的 OpenClaw 构建重新运行 `openclaw doctor --fix`。Doctor 会刷新每个成功验证的数据库的注册信息,包括活动状态目录内保留的已注册数据库,即使其代理不再被配置。

Doctor 会在释放维护之前完成其修复启动的数据库工作。未找到修复的检查会保持现有运行时句柄打开。如果失去维护所有权,Doctor 会停止其修复并清理自身资源,而不会关闭独立准入的运行时工作。

`openclaw doctor --fix`(包括 `openclaw update` 期间的修复流程)会移除历史任务运行 ID 和子会话键周围的空白。它在同一事务中修复相关的子代理任务绑定,同时保留任务 ID、物理子代理运行 ID 和交付记录。如果不同的运行 ID 会变成同一个 ID,Doctor 会保持事务不变并报告冲突的绑定。新的任务写入在持久化之前会规范化这些字段;Gateway 读取使用现有索引,而不会扫描以修复空白。直接替换二进制文件时,请在启动新 Gateway 之前针对相同状态运行 Doctor;官方容器镜像激活包括此修复流程。

在 Windows 上,独立的 `openclaw doctor --fix` 会合并同时使用普通路径和扩展长度路径(`\\?\` 或 `\\?\UNC\`)的内部数据库注册,并在状态相对行中保留最新记录的事实。外部数据库位置保持其现有拼写。在更新期间,包括候选 Doctor 流程,Doctor 会跳过此修复并发出警告,以便更新器捕获的回滚清单保持不变。更新完成后,重新运行独立的 Doctor 以修复现有别名。

Doctor 会报告各个通道迁移计划的失败,同时继续处理无关源的迁移计划,包括来自同一插件的计划。共享失败源的迁移计划会被延迟,源清理会等待其最后一个消费者在没有报告失败或不完整导入的情况下完成。建议性就绪警告允许 Gateway 以降级方式启动。启动时会记录一次警告,并附带确切的修复命令;`openclaw status` 和 `openclaw doctor` 会显示正在运行的 Gateway 的警告报告。针对相同状态/配置运行 `openclaw doctor --fix`,然后重启 Gateway。带有警告的迁移在后续 Doctor 运行之前仍保持未完成。读取不安全的状态仍会拒绝启动。

如果代理数据库属于另一个代理,Doctor 会在升级任一数据库之前检查是否存在错放的副本。只有字节完全相同的数据库文件,且其 sidecar 和归档依赖缺失或相同,才符合条件。Doctor 会在其维护租约下对它们进行检查点并重新检查,使用现有的 `.corrupt-<timestamp>` 恢复文件名保留错放的副本,并让受影响的代理使用全新数据库启动。警告会指明保留的路径。

分歧或未验证的副本保持原位。对于具有已验证所有权不匹配的配置的次要代理,Gateway 会启动并使该代理不可用,同时继续为健康代理提供服务。`openclaw agents list`、status 和 Doctor 会报告降级代理;针对它的回合会返回记录的拒绝原因。影响默认或系统代理的拒绝,或共享状态数据库,仍会阻止启动。

对于已检查数据并停止 OpenClaw 的操作员,Doctor 会报告嵌入的所有者和现有的显式隔离命令。独立状态迁移仍会运行;需要被拒绝数据库的修复会被跳过并报告为警告。准入从数据库文件派生,并且仅保存在运行中的进程中。在修复或显式隔离错放副本后,重启 Gateway 以重新评估准入。没有持久化的拒绝或单独的放行记录。

`delivery-queue/` 和 `session-delivery-queue/` 下的 JSON 交付文件最后一次写入于 2026 年 7 月 1 日之前。它们的导入已退役。Doctor 和启动过程会保持这些文件不变,并停止,同时提供指导:先通过 `2026.9.7` 升级并运行其 `openclaw doctor --fix`。在该中间升级之前,请备份完整状态目录,包括队列拥有的媒体。当前 SQLite 队列及其重试策略保持不变。

Doctor 还会准备 SQLite 中已退役的原始出站行,包括中断的准备和媒体暂存检查点。它仅在准备或发送对账需要时加载已配置的插件运行时,保留现有的修饰器顺序和取消策略,并在完成修复前释放该运行时。已准备的检查点会在不重新运行修饰器的情况下完成。缺失的插件或媒体会保留现有的保管与重试警告,留待下一次 doctor --fix 处理。常规 Gateway 启动会报告旧版 SQLite 行,但不会转换它们;它会继续为当前已准备队列执行恢复和重试。

如果插件清理报告存在保留的资源,Doctor 会保持其维护所有权并使修复失败。在重启 Gateway 之前,先解决该进程的清理失败;当这些资源可能仍在写入时,另一次调用无法接管其租约。已完全解决的回调错误仍然可见,但不会保留维护所有权。

现有的 .migrated JSON 文件和 .media.migrated 目录仍作为恢复工件保留。它们不是待处理消息,也不会被自动删除。在发送新消息之前,请检查保留的收件人、文本和附件;不要将已归档文件重命名回队列以请求重放。

当迁移将旧版文件夹保留为备份时,Doctor 会发出警告。WhatsApp 身份验证有意仅通过 openclaw doctor 迁移。Talk 提供方/提供方映射规范化按结构相等性进行比较,因此仅键顺序差异不再触发重复的无操作 doctor --fix 变更。

当显式名册不再包含 main 时,只有 openclaw doctor --fix 会迁移持久的 agent:main:* SQLite 行,并且仅当替换所有者明确无歧义时才会执行:即唯一的名册成员,或 agents.defaults.sessionStore.agentId 中配置的升级所有者。显式所有者同时适用于按代理和固定会话存储;固定存储的运行时所有权仍限定于该物理存储。Gateway 启动、嵌入式 TUI 启动、CLI 预检和首个代理引导只会检查保留的声明并报告 Doctor 提示;它们不会移动或删除行、恢复旧版转录代际,或写入旧版 main 迁移回执。

openclaw doctor --fix 首先导入任何旧版 JSON 会话存储,然后保留胜出的规范声明,并在其原始数据库中将落选的每个声明重命名为 agent:<owner>:legacy-main-conflict-<n>。隔离仅更改键;条目和完整转录仍可供检查或归档。

Doctor 还会从有界转录前缀中的首个用户请求修复缺失的历史会话标题。它保留显式名称和会话活动,跳过正在运行和隐身会话,并且不会恢复冷历史或调用模型。在规范会话键修复之后,它会规范化符合条件的旧版 ACP 元数据键,同时保留其存储的生命周期绑定。缺失、过期或冲突的 ACP 声明仍可供检查,并带有警告。Gateway 启动和普通读取不会执行这两种修复。

Doctor 会检测受管 worktree 会话上缺失的规范工作区元数据,并在会话键修复完成后对其进行修复。Gateway 启动不会扫描这些旧版工作区修复。当前模式打开、就绪验证、转录投影和实时运行恢复仍由其运行时所有者负责。

此迁移首先扫描会话键。如果任何候选存储中都不存在旧版别名,则不读取转录;否则,它只跨这些存储流式读取别名及其规范目标。跨存储复制在写入前会重新读取并验证源,源删除会在删除事务内再次验证它。这限制了 Doctor 期间的转录内存,包括 openclaw update 内部的 Doctor 处理。Gateway 启动将旧版迁移及其扫描留给 Doctor。

来自 2026.9.x 的独立 SDK 安装会继续使用操作系统主目录下非空的旧版 ~/.openclaw/agent/ 目录,直到 Doctor 记录一次已完成的迁移,即使规范目录已存在。该源会忽略 OPENCLAW_STATE_DIR 和 OPENCLAW_HOME,与随附 SDK 保持一致。Doctor 会将该源以及任何不同的 <state>/agent/ 负载合并到已配置的目标位置。在移动或隔离每个 SDK 旧版条目后,Doctor 会在目标位置写入 .legacy-agent-dir-migration.json,并将其绑定到已解析的源路径和目标路径。匹配的回执允许 SDK 在旧版文件重新出现时使用规范目录;Doctor 会报告并修复这些残留文件。缺失或不完整的回执会使 SDK 继续使用非空的旧版目录。Doctor 会保留无法识别的目标回执,并报告以供检查,而不是将其覆盖。Doctor 和独立 SDK 会从已加载配置中解析相同的安装目录,包括自定义 agentDir 或非 main 默认代理。SDK 目录读取会在检查配置之前使用显式的 OPENCLAW_AGENT_DIR。否则,缺失、不可读或无效的配置会产生一条警告,并使用默认目录决策,包括未迁移的旧版状态。检查永远不会重写配置、更改进程环境或运行迁移;Doctor 保留其独立的配置准入检查。显式的 OPENCLAW_AGENT_DIR 覆盖对两者仍然具有权威性:Doctor 永远不会清空所选目录,而是将其他旧版源合并到其中。当配置或迁移更改该目录时,受管工具查找会遵循此目录。复制状态规划会推迟绑定快照之外的 SDK 主目录负载;请在原始安装上运行 Doctor 以迁移这些文件。

在没有环境代理所有者或选定安装目录的情况下,搜索工具仍会使用 PATH 上的系统二进制文件,shell 命令会保留其现有 PATH。下载受管二进制文件需要选择所有者或设置 OPENCLAW_AGENT_DIR;SDK 会话保留其显式所有者要求。

SDK 会将所选目录与其记录的数据库所有者配对。当配置选择了另一个代理(例如 worker)时,旧版 main 存储仍会作为 main 打开。Doctor 会延迟该目录迁移,保留存储原样,并记录 outcome=deferred,原因为 owner-mismatch,以及记录的所有者、配置的所有者和源路径。警告会提示你继续使用现有存储;整个存储的所有权转移需要后续版本支持。对于延迟的源,不会写入完成标记,独立的修复会继续进行。即使所有者匹配,SQLite 目录迁移仍保持延迟。

Doctor 会递归合并旧版代理目录,包括现有的 `bin/` 目录。相同文件无需隔离;不同文件会保留当前目标位置,并将旧版副本保存在状态目录正下方的单个 `agent.legacy-<timestamp>-<id>` 目录中。即使 `agentDir` 位于外部或通过祖先符号链接访问,恢复副本也会保留在那里;Doctor 在移动前会解析文件系统路径。警告和修复报告会列出每个冲突,后续修复会继续进行。在没有新的冲突数据的情况下重复运行 Doctor,不会创建另一个隔离区。Doctor 会报告超过 30 天的隔离区,并附带清理提示,包括来自旧版按代理划分位置的产物;在手动删除不再需要的副本之前,请先检查它们。OpenClaw 不会自动删除这些恢复产物。

Doctor 会将每个 SQLite 数据库族保留在其原始位置,包括其 WAL、共享内存和回滚日志文件。即使目标位置为空,以及对于缺少数据库的不完整数据库族,也是如此。警告和修复回执会记录 `outcome=deferred`、原因 `sqlite-family`、源文件以及计划目标位置。请继续使用现有存储;安全的 SQLite 目录迁移需要后续版本支持。Doctor 不会写入完成标记,SDK 会继续使用旧版目录及其记录的所有者。

对于包含 SQLite 的源,Doctor 也会保留其他源文件,使已安装的工具和模型发现保持可用。它会将缺失的非数据库文件复制到目标位置,保留相同文件原样,并对不同文件发出警告,同时保留两个原始文件。对于这些延迟源,它不会创建冲突隔离区。独立的修复会继续进行。不包含 SQLite 的源仍使用上述递归移动和隔离行为。
3a. 旧版插件清单迁移

Doctor 会扫描所有已安装插件清单中的已弃用顶层能力键(speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders)。找到后,它会提供将它们移动到 contracts 对象中并就地重写清单文件的选项。此迁移是幂等的;如果 contracts 已有相同值,则会移除旧版键而不重复数据。

3b. 旧版 cron 存储迁移

Doctor 会修复 SQLite cron 行中受支持的历史形态,并导入受支持的 jobs-quarantine.json 伴随文件。已弃用的 jobs.json、jobs-state.json 和 runs/*.jsonl 文件需要先通过 2026.9.7 进行中间升级;Doctor 会保留这些文件,并在 cron 修复前停止。参见保留策略。

当前 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 投递;announce 任务保留其聊天投递并获得 delivery.completionDestination。随后 Doctor 会移除旧配置键。如果没有可用的旧版 webhook,则会为无目标任务移除无效的顶层 notify 标记(现有投递,包括 announce,会被保留),因为运行时投递从不读取它。

旧版默认代理所有权仅由 Doctor 修复。Gateway 启动会保持已存储的 cron 所有权不变。一个无所有者的任务,如果其配置仍保留旧版默认标记,会等待修复,而不会消耗其到期触发或禁用一次性任务。手动运行会返回 openclaw doctor --fix 指导;显式拥有所有者的任务会正常继续。Doctor 会在移除该标记前固定历史所有者,保留任务的定义和运行时状态。未解决的历史任务在更新或删除前也需要 Doctor,并且当前系统代理不会获得对它们的管理访问权限。操作员检查仍然可用。对于没有默认标记的旧版 agents.list,Doctor 会在转换名册之前将历史无所有者任务固定到列表中的第一个代理。当前带键的 agents.entries 配置如果没有旧版标记,则保留其动态系统代理选择。

缺失的 interval 锚点由 Doctor 修复。运行时调度可以计算下一次运行,而无需将锚点写入旧定义。计划维护和运行结果会保留已存储的所有权和作者字段;有意的启用/禁用转换仅更改 enabled 字段。

Gateway 还会在加载时清理格式错误的 cron 行,使有效任务继续运行。格式错误的行会在同一事务中被隔离到共享 SQLite 状态数据库,该事务同时将它们从活动调度中移除;doctor 会报告这些记录,并导入旧版本遗留的任何 jobs-quarantine.json 伴随文件。

Gateway 启动会规范化运行时投影,并忽略顶层 notify 标记,但会保留已持久化的 cron 状态以供 doctor 修复。Doctor 会移除没有迁移目标的任务的无效标记(delivery.mode 为 none/absent、不可用的旧版 webhook 目标,或现有 announce/chat 投递),并保持现有投递不变,因此重复运行 doctor --fix 不再对同一任务重复警告。

在 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 会扫描每个 agent 会话目录,查找由文件支持的会话异常退出后遗留的旧版写锁文件。对于找到的每个锁文件,它会报告:路径、PID、该 PID 是否仍然存活、锁的年龄,以及它是否被视为过期(PID 已死亡、所有者元数据格式错误、超过 30 分钟,或一个被证明属于非 OpenClaw 进程的存活 PID)。在 --fix / --repair 模式下,它会自动移除所有者为已死亡、孤立、已回收、格式错误且过期或非 OpenClaw 的锁。仍由存活的 OpenClaw 进程持有的旧锁会被报告但保留在原处,以免 doctor 中断正在活动的转录写入器。

3d. 会话转录分支修复

doctor 会扫描旧版 agent 会话 JSONL 文件,查找由 2026.4.24 提示转录重写 bug 创建的重复分支形状:一个被放弃的用户轮次,带有 OpenClaw 内部运行时上下文,外加一个包含相同可见用户提示的活跃兄弟节点。在 --fix / --repair 模式下,doctor 会修复该分支,同时将其历史暂存以便导入 SQLite。原始 JSONL 文件保持不变,并在成功导入后归档。

4. 状态完整性检查(会话持久性、路由和安全)

状态目录是操作中枢。如果它消失,除非你在其他地方有备份,否则你会丢失会话、凭据、日志和配置。

doctor 检查:

  • 状态目录缺失:警告可能发生灾难性状态丢失,提示重新创建目录,并提醒它无法恢复缺失的数据。
  • 状态目录权限:验证可写性;提供修复权限的选项(检测到所有者/组不匹配时,会发出 chown 提示)。 配置修复(包括更新期间)会保留由其他用户拥有的可写状态根目录(例如 Kubernetes fsGroup 卷,模式为 2775)。它们会将其路径、所有者 ID 和保留的模式作为警告报告。配置和备份文件仍要求模式 600;目录所有权加固和私有凭据目录检查仍会强制执行。
  • macOS 云同步状态目录:当状态解析到 iCloud Drive(~/Library/Mobile Documents/com~apple~CloudDocs/...)或 ~/Library/CloudStorage/... 下时发出警告,因为基于同步的路径可能导致更慢的 I/O 以及锁/同步竞争。
  • Windows 云同步状态目录:当状态解析到 OneDrive 同步根目录(来自 OneDrive、OneDriveConsumer 或 OneDriveCommercial)下时发出警告,因为基于同步的路径可能导致更慢的 I/O、锁/同步竞争以及 Files On-Demand 脱水。若要迁移,请停止 Gateway,移动整个状态目录,为 Gateway 服务设置 OPENCLAW_STATE_DIR(而不仅仅是一个 shell),然后重启并重新运行 doctor。
  • Linux SD 或 eMMC 状态目录:当状态解析到 mmcblk* 挂载源时发出警告,因为基于 SD/eMMC 的随机 I/O 在会话和凭据写入下可能更慢且磨损更快。
  • Linux 易失状态目录:当状态解析到 tmpfs 或 ramfs 时发出警告,因为会话、凭据、配置和 SQLite 状态(包括 WAL/journal 附属文件)会在重启后消失。Docker overlay 挂载有意不标记,因为其可写层在容器仍然存在时会跨主机重启持久化。
  • 会话目录权限:检查现有会话和存储目录的可写性。在新配置中,缺失的归档目录是健康的,并会在需要时创建。
  • 旧版转录不匹配:当最近的旧版会话条目缺少转录文件时发出警告。由 SQLite 拥有的会话不需要归档的 JSONL 文件。
  • 旧版主会话“1 行 JSONL”:当未导入的主转录只有一行时标记(历史未累积)。
  • 多个状态目录:当活动状态目录与有效主目录的默认 ~/.openclaw 目录不同,且该默认目录存在时发出警告(历史可能在多个安装之间分裂)。有效主目录遵循 OPENCLAW_HOME、HOME 和 USERPROFILE;doctor 不会枚举其他账户的主目录。
  • 远程模式提醒:如果 gateway.mode=remote,doctor 会提醒你在远程主机上运行它(状态位于那里)。
  • 配置文件权限:如果 ~/.openclaw/openclaw.json 对组/其他用户可读,则发出警告,并提供收紧到 600 的选项。
5. 模型认证健康(OAuth 过期)

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 还会报告由于短暂冷却(速率限制/超时/认证失败)或较长禁用(计费/信用失败)而暂时不可用的 auth 配置文件。

doctor 还会将旧版生成的提供商目录(plugins/*/catalog.json 和保留的迁移声明)导入 agent SQLite,同时保留提供商凭据。运行 openclaw doctor --fix 以导入这些目录,或修复无法推导传输 API 的已持久化生成模型。普通模型加载会读取规范 SQLite 目录,而不会导入附属文件或修复已保存的行。初始磁盘发现和显式注册表刷新会通过 doctor 命令报告旧版目录;热模型查找和生命周期捕获的目录不会检查旧版文件。新生成的目录在发布前仍会进行规范化。

OAuth 凭据 sidecar 导入已停用。Doctor 会保持 sidecar 的文件和加密密钥原封不动。当旧版 auth-profiles.json 仍引用某个 sidecar 时,Doctor 会拒绝迁移:请先升级到 2026.9.7,并在原主机的交互式终端中运行 openclaw doctor --fix,然后再重试;该版本可以恢复历史密钥并导入凭据。未被引用的 sidecar 会保留原样,不会造成阻塞。参见保留策略。

6. 钩子模型验证

如果设置了 hooks.gmail.model,Doctor 会对照目录和允许列表验证该模型引用,并在其无法解析或被禁止时发出警告。

7. 沙箱镜像修复

启用沙箱后,Doctor 会检查 Docker 镜像;如果当前镜像缺失,会提供构建或切换到旧版名称的选项。

7b. 插件安装清理

Doctor 会修复早于已记录来源权威的旧版官方 ClawHub 安装记录。使用 --fix 时,仅当原始规范和所有记录在案的包标识都与官方目录一致时,它才会回填现有的官方主机/渠道字段。本地来源、部分或冲突的权威信息以及无法验证的标识都需要重新安装,才能为受限运行时能力获得信任。具有一致官方规范的普通旧版 npm 记录已经满足信任要求。插件作用域状态和入站队列不需要受信任的来源。拒绝原因代码和补救措施请参见 插件运行时信任被拒绝。

当本地 Gateway 不可达时,Doctor 会比较 CLI 状态目录与已安装服务的有效环境。如果两者不同,它会打印两个路径;否则报告无法验证服务路径。无法读取或没有命令的服务定义,以及所引用的环境文件不可用,都属于未知状态,不能作为路径匹配的证据。Windows 批处理赋值中未解析的变量展开或不支持的转义同样保持未验证;在选择修复之前,请使用 openclaw gateway status --deep 检查其服务环境。请在 Gateway 的 OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_PATH 环境下运行检查和修复;仅配置文件与可执行文件版本一致并不能确定插件安装状态一致。

如果无法读取的本机定义同时阻止了安装或自更新,请遵循 本机服务恢复。重新构建启动器之前,请保留仅服务使用的环境变量值;配置和插件状态无需删除。

Doctor 会保留共享的插件运行时缓存和暂存目录,包括较旧的带版本号存储桶。其他安装或配置文件可能仍依赖它们;目录名称或标记并不能证明其未被使用。openclaw doctor --fix / openclaw doctor --repair 仅在全局插件运行时符号链接的目标不再存在时才删除它们,而不会仅仅因为指向较旧缓存就删除。

随 v2026.8.1 提供的 core/doctor/legacy-plugin-dependencies lint 选择器仍可作为已弃用的非破坏性信息检查使用。它不再扫描缓存根目录,也不再建议删除它们。使用 --severity-min info 可显示其弃用通知。

包级清理仍由包安装程序负责。Doctor 仍会删除捆绑的 @openclaw/* 插件中孤立或已恢复的受管 npm 副本,这些副本可能遮蔽当前的捆绑清单。它还会将宿主 openclaw 包重新链接到声明了 peerDependencies.openclaw 的受管 npm 插件中,从而使 openclaw/plugin-sdk/* 等包级运行时导入在更新或 npm 修复后仍能继续解析。

当配置引用了可下载插件但本地插件注册表无法找到它们时(具体的 plugins.entries、配置的渠道/提供商/搜索设置、配置的代理运行时),Doctor 也可以重新安装这些缺失的插件。在包更新期间,Doctor 会避免在核心包被替换时重新安装插件包;如果更新后某个已配置的插件仍需要恢复,请再次运行 openclaw doctor --fix。Gateway 启动和配置重新加载不会执行包修复;插件安装仍属于显式的 doctor/install/update 操作。

对于不完整的已记录安装,Doctor 的重新安装提示会保留已记录的包选择器,并优先使用解析出的版本而不是原始规范。例如:openclaw plugins install clawhub:demo@1.2.3 --force。如果这两个选择器均未被记录,Doctor 会解释为什么无法给出确切的重新安装命令,并保留通用修复指导。

Doctor 还会刷新绑定到当前 OpenClaw 发布群组的过期官方运行时插件。此修复使用记录注册表上声明的当前目标,并独立于旧安装验证该工件。已有的精确 npm 锁定版本将成为精确的替代版本;普通的缺失插件修复会保留已记录的目标和完整性。能力同意仍然适用。

容器化 Gateway 的启动遵循与其他安装相同的就绪边界。它会验证配置、接纳受支持的数据库、刷新当前插件元数据,并检查活动插件负载。官方镜像入口点会在默认或 Compose Gateway 命令之前,针对挂载的状态/配置运行 openclaw doctor --fix --non-interactive,因此常规镜像升级无需额外执行 Doctor 步骤。Gateway 启动本身不会导入旧版文件、修复插件包或链接,也不会记录已完成的旧版迁移。如果您覆盖了镜像入口点,请在启动 Gateway 之前,对同一挂载的状态/配置运行 Doctor。受支持的版本化数据库打开和本机初始化仍属于正常运行时操作的一部分。

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