SQLite 维护和会话迁移

显式 SQLite 维护在 Gateway 停止后离线运行。本页介绍共享状态压缩和针对性的会话 SQLite 模式。

在 Linux 上，已停止的 Gateway 服务仍可能在其 systemd cgroup 中留有子进程。Doctor 和更新维护在这些进程退出前将保持阻塞。请检查服务状态和日志，并让进程所有者停止其余子进程后再重试。即使 Gateway 本身以用户服务运行，root 拥有的子进程也可能需要管理员协助。

共享状态 SQLite 压缩¶

有关模式版本控制、完整性检查和降级恢复，请参阅数据库模式。

openclaw doctor --state-sqlite compact 是对位于 <state-dir>/state/openclaw.sqlite 的规范共享状态数据库执行的显式离线维护。它不接受任意数据库路径，不会在正常 Gateway 运行期间被调用，也不属于 openclaw doctor --fix 的一部分。该命令会获取与 Gateway 启动相同的状态所有权锁，并在验证、检查点、VACUUM 以及最终完整性检查期间持有该锁。当 Gateway 或其他 SQLite 维护命令持有该锁时，它会拒绝运行。即使 OPENCLAW_ALLOW_MULTI_GATEWAY=1 跳过了按配置的 Gateway 单例，状态锁仍然保持生效，因此操作员 shell 无需继承 Gateway 服务的环境，维护命令也能检测到该锁。

先停止 Gateway 并创建经过验证的备份：

openclaw gateway stop
openclaw backup create --verify
openclaw doctor --state-sqlite compact --json
openclaw gateway start

该命令：

1. 要求规范共享状态路径处存在常规文件。数据库缺失时报告为 skipped 并以成功状态退出。
2. 在执行检查点或更改文件之前，验证当前支持的模式版本以及 schema_meta.role = "global"。
3. 要求 wal_checkpoint(TRUNCATE) 不处于忙碌状态。如果检查点繁忙，请停止所有剩余的 OpenClaw 进程并重试。
4. 将 auto_vacuum 设置为 INCREMENTAL，运行完整的 VACUUM，然后再次执行检查点。
5. 运行 quick_check、integrity_check 和 foreign_key_check，然后重新对数据库和 SQLite 附属文件应用仅所有者权限。

JSON 输出报告压缩前后的数据库和 WAL 大小、空闲列表页、页大小以及 auto_vacuum 值，还有回收的字节数以及 quick_check 和 integrity_check 的结果。foreign_key_check 以失败关闭方式强制执行，没有单独的成功字段。SQLite 将 auto_vacuum 报告为 0（无）、1（完整）和 2（增量）。

当模式版本过旧、比当前运行的 OpenClaw 构建更新、或属于代理数据库时，压缩会在不做任何修改的情况下失败。对于较旧的共享状态模式，请先运行 openclaw doctor --fix。对于较新的模式，请恢复兼容的备份或升级 OpenClaw。

会话 SQLite 迁移¶

运行时会话行和转录数据存储在 SQLite 中，默认位于 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。Gateway 启动时会使用 Doctor 的独占维护所有权来迁移旧的会话 JSON/JSONL 文件，然后才检查就绪状态。运行时读取仅使用规范 SQLite 状态。不可读的旧会话索引会与其转录一起保留在原路径，因此重复启动会拒绝就绪，并打印活动配置文件的 doctor --fix 命令，直到源被修复。

要从较旧的基于文件的安装升级历史数据，请停止 Gateway（openclaw gateway stop）、备份其状态（openclaw backup create --verify），并在使用 openclaw gateway start 重新启动之前运行 openclaw doctor --fix。

Doctor 会在每个配置的 agents.entries.<id>.agentDir 处迁移现有数据库，包括默认代理树之外的自定义路径以及注册表中不存在的数据库。配置的会话存储和保留的旧数据库也会被检查。如果配置的数据库在 --fix 之后仍需要模式迁移，Doctor 会报告其路径并以非零状态退出，而不是打印 Doctor complete。

openclaw doctor --session-sqlite <mode> 提供针对性的检查、导入、验证和 SQLite 维护。旧的 sessions.json 文件是迁移来源。热转录 JSONL 文件在成功导入后被导入并归档；归档层的 JSONL 文件仍然是支持工件，而非运行时回退。

