跳转至

数据库模式

OpenClaw 将控制平面状态存储在共享状态数据库中,并将代理数据存储在每个代理一个 SQLite 数据库中。数据库打开时,模式迁移向前执行。较旧的 OpenClaw 构建会拒绝由较新模式写入的数据库。

Gateway 进程是每个 OpenClaw 数据库及其状态的唯一所有者。其工作进程和原生句柄共享该所有权。已提交写入回执在下次使用之前使进程内行缓存失效;没有完整写入者覆盖的缓存必须改用直接读取。运行时读取不会使用 PRAGMA data_version、版本观察或外部观察作用域来探测外部提交。处于打开的读取事务之外的 SQLite 语句已经能看到已提交数据。单语句读取无需显式事务;多语句读取在结果需要一个一致快照时保持事务。CLI、Doctor、cron 和插件子进程必须通过 Gateway 路由变更,或者在 Gateway 停止时获取独占所有权。首次准入、迁移、修复和最终实时权限检查保留其现有所有者。

原生 SQLite 初始化在准入真实状态数据库之前,通过一次查询读取已加载库的版本和扩展能力。Auth-profile 读取器在连接打开时安装其锁等待超时。隔离决策读取器和写入器在连接打开时设置其现有锁等待超时。隔离存储的格式每个物理数据库每个进程只准入一次,同时现有守卫保留在一个 SQLite 快照中对索引化持久隔离行的查找,并验证任何已记录的文件代际。独立的检查进程可以在 Gateway 验证器确认损坏之前准入目标;其下一个守卫必须观察到该已记录的拒绝,即使目标的物理身份未变。隔离行保留其路径名作用域,别名仍然共享物理格式、模式和完整性事实。持久化的模式、WAL 安全性和恢复行为保持不变。

受管写入在公开观察者之前发布已提交事实。私有回执区分显式缺失与不完整覆盖,并独立于回复投递保留已知提交。有关顺序、回滚以及仍保留原生守卫的写入器族,参见 已提交事实与完整性。

SQLite 格式、模式版本、完整性、规范索引和表存在性验证在每个进程加载时每个物理数据库运行一次,在其首次准入时执行。已准入的事实与所有工作进程和句柄共享,包括空闲关闭后的后续打开和重新打开。文件身份使用卷、inode 和稳定出生时间,通过 fstat 检查,而不是 SQL。被替换或恢复的文件需要其自身的首次验证。迁移和修复所有者验证其更改,并在 DDL 成功结算后发布新事实;后续运行时使用者不会重新检查它们。Doctor 和显式验证保留其检查,观察到的损坏仍会撤销准入。

共享状态和代理只读连接在其原生连接生命周期下复用有界预编译语句。仅复用预编译语句不会保留查询结果。模式事实查找使用进程已准入的事实,而不使用 SQL。写入器回执跨连接使缓存行结果失效,而不再次查询 data_version、schema_version、user_version 或目录。当前行权限检查保留在其效果边界处。活动 SQLite 快照内的缓存行使用该快照的身份和连接的本地变更修订。它们从不携带当前已提交写入修订,也不会在快照结束后变为可复用。自动提交缓存使用拥有写入器的回执。关闭连接会清除其预编译语句和行缓存,而物理数据库准入在进程生命周期内持续存在。

共享状态内容版本检查跨句柄和工作进程复用物理数据库已准入的版本事实。普通提交、事务和连接关闭不会强制再次读取标记。迁移所有者随其已提交模式发布替换事实。观察到没有替换事实的 DDL 会使内容版本准入过期:未变化的目录形状不能证明 config_machine_state 标记仍然存在。下一个所有者查找会验证一次,后续打开复用该结果。历史快照保留其自身的标记事实;发布需要与当前已提交准入的正向匹配。每个调用者仍应用其已发布版本下限。模式版本、存储字节以及升级或降级行为保持不变。

新的代理读取器复用进程的模式准入。共享状态工作进程读取消费写入器失效的缓存事实或当前行,而不进行新鲜度探测。点转录统计、变更时钟、待归档检查和热/冷水印使用单语句的快照;复合读取保留其读取事务,热转录读取复用现有事务,而不使用嵌套保存点。让出写入准入会在获取写入事务后立即一次性恢复其临时繁忙超时,并携带继承的锁截止时间,而不会重新读取连接的超时。FIFO、锁等待预算、模式、存储数据和更新行为保持不变。

