遗留状态迁移

openclaw doctor --fix 拥有持久文件到 SQLite 的迁移。本页描述了每个迁移源以及当迁移源被阻止时该怎么做。

旧会话导入中断后，针对同一状态目录重新运行 openclaw doctor --fix。 Doctor 将保留的转录本与导入者修复的表示进行比较，包括旧的提供者名称和重复的会话标头。已导入的事件成功，不会重复；可以附加经过验证的缺失后缀。匹配存储完成归档并保留原始字节。正版内容冲突保留受影响的商店及其原始内容； Doctor 显示阻塞结果并记录存档验证失败。

对于帐户发现中不再存在的指定频道帐户，Doctor 将其旧版 credentials/<channel>-<account>-allowFrom.json 文件移动到现有的 .migrated 存档路径（如果被占用，则进行编号），将这两个路径报告为警告，并继续后续迁移。原始字节仍然可用于恢复；它们不会分配给幸存帐户。已配置帐户的格式错误的允许列表和不明确的帐户身份仍需要修复，然后才能继续迁移。更新时医生使用相同的行为。

Matrix 的一次性入站重复数据删除扫描仅在配置了 Matrix 或旧的 Matrix 状态需要检查时适用。两者都没有的全新安装不需要 Matrix 迁移或专门的网关维护。完成的扫描会保留一份持久的收据，以便以后的医生运行不会重复扫描。