当插件迁移被延迟时，经过验证的导入收据也会捕获未被引用的 JSONL 输入。完成插件迁移后，这些原始文件将与索引转录数据一样，以相同的身份和字节校验被归档。转录数据的 .trajectory-path.json 指针会随其一起移动。如果先前的结算已归档转录数据但留下了经过收据验证的指针，则下一次 doctor --fix 也会归档该指针。捕获后创建的文件以及被修改的原始文件会在结算前分别进行验证。文件时代的会话路径修复会保留这些原始文件，直到其经过验证的导入收据完成归档，即使待处理的插件迁移记录已清除也是如此。重试和只读检查会复用经过验证的收据，包括在 sessions.json 之外发现的转录数据。Doctor 会为这些保留的输入报告一条待处理插件警告；它们不会使已完成的核心里迁移失败，也不需要 doctor --session-sqlite recover。仅含警告的结果以成功状态退出。不在该收据范围内的活动旧 JSONL 属于等待验证的建议事项。doctor --fix 和 --session-sqlite recover 会验证其事件身份和内容是否存在于所属代理的 SQLite 转录中。较长 SQLite 转录的前缀或子集被视为被取代，而非计数不匹配。Doctor 会归档原始文件，并在其现有迁移收据中记录 superseded by SQLite (N of M events present)，其中 N 是旧事件计数，M 是 SQLite 事件计数。缺失的后缀事件会在验证前经过现有导入器处理；当前会话设置及其活动代保持不变。原始字节保留在迁移归档中，以供恢复。已修改、格式错误或冲突且无法验证的源文件会保留在原处。冲突的身份或缺失的中间事件会在检查发现中被点名。请将这些事件与经过验证的备份进行比较，保留原始文件，并在重新运行恢复之前将修正后的 JSONL 恢复到指定路径。健康的代理不会继承另一个代理的失败。当旧索引和实时转录输入都已不存在时，经过验证的历史归档会保留其现有收据。它们不需要新的旧索引收据，也不会阻塞会话后的插件修复。插件的完成会释放其保留的配置。

如果原始 sessions.json 不可用，但已完成的导入回执仍标识了规范数据库，导入会从回执中记录的哈希重建其源索引。它会在现有回执中记录该修复，而不会重新创建 sessions.json 或重放会话元数据。哈希匹配的源会在导入过程中继续；已更改或无法验证的源保持受保护，并按路径列出。保留这些文件以供检查。

一个会话目录不需要旧版 sessions.json 即可恢复其历史。Doctor 从已验证的转录文件头和 SQLite 推导会话归属。对于具有待处理插件迁移的已配置 agent，它会在现有导入回执中记录源索引，而不创建新的 JSON 索引。对于未配置的 agent，它会导入有效对话，并将原始历史移动到受保护的迁移归档中，同时记录每次移动。仅轨迹目录也会保留在那里，而不创建空的 agent 数据库。其他 agent 的待处理迁移不会阻止此归档。

具有已记录 SHA-256 和大小的已恢复副本仍然有效，即使其 inode 或修改时间不同。--session-sqlite recover 会在现有回执中记录其当前标识，包括不存在失败迁移清单的情况。如果数据库文件已被替换，恢复会先将保留的转录内容与当前 SQLite 数据库进行验证，然后再重新绑定回执。Doctor 还会将仅格式变化的索引与记录的源哈希进行验证，并将已更改的转录与完整的规范历史进行验证。已验证的内容会刷新回执，而不会覆盖当前会话设置或恢复已删除的历史。已更改的索引值和其他无法验证的插件输入会移动到受保护的迁移归档中，并在报告中包含其验证错误和恢复路径。对于已更改的索引，Doctor 会将会话键和 ID 与规范 SQLite 进行比较，并在按会话的警告中列出不同的元数据字段。此比较不会授权重放旧值，也不会接受已更改的字节作为原始导入。快照、model-route 和完整性修复会保持这些历史输入不变，即使插件义务完成而其源回执仍然存在。规范 SQLite 修复继续进行。在无索引导入之后出现的新索引会被保留为冲突输入；它不能继承先前回执的权威性。

