数据库模式

OpenClaw 将控制平面状态存储在共享状态数据库中，并将每个 Agent 的数据存储在每个 Agent 单独的 SQLite 数据库中。数据库打开时，Schema 迁移会向前执行。较旧的 OpenClaw 构建会拒绝由较新 Schema 写入的数据库。

Schema 版本、完整性、规范索引和表存在性检查属于打开/准入阶段，并在迁移后由迁移所有者负责；运行时路径必须通过句柄携带已准入的 Schema 事实，绝不能重新查询这些事实，并在下一次未固定读取时使用最新的 PRAGMA data_version 探测来观察外部提交，同时保留活动的 SQLite 快照。现有的逐调用检查属于遗留实现，在改动时必须迁移。

Gateway 不会在启动后或按每日定时器调度全数据库完整性扫描。对于操作员请求或计划安排的完整验证，请使用 Doctor 维护。准入请求的后台 quick_check 工作仍仅限于被请求的 Agent 数据库。

该契约由两种机制支撑。CI 运行 scripts/check-native-state-schema-version.mjs，当 Swift 与 TypeScript 状态数据库契约声明不同的 Schema 版本时，该脚本会使构建失败。openclaw doctor --fix 负责文件到 SQLite 的迁移，并在共享的 migration_runs 和 migration_sources 表中为每次迁移记录一条回执。

执行步骤回执与这些持久化的导入回执是分开的。被先前拒绝阻止的步骤会包含可选的 originatingRefusal 字段 stepId、code 和 message，用于指明首次失败。如何解决请参阅遗留状态迁移。

本页是一个索引。参考资料按聚焦页面记录，每个读者任务对应一个页面。打开与你任务匹配的页面并停留在该页。

页面	何时阅读
数据库布局	数据库的两种角色、它们在磁盘上的路径，以及各个功能背后的表。
版本化契约	Schema 版本如何记录、何时需要提升版本，以及更新器如何跨版本升级。
个人与配套存储	个人 GitHub 连接、个人模型账户，以及 Apple companion 投递日志。
存储变更与发布预检	为另一种后端做准备、实质性变更的审查检查点，以及 `openclaw database preflight`。
工作器中的数据库访问	将运行时读写从 Gateway 主线程移出，同时保留其所有者。
工作器迁移清单	重现同步访问清单并选择下一次迁移。
Agent schema 历史	每个 Agent 数据库的 schema 版本、变更内容及其首次发布版本。
状态 schema 历史	共享状态数据库的 schema 版本、变更内容及其首次发布版本。
完整性、故障排除与恢复	完整性检查、常见数据库错误，以及受支持的降级恢复路径。

备份 — 归档、按数据库快照、调度安排，以及本文所述数据库的异地副本
更新 — 安全更新，包括提升 schema 版本前应做的已验证备份，以及回滚策略
Doctor — 修复过期配置/状态并报告健康问题的修复与迁移工具
openclaw doctor — 运行这些迁移的命令的 CLI 参考
openclaw update — 对 schema 支持执行预检的更新器的 CLI 参考

各章节去向¶

先前单页版本中的每个章节标题都在此处保留其锚点，因此诸如 /reference/database-schemas#schema-bumps-and-older-updaters 之类的现有链接仍然有效。每个条目都指向现在承载该内容的页面。

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

数据库模式

相关¶

各章节去向¶