已准入的目录包括与表并列的索引名称和触发器定义。规范会话验证消费这些定义,而无需另一次目录扫描。首次规范索引准入共享模式契约读取器的批量元数据快照,而不是分别查询每个表和索引。被遮蔽的 PRAGMA 名称在该验证期间保留原生检查。授权、初始漂移检测、事务性修复和完整性检查保留在其现有所有者处。首次使用的模式所有者仅当所有表和索引都存在于已发布事实中时,才跳过附加 DDL。缺失对象使用现有安装事务,该事务在提交时发布新模式事实;回滚不能发布未提交的模式。普通连接替换和数据提交不会重复模式验证。模式、存储字节和更新行为保持不变。

已接纳的模式事实在仅数据事务结算后仍然有效。已提交写入回执会使缓存的行事实失效。事务本地的模式事实视图随其 SQLite 快照结束;下一个事务消费进程已发布的事实,而不重复验证。

进度卡片写入复用该事务已接纳的表事实。模式所有者仅在表不存在时创建惰性表,并为每个句柄和工作进程发布已提交事实。回滚的安装保持不存在,直到下一次正常安装事务。已存储卡片、修订墓碑、模式版本以及升级或降级行为均不变。

agent-database 执行所有者按最近最少使用顺序保留最多四个空闲物理 agent 执行器。借用执行器会刷新其独立的 30 分钟空闲超时;第五个空闲执行器会驱逐最近最少使用的一个。对 agent 名册或存储路径的配置变更会停止热保留,并在其最后一个借用者结算后排空受影响的执行器。已接纳的工作保留其原始物理存储;新请求解析当前配置。显式数据库关闭和 Gateway 关闭仍会撤销并排空现有生命周期资源。这不改变任何模式、存储字节或更新行为。

在已接纳的不存在路径创建 agent 数据库,会在工作进程准备之前撤销先前文件保留的验证。重新创建的文件即使 Linux 复用其 inode 也无法借用该证明。普通重新打开仍会复用有效证明,新存储保留其规范认证。回执标识符在工作进程转移后仍然保留,因此别名发布会撤销被取代的证明,同时保留已确认的副本。后续撤销仍拒绝发布。模式、存储字节和更新行为均不变。

保留一个已打开的 agent 句柄会维持其生命周期,而无需查询 SQLite。写入者回执会使该句柄缓存的行事实失效;模式事实来自进程范围的接纳。规范就绪状态在拥有写入者更改存储时,会使干净存储决策失效。

schema_meta 中的 agent ID 和角色描述物理存储的固定模式所有者。创建和迁移会为每个句柄和工作进程验证并发布这些事实;普通提交不需要再次读取所有权元数据。观察到没有所有者发布的替代元数据的 DDL 会使该接纳过期,即使重新创建的表具有相同定义:其主行必须由下一次所有者查找验证一次。历史元数据随其快照保留,直到与当前已提交接纳明确匹配。外部行编辑不会重新分配一个已接纳存储。实时会话权限、租约所有权和调用者权限保留其当前行检查。动态授权器保留原生元数据读取。这不改变任何模式、存储字节或更新行为。

注册表发现复用已接纳模式代次的成功迁移检查。分钟级保留扫描在工作进程中读取删除历史,并在其 agent 存储之间共享一个匹配器;实时删除状态和生命周期提交保护仍然适用。Cron 注册表保留在其读取工作进程中验证完整列表,并只将 cron 运行条目返回给 Gateway;普通会话元数据保留在工作进程中。旧版监视标记发现使用索引前缀范围。即使没有写入,保留也会随着行老化而继续;模式、升级和保留策略不变。

会话行事实读取复用规范延续的现有事务,而不是嵌套保存点。没有活动事务的读取仍会打开一个事务,使条目元数据、看板存在性和转录水印共享一个快照。看板存在性随精确条目查询一起传递,包括其单键错误回退,而不是单独的 Board 读取。

放置投影在每个有界批次中用一条语句读取放置、移动、待定结果、日志和环境事实。批次共享现有读取事务;日志和结果声明检查消费相同的快照事实。可选列来自已接纳的模式事实,并随该所有者刷新。

共享状态读取操作通过其同步领域读取保留其接纳修订。ACP 元数据在该修订下每个连接最多复用 128 行;写入者回执、模式变更和关闭会使复用失效。事务以及固定或授权器控制的读取仍会查询 SQLite。提供的共享状态写入者复用其选定句柄,并在 BEGIN 之后检查所有权,而不进行重复的事务前行读取或模式验证。 存储字节、模式、权限和更新行为均不变。

精确条目和参与者读取器在已接纳的连接修订处保留其最后结果。重复读取复用这些事实,直到拥有写入者的回执、回滚、模式变更或连接退役使其失效。会话修订保护和维护快照保留其变更和快照谓词;事务进入、回滚和结算保留其现有失效机制,而不进行外部提交探测。 模式、存储字节、权限或更新行为均不改变。 返回的条目和参与者身份仍由调用者拥有。转录水印读取在一条语句中选择热代次和保留的冷或热序列;仅热读取器保持其现有含义。这些查询变更保留模式、存储字节、实时权限和更新行为。