保留的插件源冲突不会阻止核心导入完成后的 Gateway 就绪。Doctor 负责修复，Gateway 继续提供 SQLite 服务。inspect 会报告实际的 SQLite 行数，即使保留的输入需要修复。恢复报告会包含所有剩余的问题代码，并区分未解决的发现与已完成的验证。

当已记录的旧版索引及其归档都缺失时，Doctor 会先将剩余转录与规范 SQLite 进行验证，然后报告规范转录完整且旧版索引条目仅供参考。它会保留这些活动转录和迁移记录，跳过另一次导入，并允许会话后插件修复继续。它不会持续要求为该已验证历史执行导入。

Doctor 还会发现从旧版注册表中遗漏的主要对话转录，包括带时间戳前缀的文件名。导入前，它会验证会话头、文件标识和逻辑所有者。已知的历史代次仍会附加到其现有会话，而不更改其当前代次或设置。没有注册表所有者的历史仅在其 agent 所有者明确无歧义时，才作为归档会话恢复。

重新运行导入可以恢复被先前迁移扫入受保护归档的主要历史。Doctor 使用保留的迁移清单和归档注册表谱系；它不会用陈旧设置覆盖活动 SQLite 状态。原始文件保持受保护，并记录已完成的恢复，以便后续运行不会恢复用户明确删除的历史。诊断轨迹信封、已删除的工件、不支持的文件、冲突标识和模糊所有权不会被转换为对话。延迟文件仍可用于恢复。

重复导入可能会留下一个主要转录的多个归档副本。Doctor 将同一原始路径、具有相同已验证大小和 SHA-256 的副本视为一个历史声明。它会保留一个已验证的原始文件，并通过现有恢复回执退役相同重复项，更新每个保留的清单。--session-sqlite recover 还会处理这些归档，即使最新失败运行未移动任何文件。字节不同的副本保持受保护，并在警告中列出；保留的历史冲突不会阻止 update 的会话后插件修复。在解决这些冲突时，请保留原始文件和迁移清单，然后重新运行 openclaw doctor --fix。

常规 Doctor 输出和 openclaw update status 每个会话存储最多显示五个 historical_transcript_deferred 示例。更大的组会包含总数和省略数量；其他警告类型仍可见。对于每个发现，请运行 openclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --json。此摘要不会退役恢复引用，也不会使缺失归档符合清理条件。请保留剩余的原始文件和迁移清单以供恢复。

已更改的归档注册表¶

historical_transcript_deferred 可能会报告归档会话注册表不再与其迁移回执匹配。回执通过设备、inode、修改时间、大小和 SHA-256 标识原始文件；它不是 agent 或安装 ID。历史归档发现、还原和恢复清理接受卷重新挂载后的设备号变化；inode、修改时间、大小和 SHA-256 仍必须匹配。复制、替换、touch 或编辑归档可能会使该回执失效。 2026.9.4 和 2026.9.5 中的标识格式相同；2026.9.5 添加了历史归档发现功能，用于检查这些旧回执。

Doctor 会跳过该存储的历史转录导入，并保留原始文件。 仅出现此警告并不表示 SQLite 损坏，也不要求回滚。 如果所有预期会话都可见，则无需处理。你可以使用 openclaw doctor --session-sqlite inspect --session-sqlite-all-agents 检查当前 SQLite 状态。

如果历史记录缺失，请保留指定归档以及 <state-dir>/session-sqlite-migration-runs/，创建经过验证的备份，并携带警告和检查输出寻求恢复帮助。请保持转录内容和原始清单私密。doctor --fix 不会重置未验证的指纹； 不要删除或编辑收据以消除警告。导入尝试会在其迁移清单中记录跳过的结果，并保持现有 SQLite 会话完整。

导入暂存与验证¶

公开的 Doctor 迁移路径会将转录负载暂存，并在私有的临时 SQLite 数据库中执行分支 和提供商修复，而不是在内存中保留完整历史。它会保持原始转录不变，直到通过独占的同文件系统移动将其归档，从而避免额外完整的 .pre-doctor 原始 副本和重写的中间文件。

