跳转至

State schema 历史

状态模式历史

发布版本 指明包含每项变更的第一个稳定发布标签,或在尚无稳定发布包含它时,指明第一个 beta 标签。多个模式变更可能首次一起包含在写入更高版本的发布中。 Unreleased 保留给既不在稳定标签也不在 beta 标签中的变更。 规划升级时,请使用目标发布的模式历史:已安装版本的 openclaw update --dry-run 不会显示目标的迁移计划。 旧版本构建会拒绝新模式;回滚需要经验证的升级前备份及其匹配构建,而不仅仅是重新安装旧软件包。

Doctor 会在后续工作区和代理检查运行之前,补全早于审计账本的已识别模式 1 数据库。在模式 2 或更高版本中,缺少所有权元数据或缺少审计账本仍会阻止修复。

版本 变更 发布版本
1 初始共享状态数据库 v2026.6.1
2 仅元数据消息审计事件 (#103903) v2026.8.1
3 STRICT 表和模式漂移加固 (#108663) v2026.8.1
4 会话监视溯源取代编码哨兵行 v2026.8.1
5 待处理工作区栅栏上的持久云工作器结果引用 (7a7d6bb, #110952) v2026.8.1
6 每个已提交的共享状态表都成为规范运行时模式的一部分 (509a5f0, #113473) v2026.8.1
7 移除已退役的推断承诺存储 v2026.8.1
8 云工作器放置执行模式和模式感知的轮次声明 v2026.8.1
9 根内代理数据库注册表路径相对于状态目录存储 v2026.8.1
10 六个废弃表退役 (agent_model_catalogs, android_notification_recent_packages, command_log_entries, diagnostic_stability_bundles, media_blobs, model_capability_cache) v2026.8.1
11 旧版技能策展人生命周期表和从未读取的提案来源运行投影退役 v2026.8.1
12 十三个单例/缓存表退役;持久状态合并到 config_machine_state v2026.8.1
13 状态整合:cron 作业和子代理运行变为 JSON 规范(移除 113 个投影列、5 个未使用索引);installed_plugin_index 和共享认证配置文件单例合并到 config_machine_state;workspace_attestations 合并到 workspace_setup_state;网关来源设备令牌成为规范 v2026.8.1
版本 变更 发布版本
14 带来源限定的 cron 创建者捕获;历史人工任务创建者仍未知 v2026.8.1
15 会话绑定使用精确目标键;冗余的代理/会话投影已移除 v2026.8.1
16 Skill Workshop 所有权从 workspace/provenance 列迁移到按代理的目录包含 v2026.9.3
17 预置 worker 生命周期事实和一次性节点工作区绑定 v2026.9.4
18 保留原始请求权限,并附带共享的 GitHub 发布回执 v2026.9.6
19 持久化原始频道所有者授权和撤销连续性 v2026.9.7
20 Cron 回执投递尝试围栏防止重放模糊的一次性完成 v2026.10.1-beta.1

更早的 beta 版本首次包含模式 1(v2026.5.30-beta.1)、模式 2(v2026.7.2-beta.1)、模式 3(v2026.7.2-beta.2)、模式 5(v2026.7.2-beta.4)和模式 6(v2026.7.2-beta.5)。

状态模式 20

模式 20 向 cron_run_receipts 添加 delivery_attempt_state。新的回执声明记录 not-started;回执所有者在完成交接或持久出站托管之前提交 started。该事实是单调的,表示投递可能已经发生,而不是接收方已确认。现有的回执保留和精确运行身份保持不变;没有额外的表或索引。

启动仅在其精确回执证明为 not-started 时,才能恢复被中断的一次性任务。处于 started 或旧版 unknown 的实例保持禁用,并带有 Unknown 投递状态以供检查。无回执的旧版运行标记也未知。仅排队运行、不同的操作员替换、重复计划以及精确的最终化历史保持其现有恢复规则。围栏提交和交接之间的崩溃可能导致 Unknown 而未发送;手动重试需要先检查接收方。

迁移以默认值 unknown 添加该列,而不会从缺失的历史证据推断未投递。启动和 Doctor 一起提交该列和模式元数据。旧的模式 19 调度器无法强制实施此围栏,因此即使物理添加是兼容 SQL,内容版本也会前进。现有的旧更新器发布延迟及其旧更新器宽限期保持不变。模式 19 准入拒绝较新内容;文档中记录的旧宽限期会延迟降级保护,直到其所有者退出或其窗口过期。

升级前创建经过验证且支持 WAL 的备份。二进制回滚无法移除此投递围栏:旧运行时必须拒绝已迁移状态。恢复升级前备份会丢失后续回执事实,并且不会撤销外部发送;在重试自动化之前,先核对这些影响。

Skill Workshop 提案退役(状态模式 20,同一版本)

Skill Workshop 不再存储提案。可选的 skill_workshop_proposals、skill_workshop_proposal_events、skill_workshop_proposal_rollbacks 和 skill_workshop_collection_reviews 表从规范模式中移除,且不提升版本;它们是惰性添加表,因此旧的同版本读取器已经容忍其缺失。打开仍包含这些表的数据库的行为不变:这些表不再被验证,运行时打开也永远不会删除它们。

openclaw doctor --fix,包括 openclaw update 启动的 Doctor 运行,首先在其模式序言中修复已知的格式错误的 idx_skill_workshop_collection_reviews_workspace_time 索引。其最终的 Workshop 步骤随后将每个 pending 或 quarantined 提案草稿及其支持文件写入 <agentDir>/workshop-skills/.archive/.retired-proposals/<proposalId>/SKILL.md,用于已记录的所有者代理,或在未记录时用于默认代理。带有 proposal.json 的 <state-dir>/skill-workshop/proposals/<id>/ 下的 Pre-SQLite 捆绑包以相同方式导出。现有导出永远不会被覆盖。在所有导出成功后,Doctor 在一个写事务中删除这四个表及其索引,然后删除旧版提案文件。任何失败都会保留表和文件并记录警告;重新运行 Doctor 会继续。已应用、已拒绝和过期的提案、事件历史、回滚元数据以及集合审查结果将被丢弃。

降级到仍会读取提案的构建版本需要升级前备份;导出的草稿仍为普通文件,可以重新创建为技能。

状态模式 19

模式 19 向现有 user_profile_identities 行添加可空的 authorization_id TEXT 和 authorization_basis_json TEXT。资料所有者会复用未中断频道链接的不透明 UUID,并仅记录其原始访问策略授权引用(或 JSON null)。它不会将频道身份复制到另一个存储中。引用是带版本的 JSON { "version": 1, "id": "<uuid>" },而不是凭据:恢复时会通过资料读取工作进程解析它,并重新检查当前角色或身份范围以及原始插件授权。未知版本、格式错误的引用、缺失的行或损坏的授权事实均不会授权执行工作。该模式提供所有者契约;消费者必须保留并重新验证其自身的效果权限。

资料权限变更会在与其角色、别名或所有权变更相同的交易中清除这些字段。解除链接会删除该行。恢复角色或链接无法恢复已退役的引用。现有的配置机器状态存储会在 operator.channelPolicy 下记录已激活的 gateway.roles 和 gateway.auth.identityScopes 策略快照。仅身份范围的所有者使用相同的引用契约;移除并恢复其已配置的范围无法使已退役的引用复活。在密钥激活锁下,任一策略的变更都会在发布精确的后继快照之前持久地退役现有引用。回滚使用相同操作并采用合并后的目标;发布失败会协调存活的活跃策略。不涉及代理模式变更。

启动和 Doctor 会添加这些可空列,但不会为旧行分配权限;未使用的资料表在首次使用前保持不存在。规范模式与资料所有者的延迟确保共享表和索引定义。两个已发布的模式标记通常都会推进到 19。在现有的旧更新器发布延迟期间,内容可以升级,而旧的已发布标记保持不变。在版本 19 发布之前,无法签发或恢复引用。

版本 18 的写入器无法保留吊销历史,因此即使新增列可空,这也是一个带版本的权限契约。它们的常规工作进程准入检查会在状态协调器下检查外部版本变更,并拒绝进一步写入,包括比其支持更新的延迟内容。旧读取器也会拒绝模式 19。升级前创建经过验证的、支持 WAL 的备份。降级需要在单独的状态目录中恢复匹配的升级前备份;切勿降低标记或删除权限列。恢复备份会丢失后续的吊销和回执,并且不会撤销外部效果;回滚前请使用兼容构建协调这些内容。

状态模式 18

模式 18 向 github_publication_session_lifecycles 和 github_repository_publication_requests 添加可空的 requester_authority_json TEXT 列。共享发布准入会在现有请求事务中记录其原始请求者、范围上限以及任何所需的插件授权身份和原始别名绑定 ID。该快照可跨越延迟和重启保留;它不会替代当前角色、授权、会话或执行权限检查。发布者选择、仓库路由、人工归属和回执保留均保持不变。

启动和 openclaw doctor --fix 会将这些列添加到现有表中,而不会重建或重写其行。历史值保持为 NULL:迁移不会从发布者、会话创建者或当前负责人推断请求者。未经验证的待处理请求不能开始新的效果。终态回执仍可读,并且观察已分派的 GitHub 结果不会授权另一项操作。未使用的发布表在正常首次写入前保持不存在,该写入会创建规范模式。

资料模式所有者会向现有 user_profile_emails 表添加可空的 binding_id TEXT,并在其自身事务中初始化缺失的 ID。每个邮箱到资料的绑定都有一个不透明 UUID。创建或实际所有权变更会开始新的绑定;同一所有者的刷新会保留它。移除并随后恢复别名无法恢复其原有 ID。发布快照仅保留这些原始 ID,不会复制邮箱地址或更新已接受的回执字节。初始化现有别名不会将缺失的权限回填到历史发布请求中。

发布列添加和版本事实在一个模式事务中提交;失败时会一起回滚。两个已发布标记通常都会推进到 18。现有的旧更新器发布延迟可以保留较早的已发布标记,同时记录已应用的内容版本 18。重新打开使用该内容版本,并且不会重复迁移。

旧读取器会精确验证这些可选表,因此单纯的可空列不会使这成为同版本添加。支持状态模式 17 或更早版本的构建会拒绝模式 18。升级前停止旧写入器并创建经过验证的、支持 WAL 的备份。回滚需要在单独的状态目录中使用匹配的构建和升级前备份,而不是降低版本标记或删除权限字段。保留较新的数据库,并在回滚前使用兼容构建协调已接受的 GitHub 效果:恢复备份会丢失后续的本地回执,并且不会撤销已推送的提交或拉取请求。

状态模式 17

模式 17 添加完整的已准备工作进程存储契约。worker_environments 中可空的 preparation_key、preparation_demand_at_ms、preparation_expires_at_ms 和 preparation_consumed_at_ms 列构成一个受约束的元组,用于一次性容量。单独的可空 last_activated_at_ms 列存储成功激活时间。就绪池准入会写入准备元组;消耗该容量并分配会话放置共享一个事务。成功的放置激活会在同一事务中记录其需求时间。消耗会跨越附加失败、放置退役和重新打开保留,而终态行保留未过期的需求和不确定的清理。迁移会将现有工作进程上的所有五个值保留为 NULL,并且不会从历史行推断需求、激活或未使用容量。

专用节点在首次使用的 node_worker_prepared_workspaces 表中注册固定的构建路径。该表记录精确的环境和已完成的 preparation_key、用于标识兼容项目/运行时内容的必需 cache_key,以及固定的 workspace 和 HOME 路径。独立的必需 source_manifest_ref 和 prepared_manifest_ref 摘要分别标识干净的 Git 基线和已完成的设置树。初始绑定会验证已完成的树;重放会保留已绑定会话的编辑。绑定只记录一次会话和所有者纪元。退役会保留该绑定直到机器拆除,因此退役路径不能被另一个会话认领。

注册会在其现有同步写事务中创建仅节点表。中止的注册会回滚该 DDL,后续尝试可以再次创建它。普通数据库打开和迁移不会创建该表。按代理的模式和原生伴随表保持不变;原生客户端可以继续验证和读取其在状态模式 17 下已有的自有表,而无需执行迁移。

启动和 openclaw doctor --fix 在打开 schema-15 或 schema-16 数据库时应用 prepared-worker 迁移。schema-16 数据库仅接收 prepared-worker 迁移。元组约束属于最后添加的列,因此迁移只扫描一次现有环境,并保留该表而不是重建它。租约、凭据、放置、推理轮次、未知附加数据和不确定的清理均保持完整。迁移事务中不会运行任何 provider 操作。

迁移内容及其版本事实一起提交;失败会回滚该次尝试中的所有数据库更改。两个已发布标记通常在该事务中推进到 17。当较旧的更新器仍拥有尾部账本读取时,现有的 版本发布延迟 会将已发布标记保留在较早版本,并单独记录已应用内容 17。重新打开不会重复该内容迁移。

升级前,请停止较旧的写入器并创建经过验证的、支持 WAL 的备份。支持状态模式 16 或更早版本的构建会拒绝已发布的模式 17。若要回滚,请使用兼容的构建完成云端清理,停止所有写入器,然后将升级前备份恢复到单独的状态目录。恢复不会保留该备份之后所做的更改。不要降低任一版本标记,也不要擦除已消耗的绑定。未解决的 provider 清理可能会持续产生费用,直到删除得到确认。

状态模式 16

模式 16 从 skill_workshop_proposals 中移除 workspace_dir 和 claim_released_time。它还从集合审查历史中移除 workspace_dir 和 idx_skill_workshop_collection_reviews_workspace_time,并添加 owner_agent_id 及其所有者/时间索引。提案行保持完整。某个集合审查已释放其认领的提案会变为 stale 并带有状态原因,因此它曾经创建的 skill 路径仍保持用户所有,Doctor 永远不会移动它。

上述同版本的提案退役会移除该迁移。schema-15 数据库会保留其旧版 Workshop 列,直到 Doctor 导出其待处理草稿并删除提案表。

Skill Workshop 的所有权现在是物理目录 <state-dir>/agents/<agentId>/agent/workshop-skills。启动和 openclaw doctor --fix 会在共享模式事务中删除已退役的列和索引。随后两者都会运行相同的迁移,将已应用的旧版 Workshop 创建操作重新定位到推断的所有者代理,并将符合条件的待处理创建操作重新指向目标。冲突和所有权不明确的情况会变为过期提案,并保持旧版目录不变。审查历史行在可能时映射到唯一的所有者代理;否则,模式迁移会将其作为缓存类状态丢弃。

如果数据库报告模式 16,但仍具有可识别的 schema-15 Workshop 列,更新预检会识别待处理迁移,Doctor 会在重建规范索引之前运行它。仅提案的旧版列以相同方式处理。修复会保留可归属的审查行和无关索引;无法识别的列集或对已退役列的依赖仍会拒绝并回滚事务。

仅 skill 的工作区重新定位使用现有的 migration_runs 和 migration_sources 表来保存移动前的目录标识、文件哈希和工作区证明时间戳。重新定位后,只有匹配的证明专用状态会被退役;设置状态、路径别名和较新的证明保持完整。中断的迁移会重用已保存的移动前事实,而不是从空目录推断它们。工作区重置会移除待处理的工作区范围回执。无需额外的模式版本或表。

状态模式 15

模式 15 从 current_conversation_bindings 中移除 target_agent_id 和 target_session_id。目标索引使用完整的 target_session_key,并保持非唯一:多个会话可能指向同一目标。这使得插件拥有的目标可以持久存在,而无需虚构一个 OpenClaw 代理所有者。通道/账户隔离、插件审批、绑定标识符、目标键、JSON 元数据、过期和分离行为均保持不变。

启动和 openclaw doctor --fix 会在现有独占写事务中运行迁移。它们仅移除两个投影并替换目标索引,同时保留所有其他行值。依赖的触发器、索引或失败的模式检查会回滚事务;迁移不会丢弃未知依赖以强制升级。列移除会重写绑定表,因此升级成本与其大小成正比。

升级前,请停止较旧的写入器并创建经过验证的、支持 WAL 的备份。支持共享状态模式 14 或更早版本的构建会拒绝已迁移的数据库。若要返回到较旧的构建,请将升级前备份恢复到单独的状态目录;不要降低版本标记或重建代理投影。有关通用恢复契约,请参阅 降级。

状态模式 13

模式 13 将 cron_jobs.job_json、cron_jobs.state_json 和 subagent_runs.payload_json 作为规范记录。物理列仅在需要生产查询、排序或仅运行时更新的地方保留。Cron 任务从 75 列缩减到 15 列,子代理运行从 59 列缩减到 6 列。迁移通过将其编码为 JSON null 来保留显式配置为未定义的失败目标字段;它还会在移除冗余投影之前,将旧版运行状态别名规范化到 state_json 中。

工作区证明合并到 workspace_setup_state。当旧数据库没有 workspace_path_aliases 表时,迁移会保留证明时间戳和生成的引导哈希。仅证明的工作区保留空路径,直到再次遇到该工作区。

共享状态单例 auth_profile_stores 和 auth_profile_state 移动到 config_machine_state 下的 authProfiles.store 和 authProfiles.state;每个代理的身份验证表保持不变。由于这些行包含凭据,已脱敏的 Git 备份会省略 authProfiles. 机器状态前缀。

状态模式 11

模式 11 移除 skill_lifecycle 和 skill_workshop_proposal_origin_runs 表。已归档技能的生命周期状态在升级期间被丢弃:之前归档的 Workshop 技能返回到活动集合,每周集合审查根据内容对其进行评判。源运行行是一个从未读取的投影;规范的提案来源保留在 skill_workshop_proposals.record_json 中。已记录的技能使用情况和集合审查状态会保留。

状态模式 9

当已注册的代理数据库位于该目录内时,模式 9 将 agent_databases.path 值存储为相对于状态目录的值。迁移期间,当该文件存在时,外部默认布局行会重新锚定到根内对应项。仅当同一代理已经持有其根内注册时才会删除,因为双重默认布局注册无法生成有效的合并会话列表。否则,绝对路径行会保留,因此真正的外部注册永远不会被删除。这使复制的状态目录保持自包含,同时不会丢弃受支持的外部数据库路径。

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