数据库布局
一些高频或特定生命周期的功能使用专用的 SQLite 存储,包括任务注册表和轨迹数据。
版本控制契约
每个数据库都在两个地方记录其模式:PRAGMA user_version是 SQLite 的模式版本。- 主
schema_meta行记录role、agent_id、schema_version和app_version。app_version是最后一次写入模式元数据的 OpenClaw 构建版本。
user_version 新于当前运行构建版本的数据库,并报告 newer schema version 错误。Gateway 会在启动前检查所有已注册的数据库。openclaw update 也会拒绝其声明的模式支持版本早于磁盘上数据库的包或源目标。对于在添加模式元数据之前发布的目标包,无法进行预检。
只有在降级后的读取器仍然安全时,变更才可以保持在相同的模式版本。新增表符合此条件,因为较旧的构建会忽略它们。现有表中明确兼容的列也符合此条件,但仅限于其声明严格为一个不带修饰的、可为空的 SQLite STRICT 数据类型:ANY、BLOB、INT、INTEGER、REAL 或 TEXT。该声明不能包含默认值、NOT NULL、主键或唯一键、检查约束、引用、排序规则、生成表达式或其他后缀。对现有表的带约束新增内容必须提升模式版本,或改用配套表。
匹配的数字版本是必要条件,但并不充分。版本可以在不推进 user_version 的情况下添加延迟创建或启动时可修复的表、列、索引或触发器,因此两个处于相同版本的数据库仍可能具有不同的结构。OpenClaw 会验证当前发布版本所拥有的规范表定义、约束、索引、触发器、虚拟表和表选项。
通过 npm 手动安装 OpenClaw 会绕过更新器防护。数据库打开检查仍会拒绝不兼容的构建版本。
预检目标版本
在激活或回滚版本之前,针对一个明确复制的状态数据库,运行目标版本的 CLI:exact:复制的数据库与目标版本的运行时架构匹配。那些在首次使用前有意缺失的功能本地表不需要修复。startup-repairable:数值版本匹配,但仍存在由运行时负责的增量差异;启动时需要写入以使结构趋于一致。migration-required:数据库版本低于目标版本。incompatible:数据库版本较新,或同版本结构存在阻塞性偏差,例如出现意外列。indeterminate:无法验证文件、完整性元数据或所有权元数据。
schema: "openclaw.state-schema-preflight.v1" 进行标识。
使用 SQLite 在线备份,或在源数据库得到安全协调期间生成的其他支持 WAL 的快照。生成的预检输入必须是一个不带同级 -wal、-shm 或 -journal 文件的整合文件;旁路文件会使结果变为 indeterminate。不要从活动中的 WAL 数据库仅复制主 .sqlite 文件。请对将要激活的确切运行时进行预检;仅凭软件包版本或数值架构版本,无法证明同版本结构兼容性。
Agent 架构历史
版本 3 是一个未发布的开发步骤,已并入版本 4。
状态 schema 历史
完整性检查
Gateway 启动前置检查仅读取模式标头。
openclaw database preflight 会对指定的复制文件执行发布版本本地的结构比较。后台验证器负责对无需迁移的实时数据库定期执行较慢的完整扫描。
隔离决策仅保存在专用的 openclaw-quarantine.sqlite 存储中,因此即使被隔离的数据库受损,这些决策也能保留。验证结果会被记录。
故障排除
为什么更新到 2026.7.2 后无法回退
直到v2026.7.1 的每个版本都使用 agent schema 1 和 state schema 1。2026.7.2 发布线(从 v2026.7.2-beta.1 开始)会在首次启动时将你的数据库向前迁移。该迁移是单向的:数据会被重写到更新后的 schema 中,而之后安装较旧版本的 OpenClaw 并不会撤销这一点。较旧的构建会拒绝启动,并报出 newer schema version 错误,其中会指出拥有该数据库的构建。
降级二进制文件永远不会降级数据。如果在更新后必须运行早于 2026.7.2 的版本,你有三个选择:
- 恢复更新前创建的备份。在重大更新前创建并验证备份。
- 使用单独的状态目录(
OPENCLAW_STATE_DIR)运行旧版本构建。它会从空白状态开始;你已迁移的数据会保持不变,等你切回较新版本时再使用。 - 按照下面的手动降级流程操作。这不受支持,并且如果没有经过验证的备份,存在数据丢失风险。
openclaw update 会拒绝安装无法打开你当前数据库的版本,因此更新器不会让你陷入这种情况。通过 npm 手动安装旧版本会绕过该保护;数据库仍然会拒绝旧二进制文件,但那时它已经被安装好了。
Gateway 因为 newer schema version 错误而拒绝启动
一个更新的 OpenClaw 构建写入了你的数据库,而当前运行的构建更旧。错误会指出拒绝启动的安装信息——发布版本、commit 和安装根目录——以及它支持的 schema 和实际发现的 schema。 请针对安装根目录进行处理,而不是版本。一个发布版本字符串可能对应许多main 提交、schema 级别和同版本的 schema 形态,因此两个安装都可以自称为 2026.7.2,但仍然无法对同一个数据库达成一致。预发布版本可能根本不存在于 latest npm 标签中:重新安装前请检查 npm view openclaw dist-tags,因为携带你所需 schema 的标签可能是 beta,而从 latest 重新安装可能会让情况进一步偏离。
如果安装目录是一个检出仓库,链接的源码检出是 commit 会误导的情况:openclaw --version 显示的是检出仓库的 git HEAD,但实际执行的代码是 dist/ 上次构建出来的内容。如果安装根目录是一个检出仓库,请先重新构建它(pnpm build),再判断版本是否有误。
使用支持其 schema 的构建打开数据库,或者让旧版本构建指向单独的 OPENCLAW_STATE_DIR。不要通过编辑数据库来消除该错误。
数据库在完整性验证失败后被隔离
后台验证器证明该文件已损坏,因此之后每次打开都会快速失败,而不会重新扫描。请从备份中恢复数据库,或者修复它,然后运行openclaw doctor --fix 以清除隔离记录。如果隔离记录本身无法清除,doctor 会报告明确错误;请反复运行,直到它报告正常。