对于大型历史，请同时为原始 JSON/JSONL 文件、临时 SQLite 暂存区以及目标数据库和 WAL 规划空间。在系统临时卷和承载 OpenClaw 状态的卷上都保留可用空间； 生成的 SQLite 数据库可能比原始 JSONL 更大。流式处理 可降低整个历史的内存压力，但单条记录仍会在内存中解析， 并且 SQLite 也会使用原生内存。不要仅根据 JSONL 字节数或 JavaScript 堆限制来配置主机规格；没有固定的磁盘、RAM 或 迁移时间保证。

操作完成后会删除暂存数据，并且暂存数据永远不会用作运行时 存储，也不会在中断后恢复；重试会使用原始来源和 已提交的会话数据。导入后，Doctor 会对已支持自动 VACUUM 的数据库执行检查点和增量 VACUUM，并在清理前后保留完整的完整性检查和外键检查。如果数据库已处于增量自动 VACUUM 模式、没有空闲页，并且没有需要检查点的 WAL，则导入完成阶段会验证一次 并保持其内容不变。没有自动 VACUUM 的数据库仍需要完整的 VACUUM 才能启用它。增量清理会释放未使用的页，但不会重新打包部分填充的页；显式的会话和共享状态 compact 模式仍会执行完整的 VACUUM。

常规 openclaw doctor 检查也会报告初始会话头从未持久化的规范 SQLite 转录。openclaw doctor --fix 会在一个事务中前置当前会话头并重建转录索引，同时保留现有事件 ID、父级链接、行时间戳和 会话列表最近性。无头的旧版或格式错误的转录仍会被拒绝，直到其所属迁移能够验证它们。

模式：

选择器：

• 默认：已配置的默认代理存储；SQLite 检查不需要旧版文件。
• --session-sqlite-agent <id>：一个已配置的代理，或者与 --session-sqlite-store 配对时预期的数据库所有者（否则假定 main）。
• --session-sqlite-all-agents：已配置的代理存储加上发现的代理存储。
• --session-sqlite-store <path>：一个显式的 .sqlite 数据库或旧版 sessions.json 路径。

dry-run、import 和 validate 仅选择现有旧版来源。显式 .sqlite 路径在这些模式下不会选择任何旧版目标；它永远不会被解析或归档为 JSON。对于 SQLite 目标，请使用 inspect、compact 或配合 recover 的损坏恢复。从迁移清单中恢复或还原已归档来源需要包含它的原始旧版选择器或代理存储发现。旧版 sessions.json 选择器路径仍受支持，并解析到其对应的 SQLite 存储以进行维护。

在 Gateway 停止且其状态已备份后，检查并导入旧版历史：

openclaw doctor --session-sqlite inspect --session-sqlite-all-agents
openclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --json
openclaw doctor --session-sqlite import --session-sqlite-all-agents
openclaw doctor --session-sqlite inspect --session-sqlite-all-agents --json

import 会在归档其旧版来源之前验证行和转录事件计数。成功导入后，validate 可能不会选择任何旧版目标；请使用 inspect 查看当前 SQLite 状态。在旧版来源仍然存在时，如果所选条目在 SQLite 中缺失、会话 ID 不同，或旧版转录事件缺失或与 SQLite 冲突，validate 会以非零状态退出。额外的 SQLite 事件不会导致验证失败。 使用 --session-sqlite-store <path> 时，请检查报告中是否包含预期的目标数量；不存在的旧版来源在 dry-run、import 或 validate 中不会选择任何目标。

SQLite 会先删除数据库内部的可回收页面；这不一定立即缩小数据库文件。删除或归档大型转录记录后，运行 openclaw doctor --session-sqlite compact --session-sqlite-all-agents 以对 WAL 文件执行检查点，运行 VACUUM，并报告数据库和 WAL 的大小变化。压缩要求目标为具有当前 agent schema 的常规文件、其持久化数据库所有者元数据，并且 doctor 进程中不存在打开的句柄。破坏性 import、compact、recover 和 restore 模式在整个操作期间持有与 Gateway 启动相同的状态所有权锁；inspect、dry-run 和 validate 保持只读，不获取该锁。请先停止 Gateway。破坏性模式会失败，而不是与实时写入或另一个维护命令竞争。破坏性 --session-sqlite-store 目标必须位于活动状态目录内；在维护另一个安装之前，将 OPENCLAW_STATE_DIR 设置为该 store 所属的状态目录。现有硬链接目标会被拒绝，因为另一个路径可能在锁定的状态目录之外共享同一数据库 inode。相同的所有权检查覆盖 SQLite WAL、共享内存和回滚日志附属文件。

