本页内容
本页内容
技术参考
版本控制合同
版本控制契约
已承认的空共享状态数据库是在迁移所有者事务中的当前版本中直接创建的。它不会重播历史行转换或验证和修复刚刚安装的规范模式。数据库开放准入仍然适用。现有数据库和本机引导数据库保留版本化迁移和验证路径；创建保留相同的目录 SQL 和首次使用表策略。
每个数据库将其发布的模式记录在两个位置：
PRAGMA user_version是 SQLite 的模式版本。- 主
schema_meta行记录role、agent_id、schema_version和app_version。app_version是最后一次写入模式元数据的 OpenClaw 构建版本。
OpenClaw 在打开较旧的受支持数据库时应用只进迁移。它拒绝 user_version 比正在运行的版本更新的数据库，并报告 newer schema version 错误。网关在启动前检查所有已注册的数据库。 openclaw update 还拒绝声明模式支持早于磁盘数据库的包或源目标。在添加模式元数据之前发布的已知稳定版本将根据其附带的 schema-1 合同进行检查。由 2026.9.2 发布线驱动的更新可以在旧更新程序完成时暂时推迟共享状态架构版本的发布；请参阅 架构颠簸和较旧的更新程序。
本机客户端对其本地 device_identities 和 device_auth_tokens 表进行了极小的例外处理。连接到远程网关不得依赖于不相关的本地后端迁移。仅当其全局元数据与 user_version 匹配并且凭证表和索引定义仍与完整的本机合约匹配且无需其他索引或触发器时，才允许这些存储使用较新的共享状态模式。缺少或不兼容的表仍然是错误；本机客户端永远不会修复它们或更改任何架构版本标记。现有的身份密钥和网关范围的令牌保留在同一数据库中，无需迁移或第二个事实来源。
这些表名称、定义和凭证行含义是稳定的本机存储契约。未来不兼容的凭证语义必须更改表名称或定义，以便现有客户端拒绝访问；仅更改后端版本并不是凭证兼容性围栏。配置、执行批准、端口监护状态、网关启动和更新程序准入保留其后端架构版本检查。当本地后端超出其支持的架构时，此异常之前的应用程序仍然需要应用程序更新。
当网关启动遇到较新的数据库架构时，它会以状态 78 退出，因此生成的 systemd 服务不会重复重新启动它。在 macOS 上，它还停放其托管的 LaunchAgent 以阻止 KeepAlive 重试。这适用于 CLI 引导以及服务器启动期间的故障，并且不依赖于数据库支持的崩溃计数器。使用支持现有架构的构建启动网关。较旧的安装无法使用 openclaw doctor --fix 修复它们；如果需要进一步迁移，请从兼容安装运行 openclaw doctor --fix，然后通过服务或部署所有者重新启动。
即使此构建无法解析其目录，也会读取更新发布的架构版本的准入报告。已知的遗留索引缺陷不得用使用旧版本修复数据库的建议来取代拒绝。 Doctor 在停止网关服务之前检查兼容性。
共享状态 schema 24 将 11 个保留任务索引替换为 runtime/run 查找和两个有序 Cron 历史索引。行和历史顺序未更改。仅支持模式 23 或更早版本的构建拒绝它；二进制回滚需要经过验证的升级前备份及其匹配的版本。
目标发布检查将目标的模式支持与正在运行的检查器的功能区分开来。当共享状态对于目标来说太新但检查器仍可读时，预检将继续检查代理存储并报告所有不兼容性，而无需修改源文件。
只有在降级后的读取器仍然安全时，变更才可以保持在相同的模式版本。新增表符合此条件，因为较旧的构建会忽略它们。现有表中明确兼容的列也符合此条件，但仅限于其声明严格为一个不带修饰的、可为空的 SQLite STRICT 数据类型：ANY、BLOB、INT、INTEGER、REAL 或 TEXT。该声明不能包含默认值、NOT NULL、主键或唯一键、检查约束、引用、排序规则、生成表达式或其他后缀。对现有表的带约束新增内容必须提升模式版本，或改用配套表。
会话窗口预览缓存添加了裸露的可空 row_transcript_json TEXT 和 row_transcript_updated_at INTEGER 列，没有数字版本冲突。入场将栏目添加到现有商店；每行都通过代理编写器延迟填充。较旧的版本会忽略它们。仅当其源转录时间戳和索引序列仍然匹配时，缓存才可重用：较旧的正常写入会提前时间戳，而较旧的导入可以保留 mtime 但会提前索引。丢失或无效的缓存会触发有界回填；规范的转录字节、保留和回滚语义保持不变。
代理删除在首次删除或 Doctor 重建时将可空的 phase TEXT 列添加到其现有日志中。 draining 关闭入口，同时现有运行中止并在数据库报废之前解决。承认的使用刷新保留其数据库执行，直到写入解决，然后释放其进程本地刷新保留。在本机编写者退休之前，历史资源所有者会耗尽他们的工作并清理所选代理和捕获的数据库路径；不相关的商店继续营业。已退役的本机执行无法接受新的刷新写入。清理失败仍然可见，并保留排水监管；在清理完成之前，干预读取无法替换该退休资源，因此重试删除会耗尽同一所有者的资源。删除所有者随后记录 retiring 并完成清理。重启后恢复恢复记录的阶段；重试永远不会使退休状态再次耗尽。没有该列或具有空阶段的日记帐保留其先前的停用含义，而无需重写其路径或完成状态。老读者继续将每个日志行视为删除栅栏，并且可能需要显式清理重试。数字架构版本、日志保留和回滚备份策略保持不变。仅退休呼叫者将阶段保留为空。自动网关恢复将那些保留了 Claw 所有权的日志留给了现有的 Claw 删除所有者；其选择性包和工作区清理仍然需要重试删除计划。
Linux Node 工作器清理使用附加 node_worker_launch_process_scopes 配套表。其发布绑定的 linux-subreaper 证书独立于 node_worker_launch_cleanup.lineage_settled 记录内核后代灭绝。现有的清理行保留 owned-anchor，但没有合成谱系补全，因此较老的读者保留不确定的保管权，而不是将新证书视为较旧的证明。现有行不会被回填或重新解释。伴随行在相同的保留策略下启动时会被修剪；架构版本未更改。
匹配的数字版本是必要的，但还不够。版本可以添加惰性或可启动修复的表、列、索引或触发器，而无需提前 user_version，因此同一版本的两个数据库仍然可以具有不同的形状。 OpenClaw 验证正在运行的版本所拥有的所需表定义、约束、索引、触发器、虚拟表和表选项。
每个代理伴随表 session_reactions 存储相同模式版本的消息反应行。共享数据库开放附加模式将其安装在现有数据库上，而不更改 user_version；老读者会忽略该表格。行绑定会话密钥、转录会话 ID、持久消息事件 ID、表情符号和反应身份，而不更改转录字节。删除会话节点会级联其反应。转录本替换和后缀删除会针对同一事务中已删除的消息标识进行删除反应，而重置会使旧实例行变得惰性。降级会使表保持完整并禁用 Control UI 反应，直到支持构建返回。无需回填或重写成绩单。
第一次准入会在每个进程负载时验证每个物理数据库的架构版本和形状一次。代理、共享状态和其他 SQLite 所有者与每个后来的句柄和工作人员共享这些承认的事实，包括空闲关闭后重新打开。被替换的文件需要首先获得其新的物理标识。迁移和修复所有者在成功解决 DDL 后验证其更改并发布新事实；回滚无法发布未提交的架构。 schema_meta 角色和代理 ID 描述物理商店的固定架构所有者。创建和迁移验证并发布它们；通过外部 SQL 更改该行不会将已接纳的存储重新分配给另一个代理。会话权限、租约和其他实时权限仍然是当前行决策。
目录形状相等不能证明 schema_meta 主行或 config_machine_state 内容版本标记在 DDL 中幸存下来。观察到的 DDL 没有所有者发布的替换事实会使这些行支持的准入过期。下一次所有者查找将验证它们一次；稍后处理并打开重用结果。历史元数据对其快照仍然是私有的，除非所有者将其与当前提交的准入完全匹配。回滚可恢复分阶段发布和连接本地版本事实。
网关拥有运行时数据库状态。提交的进程内写入收据使跨句柄和工作线程的缓存行无效，而无需查询 data_version、schema_version、user_version 或目录。其他进程必须通过网关路由写入或拥有独占的离线所有权。 SQLite 读取快照保留其视图直至结束；打开快照外部的语句可以查看当前提交的行。初始接纳仍然拒绝不受支持的版本。 Doctor、显式验证、迁移和快照一致性检查保留各自的契约。这不会更改存储的架构、迁移、持久性或更新行为。
GitHub 发布生命周期和存储库收据上可为空的请求者权限列需要 state 模式 18。交付的阅读器准确地验证这些可选表，并拒绝其他列，即使这些列是空的且可为空的。迁移保留请求者权限未知的历史行；版本提升还可以防止旧发布者在没有新权限检查的情况下重新打开请求。
会话标签查找对非空标签使用 session_nodes(label, session_key) 上的非唯一部分索引，而不更改代理模式 20。现有的可写模式所有者安装并修复索引；只读启动接受其不存在，直到该所有者打开数据库。现有但不同的定义仍然无法严格的离线验证；网关启动在准备就绪之前向同一可写模式所有者承认所需的索引修复，并记录重建的索引和经过的时间。缺少表和不兼容的列定义仍然会被拒绝。存储的会话 JSON、标签唯一性检查和保留保持不变。较旧的同版本读取器可以忽略额外的索引，因此二进制回滚使其完好无损。接受的设计记录在会话标签索引决策中。
ACP 恢复查找在现有 acp_sessions.identity_json 代理和 ACPX 会话 ID 上使用两个非唯一表达式索引。共享状态工作线程仅选择匹配的身份，存储会话读取保留请求者、后端和生命周期检查。重复的 ID 保留会话密钥顺序；过时的生命周期不允许恢复。未解析的别名和内部会话仍然不符合资格，如存储会话列表中所示。可写架构所有者在现有数据库上安装索引，而不更改架构版本或存储的行。构建扫描一次ACP元数据并使用临时磁盘；后续元数据写入会维护两个索引。较旧的同一版本读取器会忽略额外的索引，因此降级和二进制回滚会保留行和索引。没有引入新的缓存、保留策略或操作员配置。
任务和维护查找添加了非唯一索引，而不更改状态模式 17 或代理模式 21：任务请求者会话、按环境划分的工作人员放置以及有效性尚未确认的会话条目。任务运行时删除后，任务请求者索引仍保留在物理架构中。存储的行、保留和所有权检查保持不变。只读准入接受缺失索引；共享可写架构所有者安装或修复它们。初始构建使用的时间和临时磁盘与受影响的表成比例，后续写入将维护添加的索引。较旧的同一版本读取器可以忽略它们，因此二进制回滚会保留行和索引。请参阅 已接受的索引设计。
失败传递运行状况计数使用共享状态传递队列的现有 idx_delivery_queue_failed 索引以及列 (status, queue_name, failed_at, id)。这取代了相同架构版本中的队列优先定义。队列行仍然是事实的来源；导出非唯一索引。共享可写模式所有者在准入期间自动重建不匹配的定义，包括其完整性检查。不添加每个请求的修复或额外索引。重建使用启动 I/O 和与保留的队列历史记录成比例的临时磁盘，包括检查索引及其替换。后续写入保持相同的索引计数。较旧的同版本可写所有者可以在降级或二进制回滚时重建其队列优先定义，而无需更改行；严格的只读验证可能会拒绝更改的索引，直到可写所有者修复它。计数、空故障时间戳、排序、保留、权限和持久性不变；不需要架构版本冲突。
会议标题重试查找在 meeting_transcript_utterances(session_id, session_started_at, utterance_id)（其中 utterance_id IS NOT NULL）上使用非唯一部分索引，没有架构版本冲突。文字记录存储拥有存储的标题行；索引是派生的，并保留相同的 ID 修订、精确内容重试匹配和附加顺序。只读准入接受缺失索引；共享状态所需索引所有者在可写打开时安装或修复它，并且该功能的首次使用模式包含它。模式快速路径在接纳句柄之前检测丢失或漂移的索引。在现有数据库上构建扫描表并使用临时磁盘进行修复所有者的检查和最终索引。后续写入仅维护非空 ID 的索引条目。存储的内容、保留、权限和交易所有权不变。较旧的同一版本读取器会忽略附加的非唯一索引，因此二进制回滚会使标题行和索引保持不变。
Logbook 的插件本地数据库保留模式版本 1，同时用 batches(start_ms, id) 上的非唯一部分索引替换未使用的批处理日索引，其中 status = 'pending'。现有的工作人员拥有的模式打开会在删除已停用的索引之前在已填充的数据库上安装索引。批次行仍然是事实的来源；指数导出，保留率和回收率不变。初始构造扫描批次历史记录一次并仅存储待处理条目。较旧的同版本构建可以安全地读写数据库，保持新索引完好无损并重新创建其日索引；使用当前版本重新打开会再次停用它。二进制回滚不需要行转换或架构版本更改。
内存块准入会停用同一代理架构版本中的非唯一 idx_memory_index_chunks_path 索引。两个模式发布者都保留 (path, source) 索引用于路径和源查找。可写内存初始化在遗留存储验证后删除冗余索引；仅代理和只读准入可以容忍任一状态而无需重新创建它。较旧的可写版本可能会在降级或回滚时重建它。行和约束不变；参见存储决策。
轨迹保留将现有的 idx_agent_trajectory_runtime_run 定义替换为 (session_id, run_id, created_at, octet_length(event_json)) 上的完整覆盖索引，包括空运行 ID。代理模式 24 未更改。所需索引所有者在可写许可上重建同名漂移；初始构造读取轨迹历史并使用临时磁盘进行探测和替换。写入维护表达式索引。较旧的同版本可写所有者可以在降级或回滚时恢复其先前的定义，而无需更改事件行；严格的只读准入可能需要首先进行修复。在 v17 升级期间，Doctor 会标准化旧内存元数据并在创建目标模式对象之前验证旧模式。缺少所需的表或触发器仍然会被拒绝。在剩余数据迁移后修复所需的索引，并在同一事务中进行目标模式验证。拒绝会回滚迁移，并使数据库在修复之前无法运行。请参阅 存储设计。
删除任务和 TaskFlow 运行时不会更改共享状态或代理架构。现有的表、索引和可选的执行所有者列仍然是已发布存储合约的一部分。 Cron 通过自己的存储读取和写入 task_runs 中现有的 runtime = 'cron' 历史记录行。非 Cron 任务和 TaskFlow 行在运行时保持不变和未使用；它们不会转换为替代分类账。 Codex 插件的 Doctor 迁移 保留来自现有父绑定元数据中所有者标记的遗留行的合格本机子恢复事实，并具有防止重播的原子导入标记。源行保持字节相同。此删除不会伴随表删除、SQL 架构更改或架构版本冲突。
Node 工作线程恢复使用现有启动日志中的私有 node_worker_launch_cleanup 伴随表。启动所有者在首次使用时添加它，并在允许执行之前将选定的进程组或拥有的锚点传输记录在 cleanup_mode 中，与工作人员身份处于同一事务中。拥有的锚只能在其根退出并且其继承谱系达到正 EOF 后才能记录其确切的当前运行身份 lineage_settled = 1。恢复还会验证记录的进程组在释放容量之前是否已消失。缺失或模糊的谱系结果仍然未知；仅凭一个空的锚定群体并不能证明其他群体的后代已经停止。
节点恢复修复使日志保持为唯一的持久所有者。清理记录不包含启动描述符或凭据，不输入公共收据，并通过级联外键共享启动的现有 24 小时终端收据保留。 schema版本保持不变；老读者会忽略新的同伴表，而不更改他们的启动表合同。缺失的清理记录会保留已发布的 2026.9.4 进程组合约，而无需回填猜测的身份。使用未标记锚点的未标记中间构建必须在替换之前耗尽原始构建上的工作人员。活跃的现代工人在降级或回滚到较旧的作家之前也必须耗尽，这无法解释锚谱系的完成。
通知所有权在同一架构版本中使用裸露的可空 TEXT 列：session_watch_cursors.watcher_store_path、subagent_runs.requester_store_path 和 subagent_runs.controller_store_path。如果缺少的话，它们的作者会在第一次使用时添加它们；读取不安装它们。老读者会忽略这些专栏。 NULL 仍然未知，因此网关通知传递不会仅通过密钥将历史记录分配给当前父级。
新的子代理运行在 subagent_runs.payload_json 内的 childAgentId 中记录其选择的逻辑拥有代理，以获取原始密钥和代理限定密钥。当财产不存在时，历史有效的合格密钥仍然是所有权证据；冲突或不正确的所有权仍未得到解决。此运行时修复不伴随 DDL、新列、架构版本冲突或自动回填。当前配置定位已知所有者的商店；它无法识别原始所有者。未知所有者记录保持不变，并且没有资格进行普通清理。具有可解析子所有者和请求者所有者但没有原始会话身份或生命周期修订的历史记录未经遗留验证。请求者结算、交付、簿记和授权恢复或确切任务停止仍然可用，同时子会话突变被抑制。冲突的记录身份仍然不匹配；缺失的身份不会被回填。
相同版本回滚并不能保证老编写者保留此契约。编解码器往返不能证明现有行替换或可写重新打开。确切的基线 930bd387bbaa 是认证的候选者，而不是经过认证的目标或使用任何 schema-20 构建的权限。在同数据库回滚之前，完全耗尽排队启动、运行和暂停的工作、取消协调、请求者唤醒、交付、普通和收集器清理以及私有父完成义务。未解决的所有权、未绑定的原始监视游标以及出色的原始资源清理使得该消耗不完整；永远不要删除证据来满足它。
对共享和相关代理数据库进行协调的 WAL-aware 备份，然后针对副本预检确切目标，包括可写重新打开、现有行替换、普通更新、close/reopen 和重新升级。当期望得到修复的隔离保证时，不要在较旧的目标上运行受影响的原始密钥工作流程；请改用兼容的向后移植。 d64730851269 被排除，因为其替换写入器删除了所有者。未经验证的旧版本需要在单独的状态目录中匹配升级前备份。现有的新架构拒绝和私人父级完成降级限制仍然有效。
Cron 常设授权定义生成在 cron_jobs 上使用三个裸露的可空投影：grant_definition_revision、grant_definition_generation 和 grant_definition_updated_at。保存的作业仍为 job_json。当前的编写者用它自动更新投影，推进实质性定义更改（包括编辑和恢复）的生成，并在禁用和重新启用时保留生成。
发布的 operator_approval_standing_grants 桌子保持了其精确的形状。首次使用的伴随表 operator_approval_standing_grant_generations 将每个新创建的补助金与其作业生成绑定，并与补助金级联。较旧的同一版本读取器会忽略同伴列和裸露的可为空作业列，因此他们可以重新打开数据库。重新升级后，没有伴随行的拨款将被视为遗留，需要再次批准；它永远不会追溯分配一代。工作重新创建会超越保留的同伴世代，包括当较老的编写者删除工作行时。
老作家不会维持这些预测。它的编辑使投影变得陈旧，因此当前的读者在重新升级后拒绝它。当旧版本正在运行时，它无法强制执行生成绑定，并且保留每个可观察作业值和时间戳的更改以后无法重建。不需要回填或模式版本提升。已接受的设计和回滚合同记录在#142153中。
保留的 ACP 导入对裸可为空的 session_nodes.legacy_acp_migration_json TEXT 列使用相同版本的附加列异常。如果首次使用时丢失，旧会话导入会添加它，并记录准确的源组件出处；普通会话编辑会保留它，而密钥规范化修复会在会话中携带它。正常的 ACP 初始化或关闭会通过 ACP 突变原子地消耗现有共享状态迁移分类账中的这些组件。稍后的 Doctor 重试会读取该完成事实，而不是将缺失的 ACP 行视为恢复旧元数据的权限。失踪的出处仍然未知；读者不会创建该列或从旧文件中重建它。该列遵循其会话的生命周期，而完成的收据保留现有的迁移分类账生命周期。不需要架构版本冲突。
较旧的同版本读者可以忽略可为空列并打开数据库。较早的 ACP 作者不记录此替换；当需要保护时，在返回到较旧的写入器之前完成挂起的迁移。
冷记录存储 需要代理架构 20，即使它添加了伴随表。年长的读者会将提取的转录行解释为缺失的历史记录，并且不能安全地忽略新的表示。支持的更新程序的Doctor阶段执行架构迁移；之后更改冷存储期限设置不需要重新启动网关。这些是单独的操作：实时配置重新加载不会授权活动架构迁移。
代理模式 21-24 需要会话验证挂起表及其节点、窗口和主键失效触发器。模式 25 删除了这些触发器和 entry_valid 重置触发器：会话编写器在 SQL 之前验证其最终序列化输入，同时离线导入和修复显式队列准入工作。这需要版本升级，因为较旧的模式检查器需要退役的触发器。迁移会保留有效负载，为所有现有节点提供种子，并在发布新版本之前清除旧的会话验证收据。准入仍然拒绝无效的导入行。使用旧代码重新打开被拒绝；回滚使用经过验证的迁移前备份和匹配的版本。请参阅 会话编写器验证。
代理模式 22 引入了精确转录 FTS 行所有权，具有可为空的完整性计数和延迟回填。模式 23 接受已部署的形状以及模式 21。它根据现有 FTS 内容重建所有权映射，保留挂起的协调，并淘汰旧的完整性计数器。
代理模式 23 更改了现有的有效负载表示：转录事件可以使用 Zstd BLOB，内存嵌入使用 Float64 BLOB，内存全文维护使用稳定的整数块标识。较老的编写器无法保留这些合约，因此尽管保留了逻辑事件和块 ID，但这仍需要进行修改。共享状态架构仍为 17。使用情况汇总缓存格式随此迁移而变化，但可独立重建。请参阅 紧凑型代理负载存储 了解转换、运行时要求和恢复。
代理模式 19 在可为空的 session_pending_inputs.consumed_event_id TEXT 列中记录收集的输入消耗。 Doctor和该功能的首次使用初始化需要时添加；架构版本保持为 19。该列以 2026.8.2 （#133457） 形式提供，因此支持的 Beta 升级从 2026.8.2 或更高版本运行 Doctor。尽管共享版本 19，但已验证可选挂起输入表的中间构建可能会拒绝添加的列。消耗的源收据将保留，直到其会话窗口被删除，因此重写记录无法使旧输入再次可运行。
Cron 运行收据使用可选的 cron_run_trigger_state_retirements 伴侣，无需更改状态模式 17 或已发布的收据表的形状。它的唯一列是 receipt_id，这是引用 ON DELETE CASCADE 的现有收据的主键。已提交的条件、脚本有效负载或共享状态编辑会在与作业编辑相同的事务中创建停用行。这包括已由代理所有者编辑关闭但仍在等待运行协调的确切收据。正常完成和重新启动恢复会保留替换的状态，同时保留旧运行的历史记录。第一个符合条件的编辑创建表；排队的编辑不会撤销未来的评估。作业的专用运行时状态保留确切的运行收据 ID，直到调度程序协调为止，包括代理所有者编辑首先关闭收据时。即使运行时间戳发生冲突，恢复和后续状态编辑也会使用该关联。收据修剪保留待处理的收据；普通历史保留其现有的 64 收据绑定并删除退休行及其收据。
在记录此关联之前写入的行保留其遗留恢复回退。该关联不添加 SQL 表、列或架构版本。当前版本将其从公共作业状态和公共状态补丁架构中省略。
缺少表或行意味着没有记录的退休；早期的编辑无法从最终的作业定义中重建。较旧的兼容阅读器会忽略同伴，但不强制执行此保护。要保留已编辑的观察程序状态，请在降级之前完成当前版本上的活动运行和挂起的调度程序协调。终端历史记录结果或收据仍然可能使作业状态不一致。
在运行等待协调时进行的计划编辑会在现有作业运行时状态中记录私有 runningScheduleChangeId，与编辑位于同一事务中。即使被动编辑器的快照跨越两次运行，新值也能区分连续提交的编辑。完成和恢复保留编辑的调度状态；新的运行和待运行的清理会清除标记。这不会添加表、列或公共作业字段。
没有此标记的待处理运行将保留其之前的恢复行为。旧版本确认的编辑无法根据时间戳或最终时间表可靠地重建。对这些待处理作业的新编辑会正常记录标记。较旧的兼容读者会忽略它；如果必须保留编辑的节奏，请在降级之前完成挂起的运行。
工作器准备对共享状态数据库中的裸露 worker_environments.preparation_purpose TEXT 列使用相同版本规则。共享状态数据库启动修复添加它而不改变状态模式 17. 新入场写入 reserve 或 build；现有准备行保留 NULL 并读取为 reserve，不回填需求或更改到期时间。老读者会忽略该专栏，并将现有的储备政策应用于所有准备好的工人；如果必须完成，请在降级之前停止待处理的构建。重新开放保留了目的、消费、需求和清理所有权。
放置移动表对其裸露的可空 abandon_source INTEGER、target_machine_class TEXT 和 target_os TEXT 列使用此相同版本规则。如果缺少这些列，该功能仅在第一次使用时添加；数据库启动时不会添加它们，并且架构版本保持不变。 target_machine_class 和 target_os 保留显式配置文件目标覆盖； NULL 表示无覆盖。对于abandon_source，NULL表示普通先调和机芯； 1 记录操作员明确的离线设备放弃决定，因此重新启动恢复不会意外恢复远程协调。老读者会忽略添加的列，并可以安全地重新打开同一数据库；他们不实施较新的操作系统覆盖。
对话关联对可为空的裸 route_context_json TEXT 列使用相同的规则。如果更新的二进制文件缺少该列，则数据库打开修复会添加该列。老读者可以忽略它，可以安全地重新打开并更新同一数据库；它们的关联更新会使较新的编写器捕获的上下文无效，因此在重新升级后无法重播。
保留的对话进度快照使用代理数据库的 cache_entries 表（范围为 conversation-progress）和传递操作 ID 作为键。任务支持的分离演示者已被删除，但其存储的快照和收据清理合同保持不变。此删除不会伴随任何表、列、架构版本更改或迁移。较旧的收据不会被回填。
收据拥有已知的平台消息身份和传递状态。删除的演示者不再写入或读取进度快照。现有快照字节保持不透明保留数据；所需的演示并不能证明平台编辑已交付或工作已完成。
重新打开不会从缓存的快照中恢复已删除的任务演示者；快照从不授予执行或交付权限。存储会话修复携带快照及其接收标识。现有的会话传递清理会删除匹配的快照密钥及其收据，没有新的过期策略、清理循环或完成所有者。
转录上下文资格使用裸露的可为空的 session_transcript_active_events.context_eligible INTEGER 列，而不更改代理模式 18。数据库打开安装该列和未分类行的非唯一部分索引。 1 包含有界上下文获取中的条目，0 排除仅显示活动，NULL 表示投影仍需要协调。 Bootstrap 控制标记仍然符合资格；历史计数、位置和光标不会改变。原始成绩单 JSON 仍然是事实的来源。
较旧的同一版本编写者可以在不提供资格的情况下追加或重建。即使其序列水印是最新的，现有的转录协调器也会检测其 NULL 行，然后在发布准备就绪之前从原始事件进行重建。当这项工作悬而未决时，读者返回一个可重试的投影不可用的结果；他们不会解析每个有效负载或猜测资格。初始索引创建扫描一次投影元数据，启动时等待与线程外解析和有界写入块的协调。重建总成本仍与历史成正比。重写在自己的事务中使投影无效或重建，而转录删除则删除其资格行。降级使附加列和索引保持不变；重新升级协调未知行。
多账户人员配置文件在首次使用配置文件时添加裸露的可为空 user_profiles.primary_github_account_id INTEGER 列，而不更改共享状态架构版本。现有的单账户配置文件具有明确的主要信息；显式合并保留所有已验证的帐户行并保持目标主要。这故意接受降级限制：较旧的单帐户作者可以丢弃辅助帐户链接或再次拆分链接的人员。重新升级无法重建废弃的链路。降级前保留备份，并在升级后明确重新链接受影响的配置文件。版本号并不证明多帐户关系的保存。
用户配置文件对状态模式 9 中可为空的裸 user_profiles.role TEXT 列使用相同的规则。如果首次使用时缺少该列，则操作员角色分配会添加该列。老读者会忽略该列，并可以安全地重新打开同一数据库。
Web 推送订阅所有权对可为 null 的裸 web_push_subscriptions.device_id TEXT、user_profile_id TEXT 和 preferences_json TEXT 列使用相同的规则。如果首次使用时丢失，Web Push 将添加所有三列。现有行保持未绑定状态并且仅用于测试，直到浏览器重新连接；老读者会忽略这些列，并继续安全地读取或更新端点和关键字段。
批准通知清理使用相同版本的附加 web_push_approval_deliveries 表。它记录 approval/subscription 标识符以及可能已到达浏览器的通知的请求时间 device/profile 绑定。仅当当前订阅仍具有该绑定时，终端或重新启动的网关才会发送。该表是在第一次使用时延迟创建的，行随其批准或订阅而级联，老读者可以安全地忽略它。
通过 npm 手动安装 OpenClaw 会绕过更新程序防护。数据库打开检查仍然拒绝不兼容的构建。
结构化 目标控制 使用惰性每代理 session_goal_operations 表，而不更改架构版本。目标 start/resume 在一笔事务中提交目标转换、输入轮次、运行生命周期和操作接收。管理运营将目标转换和接收一起提交。老读者会忽略添加的表格。收据在目标明确和会话 reset/deletion 后仍然有效，直到其 24 小时有效期到期；稍后目标会写入修剪过期行。它们保留原始结果和带密钥的请求指纹，而不是第二个原始请求。没有回填或配置切换。降级会保留该表，但会禁用新的结构化控件；升级后可以读取保留收据。
可变 JSON 谓词投影需要 agent 模式 26。较老的作者必须被隔离，因为他们更新规范的 JSON 而不维护升级的列。前向迁移将每个保留行回填一次； NULL-仅在重新打开时修复无法使降级和重新升级安全。
Schema 碰撞和较旧的更新程序
OpenClaw 2026.9.2 引入了更新分类账，但在运行目标 Doctor 后用旧代码重新打开它，包括记录其最终结果后的最终读取。共享状态数据库运行程序让此更新程序通过首先应用迁移内容并稍后发布新架构版本来完成。此规则适用于每个可写打开，包括 Doctor、重新启动的 Gateway 和其他 CLI 进程。
运行器将应用的内容版本记录在现有的config_machine_state密钥state.schema.contentVersion中。虽然发布被推迟，但新代码使用该内容版本，并且 PRAGMA user_version 和 schema_meta.schema_version 都保留先前发布的版本。内容及其标记一起提交。重新打开会跳过标记已涵盖的迁移步骤；它不会从表形状推断完成或重复已完成的重建。这不需要新表、配置选项或环境覆盖。
即使其版本尚未发布，当前内容也已准备好供读者使用。只读 CLI 操作和网关路由突变可以在整个窗口中与网关一起运行。当网关停止时，独立的 SQLite 写入者需要独占所有权；旧的更新驱动程序保留下面的显式移交合同。单独发布不会触发架构修复或需要停止网关。
后续更新可以在此窗口期间运行。其迁移验证和回滚检查会比较私有数据库快照中的应用内容版本。发布已应用的内容并不是另一次迁移；而是一次迁移。即使发布的数量没有改变，应用新内容仍然会阻止回滚。托管服务停止、激活和 Doctor 维护保持其正常的所有权规则。
发布等待，直到 every 更新行（其 before.version 标识 2026.9.2 发布行满足其适用条件）：
- A 终端行的
finished_at_ms至少已存在五分钟。 - A 跑步排的
updated_at_ms已超过 30 分钟。跑步者将该车手视为出于出版目的而被放弃；它不会重写运行结果。
丢失的分类帐或没有受影响的行允许立即发布。截止日期来自行的时间戳，而不是观察进程的开始时间。新网关的账本观察者安排在适用的截止日期发布，没有抖动。发布持有网关生命周期栅栏：拥有的网关可以发布，并且当没有网关拥有状态目录时，稍后可写的打开可以发布。其他进程默默地将发布留给该所有者。在推进两个已发布的架构标记之前，发布会重新读取一个同步写入事务内的内容标记和所有受影响的行。新的或刷新的运行行再次阻止发布。重新启动网关不会缩短或重新启动宽限期。
五分钟的宽限期可容纳 2026.9.2 的尾随账本读取；该版本没有记录任何驱动程序进程标识来证明这些读取已完成。旧的 CLI 在提交其终端行后阻塞了五分钟以上（例如在停滞的标准输出管道上），在发布后仍可能导致最终渲染失败。到那时，包交换、任何请求的服务重新启动以及终端分类帐结果都已完成。 2026.9.2 线路的降级保护也会因同样的宽限期或 30 分钟废弃驱动程序限制而延迟。保留的版本不允许针对迁移的功能表运行旧代码。请勿手动降低任一版本标记或删除内容标记。
更新时 Doctor 在进行其他修复之前会检查共享和注册的代理数据库。仅状态迁移将继续进行并延迟发布并报告 schema content applied; version publication deferred until update run <id> finishes。运行结束后，出版物仍然遵守五分钟的宽限期。代理架构版本不会延迟或重新标记。对于受支持的 2026.9.2 软件包更新，早期的 Doctor 在专用数据库副本上运行架构修复，而旧驱动程序仍然可以回滚其软件包安装。只有在私人医生及其子女成功安顿后，才会报告成功；实时代理数据库保持不变。没有注册备份所有者的已知挂起代理数据库在此回滚窗口期间仍会拒绝。
交付的驱动程序提交包并进入新的后核心阶段后，当前更新程序将 Doctor 委托给其执行者和维护所有权。 Doctor 在正常实时迁移之前创建并验证涵盖每个待处理代理数据库的保留恢复存档。覆盖范围需要匹配代理所有者和物理文件身份，包括注册的自定义路径；不透明存档字节不是经过验证的 SQLite 快照。备份工作后以及在版本化模式写入和提交边界处再次检查权限和实时文件身份。 Doctor报告保留的存档路径；它不会在以后出现故障时自动恢复该存档。
当无法验证阶段或当前所有者、缺少可恢复备份覆盖范围或缺少所需的 config_machine_state 表时，Doctor 会保留键入的 update-schema-bump-unfenced 拒绝。私人排练和备份失败会使实时代理模式保持不变。失败的内容事务将回滚。拒绝包括受影响的数据库版本、驱动更新程序版本和手动更新命令。包回滚无法逆转已经发生的迁移；实时迁移后的恢复需要经过验证的备份和匹配的版本。
驱动程序检查需要有效的语义版本并包括 2026.9.2 重建。早期的更新者，包括2026.9.1，没有账本并保持正常的发布行为。从 2026.9.3 开始构建，包括预发布，使用事务更新来隔离旧进程分类账访问，并让候选代码在迁移后完成；他们还保持正常的出版行为。相同架构的修复和普通的 Doctor 运行仍然可用。
个人资料拥有的技能库
个人和团队技能在共享状态数据库中使用四个首次使用表而不更改其架构版本：skill_library_entries、skill_library_revisions、skill_library_events和skill_library_uploads。普通工作区技能和未使用的库发现不会创建这些表。所有权、共享、当前修订指针、可移植文件清单和发布事件都存储在 SQLite 数据中。会话选择保留在现有的每个代理会话存储中；继承的 cron 选择保留在现有的私有作业记录中。
完整的技能包是 <state-dir>/skill-library/<skill-id>/revisions/<revision-hash>/ 下的产品工件。在一个同步数据库事务中提交其当前指针和事件之前，发布会写入并验证不可变的捆绑包。并发编辑需要预期的修订。提交之前的崩溃可能会留下未引用的完整包，但不会留下指向部分写入内容的指针。共享和传输更改元数据，而无需移动修订文件。
删除一项技能会将其从未来的选择中排除；现有会话保留其选定的修订版本。已发布的历史记录和完整的孤儿修订版将得到保守保留。当另一个上传开始时，过期的上传记录将被删除；明显废弃的暂存目录会在以后的发布过程中被清理。备份状态数据库和技能库目录，而不仅仅是当前的修订指针。
较旧的相同架构读取器会忽略新表，但无法提供托管库选择或创作。更改构建时保持表和包目录完整；不要降低架构标记或删除修订来禁用该功能。接受的存储和所有权决策记录在 配置文件拥有的技能设计问题 中。
声明的迁移备份范围
最新版本迁移与相同版本修复是分开的。代理模式 25 和更高版本将不相关的附加索引留给可写修复所有者。在公开升级的存储之前，当前会话读取器所需的缺少的启动列仍会通过后续准入进行安装。声明的版本阶段将这些附加修复保留在其检查点之外。声明的共享状态进步同样只运行其挂起的版本步骤并为这些表安装索引。随后运行不相关的同版本修复。没有完整声明的旧源保留历史运行程序和完整备份。
从规范媒体架构升级的代理版本不会重复媒体行或存档修复。 Doctor 迁移前奏还推迟了这些目标的会话输入和转录指令修复，直到相同版本运行。显式同版本Doctor修复记录成功的媒体行和ACP事务性重播记帐通行证；稍后的运行将重用这些完成事实。恢复丢失的 ACP 会计列会强制再次回填。当今的作家保持着规范的价值观；不支持的直接 SQL 写入不会使这些历史修复标记失效。 Planner 维护使用有界 SQLite 优化，仅分析丢失或陈旧的统计数据。
启动迁移默认为经过验证的完整文件备份。迁移所有者可以在 src/state/schema-migration-backup-tables.ts 中注册其重写的表，并以数据库类型和目标模式版本为键。每个待定版本都必须有一个声明；一个缺失的声明使整个挂起的集合保持完整备份。一般Doctor和updater回滚仍然使用完整备份。备份所有者添加 schema_meta、SQLite 用户版本，以及对于共享状态、延迟架构发布的 config_machine_state。
声明涵盖了完整的迁移入口点，包括终结器、索引修复、触发器以及受删除表或索引影响的 SQLite 元数据。每个声明的迁移必须在从 src/state/sqlite-migration-scope.test-support.ts 到 assertSqliteMigrationScopePreserved 的代表性装置上运行。帮助程序会比较迁移前后每个未声明表的确切架构和类型化内容哈希。包括填充的优化器统计信息和相关的同级表；仅帮助程序测试并不能证明所属迁移的范围。重建分析表或索引时，一起声明 sqlite_stat1 和 sqlite_stat4。现有的迁移不会由其读取集隐式声明。
代理模式 27 声明 context_engine_turn_outbox 和两个规划器统计表。 Doctor 在采取此检查点之前验证源完整性。如果孤立历史记录阻止准入，则其恢复所有者会在修复和检查点捕获之前保留原始记录。 Doctor 然后在进入一般维护之前提交并验证版本阶段；其回收清单已在该边界完成。启动列、同版本索引和内存修复、会话规范化、转录修复、删除恢复和插件挂钩随后在其现有所有者下运行。仅当存在实际修复工作时，破坏性恢复和保留内容重写才会保留完整的原始内容。普通的元数据修复仍然是事务性的。因此，合格的干净版本凹凸不需要完整的代理映像。版本阶段固定装置验证每个未声明的表的架构和键入的内容是否保持不变，包括填充的保留历史记录。
共享状态模式 23 仅声明 meeting_transcript_sessions。它的版本阶段在代理维护租约可以打开或修改共享状态之前运行。范围备份包括两个发布元数据表，而不相关的修复和计划器统计信息保持不变。恢复通过表重建过程中存档的字节保留行编解码器保留实时未声明的规划器统计信息；显式声明的统计信息（例如代理模式 27）则从存档中恢复。
对于完全声明的迁移，Doctor 可以编写包含所选架构 SQL、行和版本元数据的同级 <database>.pre-startup-migration-<id>.scoped.bak。只有这个较小的存档才能进行备份完整性扫描；迁移的源完整性准入仍会检查完整数据库一次。 AUTOINCREMENT、virtual/shadow 表、不受支持的 SQLite 运行时或活动状态目录之外的源将回退到完整备份。伴随代理迁移的共享数据库保留其完整备份以用于注册表和收据恢复。
范围存档不是完整的数据库，绝不能替换源文件。停止网关和其他编写器，保留匹配的备份组，并在激活旧版本之前使用候选 CLI 恢复每个作用域成员：
该命令需要活动状态目录和原始数据库路径的脱机所有权。它只恢复一个事务中声明的表和版本元数据；错误会回滚整个恢复。未声明的桌子保留在原处。这不会撤消外部影响或协调迁移后进行的新写入；保留完整备份以用于一般灾难恢复。
包更新程序回滚继续使用完整文件快照。 Candidate Doctor 可识别已设置的驱动程序附带的更新阶段标记，并在这些阶段保留完整的启动备份。范围存档永远不会提供给较旧的更新程序或通用会话文件恢复命令。两种存档格式都使用现有的完成和稍后成功更新的清理规则。