显示历史读取器按会话和事件 ID 解析所选活动锚点,并在同一读取快照内保留序列围栏。这些点查询使用现有主键,不需要模式或数据迁移。

会话条目写入将其保存的快照字段批量处理为一次 upsert,保留逐字段修订触发器和回滚。

规范主密钥策略、外部监督所有权和机器拥有的 TTS 偏好路径针对物理数据库加载一次,并在句柄和工作进程之间共享。其拥有写入者发布已提交的替换;无关写入不会使这些事实失效。Gateway 拥有运行时写入。其他进程必须使用该所有者,或在其停止时运行,但既定的更新器交接、重启哨兵和更新最终化写入者除外,它们保留自己的生命周期围栏。所有权声明需要独占的离线保管。显式所有权检查和 Doctor 仍会读取数据库,实时生命周期和租约检查保留在效果边界处。缓存的策略事实不授予规范接纳或延续权限。主密钥写入者发布携带主机修订,因此工作进程可以在无关写入后保留一个不存在的发布,而无需轮询。嵌套工作进程仅转发其实际收到的主机完整性。共享代次布局将写入回执保留在槽位 5,将主机发布完整性保留在槽位 6;这些独立见证者从不共享计数器。存在的主密钥值是数据事实:无关 DDL 不能退役一个已提交的配置后映像。缺失的策略行随连接的读取修订保留,直到模式所有者的种子或规范写入者使策略可用。不确定的回滚可以丢弃一个数据事实,并在重用前要求一次修复读取。

Mentions Inbox 通过相同的物理所有者保留其已提交 head。 未更改的 head 会跳过快照 worker 分发。已更改或不确定的变更会在恢复其 FIFO 之前, 通过一次原子查询读取 head 和保留来源;未知写入结果永远不会授权重放。会话条目变更代际 与其连接一起保存在 JavaScript 中。TEMP 触发器观察精确的会话和参与者写入,回滚会使代际失效,而不会选择 TEMP 计数器行。Auth-profile 读取器使用已接纳的目录事实来处理表、视图和缺失,而不是每次读取都查询目录。这些更改 保留模式、存储字节、持久性、保留策略、权限和更新行为。

设备配对通知器在其服务生命周期内保留空的订阅者和投递回执状态,因此空闲的定时扫描不会重新读取两个存储。 它自身跨 Gateway 和 agent 注册表的写入会使该事实失效,包括不确定结果,服务重启会重新加载它。活动通知保留 其当前订阅检查和投递回执;持久化订阅和回执保留策略不变。

Gateway 不会安排每日全数据库扫描。准入请求的后台检查仍限于所请求的 agent 数据库:quick_check 用于干净重启证明,或在已证明的同一次启动进程死亡后,或在验证器运行期间原生 WAL 准入但没有验证回执时执行完整检查。 有关溯源要求和操作员请求的验证,请参阅 完整性准入和 Doctor 维护。

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

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

此页面是一个索引。参考内容记录在聚焦页面上,每个读者任务对应一个页面。 打开与你的任务匹配的页面并停留在那里。

页面 何时阅读
数据库布局 两种数据库角色、它们的磁盘路径以及各个功能背后的表。
版本契约 如何记录模式版本、何时需要提升版本,以及更新器如何跨越一个版本。
个人与 companion 存储 个人 GitHub 连接、个人模型账户和 Apple companion 投递日志。
存储更改与发布预检 为另一个后端做准备、实质性更改审查检查点,以及 openclaw database preflight。
worker 中的数据库访问 在保留其所有者的同时,将运行时读写移出 Gateway 主线程。
worker 迁移清单 复现同步访问清单并选择下一个迁移。
agent 模式历史 每个 agent 的数据库模式版本、其更改及其首次发布。
状态模式历史 共享状态数据库模式版本、其更改及其首次发布。
完整性、故障排除和恢复 完整性检查、常见数据库错误以及支持的降级恢复路径。
  • 备份 — 此处所述数据库的归档、按数据库快照、计划任务以及异地副本
  • 更新 — 安全更新,包括在模式提升前需要采取的已验证备份,以及回滚策略
  • Doctor — 修复陈旧配置/状态并报告健康问题的修复和迁移工具
  • openclaw doctor — 运行这些迁移的命令的 CLI 参考
  • openclaw update — 预检模式支持的更新器的 CLI 参考

各章节迁移位置

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

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