每次 import 在将转录工件移动到归档之前，都会在 ~/.openclaw/session-sqlite-migration-runs/ 下写入一个 manifest。恢复引用保留在当前 sessions 目录中，包括带有旧机器绝对转录路径的备份。重试被中断的 import 会保持索引和先前归档的转录可恢复。如果显式 import 在工件移动后失败，请保持 Gateway 停止并运行恢复：

openclaw doctor --session-sqlite recover --github-issue

使用 --yes 授权在非交互式恢复期间创建 issue。如果没有它，重定向输入、--non-interactive 和 JSON 输出会跳过提示，并记录跳过 issue 创建的原因。

恢复会选择最新的失败迁移 manifest，仅恢复该 manifest 中归档的工件，验证受影响的目标，并在当前恢复问题仍存在时准备经过清理的 .failure.md 和 .failure.json 报告。报告包括记录的 run ID、失败时间戳（对于没有该字段的旧日志则为 not recorded）、目标，以及失败代码和错误。它们将当前恢复发现与记录的迁移和恢复证据分开。较早的失败和现有报告仍可用于诊断。一次当前问题为零的成功恢复不会准备或打开 GitHub issue，即使它归档了已被取代的 JSONL 文件。重复已完成的恢复是干净的无操作；被阻止或不可信的恢复工件仍需要检查。 JSON 报告保留合并的 issues 证据，并为检查过的目标添加 recoveryIssues。GitHub issue 正文避免包含转录内容、原始环境、机密和无限制配置。一旦 issue 或浏览器交接可能已发布报告，doctor 会保留该私有报告工件及其标记回执。当不存在失败的迁移 manifest 时，恢复会使用所选 SQLite 数据库完整文件集的临时副本来检查它们。SQLite 可以在 quick_check、integrity_check 和 foreign_key_check 运行之前，在该一次性副本中回滚有效的热日志，而原始取证文件在检查期间保持未动。恢复会在 schema 和所有者验证后尝试就地修复规范索引损坏。Schema、所有者和 I/O 错误，以及失败或拒绝的索引修复，会保留原始数据库并附带诊断信息。其他已确认的损坏或孤立附属文件会通过将发现的整个文件集重命名为一个 .corrupt-<timestamp> 后缀来保留 DB、WAL、SHM 和回滚日志文件。捕获到的重命名失败会在报告失败之前回滚已移动的文件，因此可恢复的文件集不会被静默拆分。恢复前请停止 Gateway；复制或重命名正在活动的 SQLite 文件集是不安全的，并且在不同操作系统上的行为不同。使用 --github-issue --yes 时，doctor 会使用 GitHub CLI 在 openclaw/openclaw 中创建 issue。如果 CLI 不可用或 GitHub 明确拒绝请求，当编码后的 URL 保持在安全请求大小限制内时，doctor 可以在浏览器中打开确切的清理后报告。没有确认时，doctor 会写入本地支持报告，并跳过 issue 创建，而不打印或打开预填 URL。模糊的提交会以失败关闭方式处理。后续的 doctor 运行会协调保留的标记，而不会发送另一个创建请求，因此它不会发布重复 issue。机器可读输出包括生成的支持 issue 状态，但不包括私有回执或预填 URL。