6 月之前的 iMessage 缓存、Active Memory 会话切换、Nostr 总线和配置文件状态以及 Microsoft Teams 对话、民意调查、SSO 令牌和反馈学习不再从 JSON 文件导入。如果这些源仍然存在，Doctor 会保留它们并引导您通过 2026.9.5](/install/updating#upgrading-very-old-versions) 进行 [upgrade 并首先运行其迁移。现有的 SQLite 状态仍然具有权威性。

7 月之前的 Telegram 机器人信息、贴纸、线程绑定、更新偏移、消息、发送消息和主题名称 JSON sidecar 不再进行检查或存档。医生保留他们的文件不变，包括空的线程绑定文件。如果您仍然需要它们的状态，请恢复完整的更新前备份并在 OpenClaw 2026.9.5 上运行 openclaw doctor --fix，然后再次更新。单独的 Telegram JSON 入口假脱机迁移仍会导入待处理的更新、处理声明和带有已验证备份的失败逻辑删除。

7 月之前的语音唤醒设置、更新检查状态、插件绑定批准、当前对话绑定、ACP 重播和重启哨兵 JSON 也已停用。 Doctor保留这些来源并中断ACP/restart导入声明，然后指导您通过2026.9.7升级并首先运行其Doctor。更新准入在激活前检查原始文件。当前的 SQLite 状态仍然受支持。

废弃的 subagents/runs.json 文件也会被忽略并且保持不变；瞬态运行永远不会从它们恢复。

7 月之前的插件安装索引 plugins/installs.json 不再导入或存档。医生保留它并以相同的中级升级指导停止。 7 月时代的 SQLite 插件安装记录仍然受支持。

沙盒容器和浏览器 JSON 注册表（包括其分片 JSON 目录）已在 7 月前的状态下停用。 Doctor报告保留的路径并拒绝--fix而不读取或更改其内容。通过 OpenClaw 2026.9.7 升级并在原主机上运行 openclaw doctor --fix，然后重试。当前的 SQLite 沙箱注册表仍然受支持。

需要退役的 room → groupChannel 转换的会话记录将被拒​​绝，而不更改其原始字节。保留状态，安装OpenClaw 2026.9.5，运行openclaw doctor --fix，然后再次升级。具有被忽略的 room 字段的当前 groupChannel 保持不变。

July Doctor 导入程序仍然可以编写 provider 和 lastProvider 别名。 Doctor 保留其修复，备份现有的 SQLite 行，并一起更新当前交付元数据及其查询投影。运行时读取需要修复；当前交付字段和不相关的存储值保留其值。

旧版状态迁移

除非您选择显式路径，否则运行时使用 ~/.openclaw/openclaw.json。对于仅使用 ~/.clawdbot 的默认布局安装，Doctor 会停止托管网关并清空数据库工作，然后将该目录重命名为 ~/.openclaw。当当前文件名不存在时，配置预检会将其中的 clawdbot.json 重命名为 openclaw.json。这些是相同文件系统的移动，而不是副本； .env 和其他状态字节保留在目录中。第二遍没有任何需要重新定位的地方。

如果两个目录都存在，Doctor 会对这两个目录进行命名并保留它们以供手动核对。它永远不会合并它们或留下遗留别名。显式 OPENCLAW_HOME、OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_PATH 选择器未更改。已退役的 JSON 插件安装索引会阻止重新定位，直到中间版本迁移它为止。

安装的更新程序运行相同的 Doctor 修复。发布的 2026.9.7 保留其原始回滚路径，因此以后失败的更新可以拒绝重定位后的自动回滚。它保留移动的状态和保留的快照；在重新启动或降级之前，请遵循其候选医生恢复指南。

openclaw doctor --fix 拥有一般持久性文件到 SQLite 的迁移。它验证并声明每个已识别的源，写入并验证当前格式的行，记录迁移收据，然后删除已停用的源。网关、节点主机和本地 CLI 启动将常规遗留修复留给 Doctor。正常版本数据库打开、本机初始化和有效当前配置的恢复仍然可用。

在启动网关之前，容器映像入口点会根据已安装的状态和配置自动运行 openclaw doctor --fix --non-interactive。如果您覆盖该入口点，请针对相同的安装显式运行 Doctor。 Doctor 在独家维护所有权下执行所需的遗留修复，并在架构升级之前保留经过验证的 SQLite 副本以及正常的配置备份和遗留文件存档。网关启动后会检查运行时准备情况。不安全的必需存储退出，代码为 78 及其具体原因。被拒绝的默认代理或系统代理永远不会产生健康的就绪响应。未使用的旧存储（包括没有代理所有者的松散 agent/settings.json 文件）保持不变并被推迟。 Doctor报告保留的来源并继续独立迁移；启动报告剩余的准备情况建议。公告绝不会隐藏单独的必需商店拒绝。

Doctor 还将旧的会话行挂起传递、模型回退和内存​​刷新字段转换为当前的结构化状态。已发布的 v2026.7.2-beta.5 将这些字段直接写入 schema-v16 会话行；稳定的 v2026.8.1 升级保留这些存储的值。即使当前编写器已经发出结构化状态，这种持久的升级路径也需要迁移。旧版 sessions.json 导入在写入 SQLite 之前应用相同的转换，保留准确的会话 ID 并存档原始 JSON 字节。这也在更新时 Doctor 期间运行，因此平面待交付字段不再通过重复请求运行 doctor --fix 来阻止导入。在重写现有数据库之前，它会保存并报告经过验证的 SQLite 备份，包括原始行值。待处理的回复文本、目标、意图 ID、时间戳和内存刷新计数保留其先前的含义；现有的当前值优先。过时的重试和错误详细信息保留在备份中。此修复仅更改那些状态字段。转录定位器、其他原始元数据、分割快照和格式错误的身份字段仍属于其现有的修复所有者；标量修复永远不会发明或证明身份。 SQLite 仅更改受影响的顶级 JSON 字段，保留不相关的不透明值，包括 JavaScript 无法准确表示的数字标记。 Doctor 使用现有快照和有界重写所有者。其捕获的文件标识也会到达正常的数据库准入所有者，后者在更改权限、日志模式、模式或行之前对其进行检查。 Doctor通过数据库所有者的内部修复许可提供这些事实；插件 SDK 选项保持不变。修复不能在备份后采用替换文件，也不能在其所有者退休后开始更改。普通会话读取需要进行此修复，而不是转换内存中的旧字段。 Doctor 预览报告受影响的行而不更改它们，并推迟进一步的会话检查，直到 doctor --fix 运行。更新时医生通行证在考生恢复会话之前执行相同的修复。迁移前奏会在重试延迟标量修复之前升级数据库模式。独立会话导入保留了旧模式的现有 doctor --fix 先决条件；会话恢复在检查和转换标量状态之前恢复或修复其选定的数据库。如果恢复的数据库仍需要架构升级，恢复会报告 doctor --fix 先决条件，而不是声明成功。修复失败会阻止医生，而不是成为可选的健康警告。如果后面的批次被中断，较早提交的批次仍存储在 SQLite 中，并且原始备份仍然可用；重新运行 Doctor 将修复剩余的行。

如果 Doctor 在代理模式或介质迁移期间中断，请停止使用该状态的其他 OpenClaw 进程并重新运行 openclaw doctor --fix。仅当其主机 PID 和进程启动身份证明进程已结束时，Doctor 才会收回记录的迁移所有者。未提交的数据库更改回滚；下一个阶段将恢复挂起的工作，同时保留迁移前的备份。没有进程标识的较旧租约在重试之前会保留其现有到期时间。

仅由先前拒绝阻止的步骤保留 refusal.code: "blocked-by-prior-refusal"，并包括 originatingRefusal 以及第一次拒绝的 stepId、原因 code 和人类可读的 message。在重试被阻止的步骤之前解决原始故障。这些字段带有 stepReceipts，包括 Doctor 拒绝错误；它们与 migration_runs 和 migration_sources 中的持久进口收据是分开的。较旧的执行收据可能会省略 originatingRefusal。如果被阻止的所有者可以独立验证其输入而无需写入，则已验证的输入错误将保留其自己的 step-refused 收据和警告。较早的故障仍附加为 originatingRefusal。 Doctor 将此应用于旧版 TUI 最后一个会话 JSON：即使较早的维护心跳退出，格式错误的输入也会保持明确。有效或不存在的输入仍会因之前的故障而被阻止。此诊断检查不会授权以后的迁移或写入。

doctor --fix 在其停止消息和运行状况警告中包含失败检查、拒绝代码和原因，使用与 openclaw update repair 相同的故障事实。它的有界摘要列出了在导数阻止步骤之前观察到的拒绝；完整的收据清单保留了完整的链。

Doctor 在预检期间导入已识别的旧工作区设置文件，然后其他迁移访问工作区状态。现有的 SQLite 设置记录获胜，包括 SQLite 中没有的里程碑。 Doctor 不会重播过时的里程碑。在删除经过验证的设置文件或中断的声明之前，Doctor 会在原始文件旁边保留其确切字节为 <source>.migrated.<sha256>.<unique-id>。 SQLite 迁移收据记录存档路径以及每个不同里程碑的一行 （legacy=... canonical=...），Doctor 也会打印该收据。由于没有 SQLite 设置记录，Doctor 会正常导入旧里程碑。成功的修复会删除运行时阻止程序；下一次运行没有要重复的工作区设置迁移。无效文件和工作区 identity/version 冲突仍处于阻止状态以供检查。

更新排练仅在其复制的状态目录中写入。演练不会复制工作区文件，因此遗留记录中保留的绝对路径仍然是只读清单。安装候选程序后，真​​正的Doctor会根据操作员的状态运行正常的导入和存档。

技能研讨会提案已被删除。 Doctor 将每个待处理或隔离的提案草稿及其支持文件导出到 <state-dir>/agents/<agentId>/agent/workshop-skills/.archive/.retired-proposals/<proposal-id>/，然后删除提案表。导出的草稿不是活技能；要保留一个，请要求代理将其保存为 /learn，以便它通过正常的验证、版本控制的 Workshop 写入。

Doctor 保留提案表和文件，并带有可恢复的警告，当没有配置的代理拥有提案时，它无法导出草稿，或者它发现无法安全撤消的半完成应用。这是故意的阻止，而不是失败的迁移，Doctor 仍然成功退出：按照警告进行操作。对于无主草稿，将其代理添加回配置中，或使用 /learn 保存整个提案目录（草稿和支持文件）并将其删除；然后重新运行 openclaw doctor --fix 以完成报废。在此之前，半成品申请的预申请内容位于 skill_workshop_proposal_rollbacks 表中。

声明文件处于复制状态之外的插件迁移将被推迟为一项插件操作。医生保留他们的档案和待处理标记完好无损，并报告延期；配置修复仍在运行。 Reef 的旧目录遵循此规则，包括其存档文件。

有意保留其文件的已完成代理删除将在更新和迁移发现期间被阻止。 Doctor 记录可恢复警告，命名代理、数据库路径和 openclaw doctor --fix 指导。这些商店不会阻止活跃代理的迁移或更新排练。如果共享身份验证源被保留，则其迁移记录跳过并且依赖身份验证修复等待；不相关的医生维修仍在继续。在迁移其保留存储之前恢复目标代理。待定文件删除会保留删除所有者的现有安全检查。

当删除历史记录丢失时，Doctor 会报告阻止修复的未经验证的存储数量。普通会话创建和数据库租用记录未知删除历史并继续；丢失行或重建收据不会导致代理被删除或无法使用。运行时不会在现有状态上重新创建空日志。即使共享数据库及其注册表消失，幸存的 quarantine/integrity 数据库也是先前状态的证据。在没有代理路径的情况下重新打开共享状态会保留未知的删除历史记录；保留的外部商店仍需要Doctor重建后才能维护。经过验证的新 SQLite 设置可以正常初始化日志，而不会出现丢失历史记录警告。旧版 JSON 会话文件本身不需要日志重建。代理目录发现从代理路径所有者中选择 openclaw-agent.sqlite 和保留的 incognito-openclaw-agent.sqlite 名称；自定义数据库名称需要配置的存储、注册表项或记录的删除路径。隐身运行时状态保留在内存中。保留路径上的现有文件是一种冲突，恢复必须清点和保护，而不是替换或静默激活为内存存储。正常的隐身访问仍然需要在重试之前移动或重命名该文件。同级重新索引锁、捕获和 SQLite sidecar 不是单独的代理存储。当前布局的数据库边车仍然保留主数据库丢失的证据。以前记录的协调文件保留仍保留在恢复收据中，但不会产生保留代理警告。升级后旧版重建索引锁定文件仍可保留；当前重新索引协调正在进行中，并且锁定文件的存在并不意味着代理已被删除。当删除历史记录不可用时，会话 SQLite 导入和恢复会保留现有代理数据库及其 sidecar，从而保留旧源而无需导入或存档它们。记录的删除和重建保留以及保留的带有导入收据的插件输入仍然受到保护。不可读的历史记录不会删除可读的删除标识或记录的保留。 openclaw doctor --fix 重建丢失的日志并隔离不可用的日志记录。在删除不可用的记录之前，它会保存其原始行，包括格式错误的 JSON 以及 <state-dir>/agents/<id>/recovery/deletion-journal-<unique-id>.json 下的保留存储库存。丢失的历史记录会在同一恢复目录中获取库存收据。 Doctor 将维护保留记录在现有迁移表中。它将有效的正在进行的删除留给其生命周期所有者。对于常规代理，隔离会保留安全删除墓碑，直到显式恢复为止；它绝不会仅通过归档格式错误的清理详细信息来复活已删除的代理。恢复保留持有的库存；它不会迁移或退休它们。运行时入场与医生的维修保持是分开的。检查路径并使用 Doctor 打印的非交互式 openclaw agents add 命令来恢复预期的代理，或使用 openclaw agents delete 来确认删除。删除之前必须恢复未配置的代理。对于自定义数据库文件名，请先恢复原来的session.store配置； agents add 在无法选择保留存储时拒绝创建空替换。 Doctor使用常规代理的ID打印准确的恢复和删除命令，例如main。预留的系统代理openclaw和crestodian不能添加或删除；任一删除记录均无效并被隔离。 Doctor 保留其存储和任何持有的内部 SQLite 协调工件，而不推荐不可能的 agents add 命令。请勿将保留的系统代理数据库分配给不同的代理 ID。

这些保留是可见的警告，而不是拒绝更新：保留存储不会使其数据面临风险。如果 Doctor 无法验证自定义商店的所有者，则会导致日志不可用并报告路径。解决库存或所有权问题，然后重新运行 openclaw doctor --fix。

无效的配置也会导致日志不可用：Doctor 无法记录完整的恢复清单，直到它可以验证配置的所有权路径。修复配置，然后重新运行 openclaw doctor --fix 以在重建之前发现并保留外部存储。

2026.7.35 编写的完整历史共享模式早于删除日志。 Doctor 会识别该模式并在共享模式迁移期间初始化日志，然后在同一过程中迁移代理数据库。这不适用于缺少日志的现代数据库或记录的恢复保留。未经验证的删除历史存储仍保留，同时继续进行不相关的修复和更新。单独的完整性、模式和所需状态拒绝保留其现有的数据保存检查。

医生报告说，即使没有新的迁移剩余或您拒绝另一次迁移，身份验证配置文件存档恢复也会中断。如果恢复无法完成，其警告将包含失败原因并留下待恢复的源；不要删除它来消除警告。

仅当其旧收据没有凭证指纹、当前存储中没有任何迁移凭证保留且保留的存档仍与记录的源哈希匹配时，doctor --fix 还会修复不一致的已完成身份验证迁移。 Doctor通过正常验证的迁移流程重新导入。已完成的带有指纹的收据、幸存的迁移凭据或没有任何存档保持不变，因此在经过验证的迁移后删除凭据不会从备份中恢复它们。

Doctor 还废弃了带有空 defaults 和 agents 的无策略 exec-approvals.json 存根，包括没有版本的存根和仅包含套接字元数据的存根。它将确切的字节存档为 exec-approvals.json.migrated.<sha256>.<unique-id>，记录停用，并使现有的 SQLite 策略保持不变。当 SQLite 没有批准行时，Doctor 会导入任何非空套接字路径或令牌，以便正在运行的 exec 主机保留其凭据。中断的 .doctor-importing 存根使用相同的修复路径。未知字段、不受支持的版本以及非空或格式错误的策略不会被视为空存根。

对于格式错误的旧版 exec-approvals.json，Doctor 会保留原始字节并报告第一个验证问题，例如 agents entry #2.allowlist[1].lastUsedAt: expected a finite number。代理条目按 JavaScript Object.keys 顺序从 1 开始编号；允许列表索引从 0 开始。这可能与 JSON 文本顺序不同，特别是对于数字键。要在本地查找条目 #2，请使用 Object.keys(JSON.parse(raw).agents)[1]，其中 raw 是文件内容。诊断忽略代理密钥和策略值，并且迁移收据不包含诊断详细信息。 JSON 语法和无效的 UTF-8 收到不同的原因。

在本地修复保留的文件，然后使用相同的 OPENCLAW_STATE_DIR 设置重新运行 openclaw doctor --fix（如果之前未设置，则保持未设置）。在迁移成功之前，Exec 批准将一直处于阻止状态。在重新启动因该修复而停止的任何网关之前，显式修复退出非零，而遗留文件或中断的 .doctor-importing 声明仍然存在。请勿删除该文件或扩大其策略以绕过验证。

代理数据库模式升级与数据库路径以及观察到的前后版本一起报告，与介质重写无关。仅当重写记录会话或轨迹行并包含这两个计数时，才会出现媒体持久性消息。执行这两项操作的运行会报告两者；未更改的重播则不会报告任何情况。

Doctor 在执行 media/schema 迁移步骤之前解析已配置的代理数据库和自定义会话存储。该先决条件在身份验证配置文件导入、会话修复和会话后插件修复之前运行，包括在预检检查尚未注册的自定义存储时。

介质修复检测在第一个需要修复的事件处停止。修复事务在提交之前仍然验证每个转录本和轨迹行；稍后在任一存储中无效的 JSON 都会回滚介质更改。没有介质修复的数据库仍然会收到完整的验证扫描，包括在导入或恢复之后。

如果在介质修复事务开始之前另一个连接提交，Doctor 将使用 source changed before migration transaction 拒绝该修复。停止使用该数据库的其他 OpenClaw 进程并重新运行 openclaw doctor --fix。

所存储的 SQLite 转录档案的丢失文件副本会产生可恢复的警告，其中包含总数以及每个数据库最多五个示例路径。媒体和历史记录迁移仍然完成，保留存储的 SQLite blob，并保留已删除的副本。这些警告不会阻止剩余的迁移步骤或数据库准备工作。

媒体和历史指令存档检查和修复一次解码一个 JSONL 记录，因此大型 zstd 存档不需要适合一个 JavaScript 字符串。未更改的档案保留其确切的编码字节。更改的档案保留其原始编解码器；内存仍然包括存储的 blob、最大的记录和编码的替换。解码或压缩过程中的取消会留下未提交的 blob 和光标进度以供重试。

SQLite 存档修复在修复文件副本之前以有限批次提交更改的 blob。在验证该批次后，发布元数据和历史迁移游标一起提交。通过完整的存档密钥进行枚举，包括空的历史会话 ID。失败的批次报告其存档会话和生成并停止；重新运行 Doctor 在提交的游标之后恢复。在文件或游标失败之前已提交的 Blob 仍保留并等待发布。 SIGINT 和 SIGTERM 通过 Doctor 现有的维护所有者取消进一步的检查和维修批次，解决未完成的工作并尝试恢复其停止的托管网关。医生报告恢复失败和下一步恢复行动。更新使用相同的迁移并保留其现有的备份和回滚所有权。

Doctor 在更新防护和准入检查中共享其初始队列架构和所有权检查。数据库读取器使用有界工作池，包括封闭的 WAL 数据库的私有快照，因此大型队列不会在每次检查时为每个代理启动新进程。修复仍会在报告完成之前验证结果模式；只有成功恢复丢失的副本才能清除该副本的所有权拒绝。

设备对的旧版 JSON 导入会在写入之前检查命名空间容量。如果缺少的条目不适合，医生会发出警告并保持来源不变。在报告完成和归档源之前，导入还会验证源密钥和预先存在的目标密钥是否保留在 SQLite 中。保留警告使源可供检查和重试；不要删除它来消除警告，因为它可能包含 SQLite 未保留的状态。重新运行 openclaw doctor --fix 之前解决容量问题。

Microsoft Teams 委托的 OAuth 代币仍然从支持 6 月版本的 msteams-delegated.json 迁移。 Doctor 在归档源之前验证导入的凭据，并保留不同的现有 SQLite 令牌。

Doctor 还会报告共享身份验证何时仍使用旧版 agents/main/agent/openclaw-agent.sqlite 所有者。 openclaw doctor --fix 将其身份验证配置文件和运行时状态行复制到 state/openclaw.sqlite，验证确切的有效负载，删除源行，并仅在事务成功后记录新的所有权。身份验证解析没有双读回退：在迁移之前遗留数据库已完成；迁移后，共享状态数据库完成。搬迁后，删除 main 不再面临车队凭证的风险。

如果共享目标已包含具有相同凭证内容的每个旧配置文件，Doctor 会保留更丰富的目标并完成清理，包括空的旧配置文件集或较旧的行时间戳。凭证比较忽略 JSON 对象键顺序，但保留每个字段；它不按时间戳选择凭据。不同的凭据、仅源配置文件、格式​​错误的子集有效负载或不同的运行时状态行仍然存在冲突。医生姓名与配置文件 ID 冲突，以及他们的凭据是否不同、格式错误或在目标中缺失。存储元数据和运行时状态冲突单独报告；凭证值和任意元数据永远不会被打印。

停止 OpenClaw 进程并备份警告中指定的两个数据库，然后再在本地进行协调。对于每个不同的配置文件，选择要保留的凭据并使其完整条目在两个商店中一致；将仅源配置文件复制到目标中，而不替换不相关的配置文件。解决命名记录中格式错误的有效负载或不同的存储元数据和运行时状态，然后重新运行 openclaw doctor --fix。不要删除数据库或迁移收据来平息冲突。待重定位收据通过中断清理保留原始源摘要。重定位完成后，没有挂起的重定位收据的主代理行仍然是普通的每代理覆盖。

对于已停用的 QMD 内存后端，包括配置重写和派生工作区清理，请参阅从 QMD](/concepts/memory-builtin#migrating-from-qmd) 迁移 [。

这包括 <state-dir>/mcp-oauth/*.json 下已停用的 MCP OAuth 文件。修复前停止网关。 Doctor 将有效凭据导入到 <state-dir>/state/openclaw.sqlite 中，在两个存储都存在时保留现有的 SQLite 会话，删除过时的持久 OAuth state 值，并使用其收据来防止重新创建的过时文件恢复已注销的凭据。退役的 .lock sidecar 会阻止导入：如果 Doctor 报告所有者过时，请验证是否没有较旧的 OpenClaw 进程正在运行，删除该 sidecar，然后重新运行 Doctor。

显式修复（--fix、--repair 或 --yes）后，Doctor 在报告完成之前验证现有配置、默认布局和注册数据库的运行时架构准备情况，包括在注册之前迁移失败的存储。被阻止的所需迁移退出非零；停止网关和其他 OpenClaw 进程，然后重新运行修复。不相关的建议性警告（包括存档副本修复失败）不会使就绪数据库无法通过此检查。准备情况检查不会创建丢失的数据库。

Doctor 还在每个解析的代理工作区、活动沙箱工作区和显式配置的 agents.defaults.workspace 根中发现已停用的设置状态和中断的迁移声明。即使显式多代理名册仅使用其子目录，也会包含该共享根目录。 Doctor通过现有迁移导入<workspace>/openclaw-workspace-state.json；它不会将根分配给代理或移动角色和内存文件。

Doctor 不再扫描、导入或删除旧的 <workspace>/.openclaw/workspace-state.json 布局。它的文件保持不变。通过 OpenClaw 2026.9.7 升级并在更新之前运行 openclaw doctor --fix 以迁移该布局。请参阅 迁移保留策略。

修复退出非零，同时保留的遗留状态仍然阻止代理轮流，即使其数据已经达到 SQLite。网关启动和实时配置候选者仅检查他们将使用的工作区的准备情况，而不是未使用的默认根目录。未准备好的实时候选者将被拒绝，最后的好运行时保持活动状态。停止 OpenClaw 进程，如果实时写入在持久化之前被拒绝，则保存预期的工作空间路径，并将保留的文件保留在适当的位置。重新启动之前运行 openclaw doctor --fix。准备情况检查永远不会导入或删除遗留状态。

待处理的插件迁移

当 Doctor 在更新或修复中运行时，请先完成该命令，然后再遵循中间插件警告的恢复建议。更新程序可能会完成包收敛并在退出之前再次运行 Doctor。

一旦安装的插件的元数据确认它没有要运行的状态迁移或检查，包括当其通道被禁用或不再具有配置条目时，Doctor 就可以完成仅安装的延迟。这会保留插件的激活设置和保存的配置。当可用包没有插件迁移合同时，旧的仅检查义务也会解决。医生使用插件 ID 和版本发出警告，并在收据中记录原因；它不声明迁移运行或更改保存的数据。仍需要检查的显式状态迁移义务和包仍然需要由插件完成。

如果已安装的插件仍未报告迁移完成，请运行 openclaw doctor --fix。如果无法完成迁移，请将剩余的警告报告给插件维护者。单独重复包更新并不能证明插件迁移了其保留状态。保留保留的状态和配置输入，直到迁移所有者报告完成为止。

插件迁移恢复覆盖率

预修复状态保留在 manifest.json 路径的消息确认 Doctor 保存了恢复副本。它仅供参考：保留该副本以供手动恢复；不需要仅仅因为副本存在而进行修复。

插件的迁移恢复覆盖范围未知的警告意味着该插件尚未声明其额外的恢复资源。这并不意味着数据丢失或插件的共享 SQLite 记录被排除。此警告可能会重新出现在每个新的恢复清单上，直到插件提供声明。删除旧的恢复副本并不能修复该问题。

将插件更新到支持迁移备份的版本。在此之前，在依赖恢复之前对其配置的数据进行单独的备份，并要求其维护者添加备份支持。插件作者应通过collectBackupResources声明外部文件和数据库；显式空列表适用于仅更改核心捕获状态或没有数据资源的迁移。请参阅插件迁移合同。

捆绑的 Canvas 和 Memory Core 迁移声明了它们的旧数据源。 Crabbox共享的SQLite记录是核心捕获的；已停用的工作板检查使其遗留行保持不变。 QMD 停用仅删除空目录和一次性陈旧协调锁，因此它没有要保留的其他数据。这些声明可以防止误导性的丢失库存警告，而不会隐藏有关迁移失败或未解决状态的警告。

当安装的 Doctor 或更新程序创建新的恢复副本时，声明适用。它们不会将资源添加到已由较旧安装的更新程序创建的原始捕获中。保留这些保留的副本，并且不要假设较旧的捕获包含新声明的外部资源。恢复副本是手动恢复的证据；它的存在本身并不能保证自动回滚。