restore 仍然是较低层级的撤销操作。它使用 manifest 中的 sourcePath -> archivePath 记录，仅当原始路径缺失时才将归档工件移回，报告独立存在的原始文件冲突，并保留 SQLite 数据库原位。发布是排他的：验证期间创建的文件或符号链接不会被替换。restore 移动原始文件而不复制其内容，如果文件系统无法安全发布，则失败而不消耗归档。已记录的中断发布可以重试，包括使用旧 manifest 或在替换 SQLite 数据库被移除之后。如果 restore 重新创建缺失的 sessions 目录，重试会在消耗归档之前重复其父目录持久性检查。当多个 manifest 记录了相同的原始路径时，restore 会在移动任何候选项之前规划所有候选项。相同的归档是安全重复项，一个非空的旧版 sessions.json 可以取代由旧写入器创建的空副本。不同的非空索引、不同的转录归档、无效归档，以及没有记录先前 restore 的缺失归档会以失败关闭方式处理，因此 restore 不会静默替换或隐藏可恢复数据。

重新导入一个未更改的、清单中记录的已恢复索引会保留当前 SQLite 会话元数据，同时协调其转录历史。它不会将较新的标签、活动时间戳或当前会话指针重置为恢复值。已更改的恢复回执会拒绝导入，而不替换该状态。不可读的恢复历史仅当目标没有会话行时才允许导入；Doctor 会验证该条件，并在一个事务中导入目标。这可能使用比正常批量导入更大的事务。当恢复历史可读时，具有不同文件标识的新建索引仍为普通导入。将恢复清单与其原始文件保留在一起，以便 Doctor 能够区分两者。共享索引为每个 agent 的 SQLite 目标保留一个回执；仅凭其他所有者的回执不能为所选目标确立已恢复的来源。显式自定义存储保留其位于状态目录之外的现有恢复/导入准入；这不会使其文件符合自动恢复清理条件。

在验证迁移和当前历史后，使用 openclaw update cleanup --dry-run 检查保留的恢复数据，而无需停止 Gateway。仅在停止同一 profile/状态目录的 Gateway、其他 SQLite 维护和数据库读取器后，才使用 openclaw update cleanup 或 openclaw update cleanup --yes --json 应用。在清理退出前保持会话列表监视器停止：即使是只读连接也可能更改 WAL/SHM 辅助文件并使验证失效。这会永久退役符合条件的回滚原始文件；它不会删除当前 SQLite 历史或操作员备份。只要保留的或待处理工件需要它们，清单就会保留，因此中断的清理可以恢复。恢复会区分有意处置、待清理和意外缺失文件。参见 更新清理。

硬链接的旧版工件¶

当另一个硬链接引用其 inode 时，Doctor 会拒绝旧版 sessions.json 或转录工件。诊断会列出工件路径、设备、inode 和观察到的链接数（nlink）。Doctor 不会扫描其他链接路径。该拒绝可保护快照副本免受通过共享 inode 的更改。

对于在身份被记录用于归档之前被拒绝的旧版源，停止 Gateway 并创建经过验证的备份。将内容复制到同一目录中的新临时常规文件，并保留权限。验证副本具有相同的内容和链接数为 1，然后将其重命名覆盖报告的源路径，并重新运行相同的 Doctor 命令。不要就地覆盖源或创建另一个硬链接：用新副本替换其目录项可在无需查找其其他路径的情况下保留快照内容。

如果之前的迁移被中断，或报告的路径是已归档的恢复工件，请保留文件和清单。首先使用相同的 profile 和旧版源选择器运行 openclaw doctor --session-sqlite recover。已记录的工件依赖于其原始身份；用副本替换它们可能会阻止恢复。如果恢复仍然拒绝该工件，请保留该证据以供支持使用，而不是替换它。

会话 SQLite 迁移后降级¶

在启动旧版本之前，请遵循 降级。在写入器停止后，openclaw doctor --session-sqlite restore --session-sqlite-all-agents 将清单中记录的旧版转录工件恢复到其原始路径。这支持从保留的原始文件恢复；它不会逆转 SQLite 架构迁移或替换更新前备份。

在 openclaw update cleanup 退役这些原始文件之前运行恢复。清理后，恢复会报告有意处置，并且无法重新创建它们。共享状态发现使用私有只读快照，包括用于自定义存储，因此被拒绝的恢复不会更改共享数据库及其 WAL。仅在 SQLite 中创建的会话不会出现在旧的文件支持运行时中。如果再次升级，请使用上述正常的迁移验证序列，在导入前比较恢复的工件与 SQLite 行。