---
doc-schema-version: 1
summary: "哪个 SQLite 数据库包含什么内容，以及各个功能背后的表格"
read_when:
  - "在磁盘上定位全局状态数据库或每个代理数据库"
  - "检查哪个表支持更新分类帐或会议记录等功能"
title: "数据库布局"
---

## <a id="database-layout"></a> 数据库布局

| 范围                | 默认路径                                               | 内容                                                                                              |
| -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 全局控制平面 | `~/.openclaw/state/openclaw.sqlite`                        | 共享配置状态、注册表、审批、插件状态以及共享运行时状态             |
| 每代理数据平面 | `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite` | 会话、转录、记忆索引、认证状态、对话状态以及代理作用域内的运行时状态 |

### <a id="local-daemon-service-intent"></a> 本地守护进程服务意图

`<state-root>/control/services.sqlite` 是守护进程拥有的，SQLite- 仅存储在每个引擎上。其独立模式版本 1 包含 `daemon_runtime_pins`，由现有的哈希服务标识作为密钥，具有精确版本的 `value_json` 和 `updated_at_ms`。格式错误和过时的记录仍然是操作员的意图；检查会报告错误，而不是将它们视为未固定。单行 `daemon_runtime_pin_migration` 收据记录版本 1、源状态路径、`copied` 或 `complete` 及其更新时间。待处理的收据永远不会被取消固定。

Doctor 将遗留的 `daemon-runtime-pin:*` 行从共享的 `config_machine_state` 中转移到国家独家监管下。它在删除源行之前提交精确的本地副本，然后将收据标记为完成；相同的副本恢复中断的副本。 Install/start/repair 在读取意图之前在服务托管下执行此步骤。只读状态报告 `migrationPending` 以及下一步 `run openclaw doctor`。冲突的值或时间戳会停止迁移，同时保留两个存储。托管更新也针对 SQLite 安装运行此迁移。确切的更新程序恢复捕获包括本地存储。运行时读取永远不会回退到共享状态。

在 Windows 上，普通 drive/UNC 路径及其扩展长度 （`\\?\`） 拼写标识相同的共享状态数据库所有者。打开、写入准入、保留连接和清理使用相同的路径标识；本机 SQLite 打开仍然支持长文件名。这不需要架构或存储数据迁移，也不会更改更新备份或回滚。

共享状态数据库保留 `task_runs`、`task_delivery_state` 和 `flow_runs`，包括它们的现有列和索引。任务和 TaskFlow 运行时、工具和 UI 已删除；它们的非 Cron 行在运行时保持不变且未使用。 Cron 通过其历史记录仅拥有 `task_runs` 中的 `runtime = 'cron'` 行。它不会将历史记录移动到另一个表。本机执行和完成仍由子代理注册表和harness绑定所有者负责；本机 Codex 挂起分配使用现有父绑定中的元数据，而不是新表。运行时轨迹事件与其会话一起存在于每个代理数据库或配置的共享会话 SQLite 存储中。

在代理模式 23 中，`transcript_events` 将原始事件 JSON 保留为 `event_json` TEXT 或 `event_zstd` BLOB，并具有压缩行的字节计数和有界导航元数据。使用转录访问器或支持的导出来重建历史记录；单独选择 `event_json` 会忽略压缩事件。内存 chunk/cache 嵌入是小端 Float64 BLOB。请参阅 [ 紧凑型代理负载存储 ](/reference/database-schemas/agent-schema-history#compact-agent-payload-storage)。

PostgreSQL 将转录体以纯文本形式存储在 `event_json` 中，并使用本机 TOAST 压缩。 `event_zstd` 仅是 SQLite-，在 PostgreSQL 上仍然是 `NULL`。 SQLite-to-PostgreSQL 代理端口必须将保留的转录本正文解压到 `event_json` 中。

已停用的任务和 TaskFlow 功能记录仍然保留。 Codex 插件的 [Doctor 迁移](/gateway/doctor/config-migrations#native-codex-recovery-after-tasks-removal) 将符合条件的、带有所有者标记的本机子恢复事实复制到现有父绑定元数据中，同时使源任务行字节相同。这是仅迁移的读取，没有替换账本或运行时任务读取器。它们的历史 UI 和 API 被删除，而数据库布局保持不变。 6 月前退役的边车进口继续退役； [升级非常旧的版本](/install/updating#upgrading-very-old-versions)描述了桥接发布路径。在启动新网关之前，在直接二进制替换后运行当前的 Doctor。

### <a id="linux-database-page-cache"></a> Linux 数据库页缓存

准备就绪后，网关会对 Linux 文件缓存驻留情况进行采样，并每 15 分钟再次检查一次。该示例观察多达 256 个文件页面，但不读取其内容；它估计整个文件的驻留，而不是每个热查询的驻留。其他平台不运行此维护。采样需要对文件有有效的写权限；否则，Linux 可以将驻留屏蔽为完全缓存。被拒绝或不可用的样本会产生维护警告，而不是居住估计。

冷样本（低于 80%）或缓慢的有界会话投影读取通过独立的只读 SQLite 工作线程启动背景变暖。共享状态是按顺序读取的。代理预热最多读取 7 天内更新的 4,096 个会话预测及其历史元数据索引的有限范围。大于 256 KiB 的投影值将被跳过。在元数据之后，它会为 48 小时内更新的会话预热每个会话的最新 32 条活动消息，首先是最新的会话。有效负载读取使用八个批次，并跳过存储的 JSON 或高于 64 KiB 的压缩值；压缩消息不会被解码。不扫描冷快照值和较旧的转录本有效负载。每个有界查询在让出之前完成，因此调步不会保留 SQLite 读取事务。块之间的升温产量，目标为 16 MiB/s，并在 2 GiB 传递预算或每个数据库三分钟时停止。最终块可能会稍微超出字节预算。 shutdown取消并加入worker；没有页面映射或读取快照能够通过。

日志记录为`database page-cache residency`。启动诊断包括样本范围、进度、逻辑读取字节、磁盘字节、预热的有效负载字节和消息计数，以及预热之前和之后的有限投影查询计时。这些时序并不测量完整的 `chat.history` 请求。较旧的历史记录、超大消息和冷快照仍然可能需要磁盘读取。架构、存储的数据、配置或更新行为没有变化。

### <a id="session-reactions"></a> 会话反应

每个代理 `session_reactions` 表将反应行存储为持久记录消息的辅助数据。其密钥组合为`session_key`、`session_id`、`message_id`、`emoji`、`identity_id`；该行还记录可选的身份标签和创建时间。 `message_id` 是公开为 `__openclaw.id` 的转录事件标识。反应永远不会修改转录本有效负载。行与其会话节点级联，并读取选择转录会话 ID，因此来自先前重置实例的反应保持惰性。该表不是秘密存储。参见[同版本合约](/reference/database-schemas/versioning#versioning-contract)。

### <a id="session-run-outcomes-and-liveness"></a> 会话运行结果和活跃度

存储的会话条目的可选 `status` 仅存储 `done`、`failed`、`killed`、`timeout` 或 `interrupted`。开始运行会清除之前的结果。 `GatewaySessionRow.status` 还可能公开 `running` 或 `queued`，它们源自运行注册表和队列所有者，而不是持久会话元数据。存储工作人员从调度所有者处接收实时会话密钥，并在提交维护或冷存储更改之前重新验证保护。

重新启动和崩溃恢复使用现有的恢复声明、运行围栏、回复阶段和交付字段。符合条件的招生人员可以通过用户轮流写入来武装自己的主张，包括没有通道路由的轮流。仅中断的结果并不授权恢复或交付。请参阅 [ 重新启动恢复 ](/gateway/restart-recovery)。

在存储会话读取之前，医生和初创公司将遗留的持久 `running` 和 `queued` 条目一次性标准化为 `interrupted`；经过验证的遗留收益保留未设定的结果，因此其子延续保留所有权。符合条件的旧 `running` 条目如果缺乏索赔，则获得恢复保管权；现有的声明、记录和活动时间戳保持不变。这不会更改表或架构版本：现有的 SQL 状态索引仍将 `interrupted` 投影为 `failed`；存储的条目 JSON 保留不同的结果。较旧的版本仍然从其持久标记推断活动，因此在这些条目上重新打开时，它们无法提供新的活动或仅声明恢复行为。

### <a id="activity-session-recaps"></a> 活动回顾

[Activity](/web/control-ui/settings#activity-tab) 在现有 `session_nodes.entry_json` 会话元数据中存储一个可选的 `activitySummary` 对象。这是一个可重构的缓存；文字记录仍然是事实的来源。 [ 批准的持久性设计](https://github.com/openclaw/openclaw/issues/147383) 不添加 SQL 表、列或数据库架构版本更改。当前和 `v2026.9.4` 元数据序列化器保留未知的可选字段；未知的重述有效负载版本被视为缓存未命中。

由于 [agent 架构 24](/reference/database-schemas/agent-schema-history#session-hot-facts-and-snapshots)，`session_nodes.entry_json` 包含热门会话事实。单独键控的 `session_entry_snapshots` 行拥有差异基线、保存的技能和系统提示报告。精确读取器仅选择调用者需要的快照：元数据读取忽略所有三个，使用上下文读取系统提示报告，会话差异读取差异基线。选定的快照、条目元数据和生命周期事实保留在同一读取事务中。替换和初始化读取保留完整的条目，因此保存的快照可以在写回中保存下来。逻辑会话节点拥有它们的保留和删除；不需要迁移。

有效负载版本 1 记录了摘要文本、生成时间、会话 ID 和生命周期修订、转录本生成和叶、时间覆盖范围以及是否省略了超大消息内容。可选的 `formatRevision` 标识缓存格式。修订版2介绍了当前的散文（一到三个简洁的句子）；修订版 3 保留了该散文，并证明超大遗漏标志仅计算跳过的用户或助理消息，而不计算超大的工具结果（例如屏幕截图）。丢失或预修订 2 的记录保留其文本和覆盖范围，而现有队列通过模型调用刷新散文。除非有新消息到达，否则修订版 2 记录将在没有模型调用的情况下重新检查一次：当仅跳过工具结果时，陈旧的遗漏通知将被删除，而当早期的用户或助理消息确实被遗漏时，陈旧的遗漏通知将被保留。这不会增加 SQL 迁移或有效负载版本冲突。倒带或替换会使不兼容的源绑定无效。网关读取元数据写入之外的有界转录块，并在提交之前重新检查当前生命周期和转录分支。回顾写入保留会话活动时间戳和排序。

最新的回顾在重新启动和存档后仍然存在。删除会话会将其删除；重置或替换会使之前的生命周期回顾无法使用。隐身会话不会保留或生成此缓存。共享的、有界的网关队列可消除查看器之间的重复生成，保留先前的故障回顾，并仅使用配置的实用程序路由。禁用该路由会停止新一代。删除或忽略可选字段是一个回滚路径，可以使会话和转录数据保持完整；删除该功能不需要反转数据库迁移。

### <a id="user-turn-model-prompt-projections"></a> 用户转模型提示投影

存储的用户消息可以包括可选的私有字段`__openclaw.modelPromptProjection: { version: 1, text: string }`。用户轮流转录记录器在提供程序调度之前存储第一个面向模型的文本，包括提示挂钩 prepend/append 上下文或模型提示替换。普通的 `content` 仍然是原始的用户记录。投影文本在没有秘密掩码的情况下存储，并且在基于规则的时间戳和发送者标准化之前存储。第一次调度和重播都使用记录的文本，然后应用相同的标准化。

现有的记录编写器将捕获绑定到确切的活动用户消息，并在提交之前重新检查实时权限。捕获是不可变的：重复只能确认相同的文本。后续媒体无法更改发送的投影或将其复制到媒体的新用户消息中。压缩会废弃投影及其源消息，并且重置或替换无法将其转移到另一轮。没有添加单独的表、缓存、sidecar 或配置选项。

没有该字段的消息保留旧的重播行为。版本 1 阅读器在提供商调度之前拒绝格式错误或不受支持的投影格式，并要求兼容的 OpenClaw 版本或新会话。这种存储形状的添加使数字数据库模式版本保持不变。不理解可选字段的旧版本仍然可以读取原始用户内容，但无法重现记录的模型提示，并且可能会丢失提示缓存重用。因此，降级并不能保留重播保证；使用兼容版本恢复受影响的会话或启动新会话。

### <a id="transcript-search-row-ownership"></a> 转录搜索行所有权

在代理模式23中，`session_transcript_fts_rows`将每个FTS `rowid`映射到其会话和可为空的消息ID。 `id`为主键； `session_id`和`(session_id, message_id)`上的索引支持精确删除和协调。转录投影所有者使用其 FTS 行维护这些派生事实。迁移保留了 FTS 内容和 rowid，同时替换了 schema 22 的惰性映射和完整性计数器。有关迁移、恢复和降级行为，请参阅 [ 紧凑代理负载存储 ](/reference/database-schemas/agent-schema-history#compact-agent-payload-storage)。

### <a id="cold-transcript-archives"></a> 冷成绩单档案

每个代理 `session_transcript_cold_archives` 表与 `session_windows` 和 `transcript_events` 一起记录冷转录位置。每行都属于保留的会话窗口，并标识其生成、存档名称、散列、计数和大小。有效负载位于不可变的压缩 JSONL 文件中，或者当由受支持的备份嵌入时位于行的 blob 中。

默认存档目录为 `~/.openclaw/agents/<agentId>/sessions/cold/`，文件名为 `<sha256>.jsonl.zst`。名为 `agent` 的目录中的数据库使用其同级 `sessions/cold/` 目录；其他商店布局在数据库旁边使用 `cold/`。这些文件包含权威的历史记录。请参阅 [ 冷记录存储 ](/reference/session-management-compaction/maintenance#cold-transcript-storage) 了解保留和恢复，以及 [ 代理模式 20](/reference/database-schemas/agent-schema-history#cold-transcript-storage) 了解架构和更新合同。

### <a id="plugin-state-listing-index"></a> 插件状态列表索引

插件键控存储使用共享 `plugin_state_entries` 表。它的列表索引包括现有插件、命名空间、创建时间和条目键列之后的 `expires_at`，因此实时行计数可以读取索引而无需获取存储的值。配额、TTL 截止值、排序和行内容保持不变。

可写启动和 `openclaw doctor --fix` 通过所需索引修复替换了旧的四列定义，而没有架构版本冲突。修复构建临时索引并运行现有表和全文件完整性检查；允许额外的磁盘空间和与第一次修复期间存储的条目成比例的工作。

较旧的版本可以将相同的索引重建回其预期的定义。全模式只读验证会拒绝不匹配的定义，直到可写所有者修复它；仅验证数字模式版本的轻量级读取器可以读取任一形状。有关升级、反向修复和性能证明要求，请参阅 [ 已接受的索引设计](https://github.com/openclaw/openclaw/issues/142244)。

### <a id="mentions-inbox"></a> 提及收件箱

[ 提及 Inbox](/concepts/multi-user#temporary-mentions-inbox) 使用 `state/openclaw.sqlite` 中的现有 `config_machine_state` 行。 `notifications.mentions.source.*` 记录保留键入的源身份、收件人、提及标识符、到期时间和解雇簿记； `notifications.mentions.head` 记录修订和顺序。写入使用现有表和主键，没有新表、列、索引或架构版本更改。

自创建后保留 7 天，每个配置文件上限为 100 个条目，全局上限为 10,000 个条目，以及用于抑制重复的 10,000 个源身份。重新启动会保留保留的条目、解雇及其原始到期时间。加载存储的状态不会重播浏览器通知或扫描记录以重建旧的提及。

### <a id="acp-replay-accounting"></a> ACP 回放记账

共享的 `acp_replay_sessions` 和 `acp_replay_events` 表保留桥重播历史记录。它们的 `estimated_bytes` 列对每个持久文本字段的 UTF-8 字节进行计数，加上每行 32 个字节。会话总数包括他们的活动。这是保留内容的估计，而不是对 SQLite 文件、页面或 WAL 大小的限制。

旧版本对字符的计数不一致，低估了 Unicode，并允许未更改的元数据写入发生漂移。显式 Doctor 共享状态修复以原子方式重建所有派生总计，保留事件 JSON 文本、标识符、时间戳和序列。修复不会删除历史记录。下一个普通会话写入应用现有的上限和逐出顺序，因此更正的 Unicode 历史记录可能会更快地修剪并在加载时使用转录后备。

正常运行时打开和自动启动模式准备使现有会计列保持不变，包括在应用程序版本更改之后。如果支持的旧形状缺少会计列，添加它们也会在同一事务中初始化它们的总计。在更新维护期间运行 `openclaw doctor --fix` 以修复历史记帐。受支持的旧架构升级仍会执行在更改架构时保留数据所需的内容转换。会计修复无法恢复已被老作家驱逐的历史记录。参见 [ACP CLI](/cli/acp)。

### <a id="meeting-transcript-tables"></a> 会议记录表

会议捕获使用共享 `state/openclaw.sqlite` 数据库中的三个 `STRICT` 表，与每个座席的对话记录分开。转录本存储 （`src/transcripts/store.ts`） 通过共享状态工作线程路由读取和写入；流式导出使用只读工作线程。共享模式所有者定义表，并且 `src/transcripts/sqlite-schema.ts` 在确保它们时重用已承认的模式事实。成绩单目录下的 Markdown 和 JSON 文件是显式导出，而不是运行时存储。请参阅 [ 脚本 CLI](/cli/transcripts)。

#### `meeting_transcript_sessions`

每个捕获标识一行。主键为`(session_id, started_at)`； `selector` 是独一无二的。索引支持启动时间、会话 ID、slug、导出密钥、源身份、帐户和元数据代理查找。

| 专栏                                                                                                                 | 类型                                        | 用途                                                                 |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
| `session_id`, `started_at`                                                                                              | `TEXT NOT NULL`                             | 捕获 ID 和原始开始时间。                                     |
| `selector`, `export_key`, `session_slug`                                                                                | `TEXT NOT NULL`                             | 标准化选择器和派生导出标识。                        |
| `provider_id`, `source_json`                                                                                            | `TEXT NOT NULL`                             | 源提供者和定位器。                                            |
| `source_account_id`, `source_guild_id`, `source_channel_id`, `source_meeting_url`, `source_thread_ts`, `source_file_id` | 可空 `TEXT`                             | 字符串值源字段的查询投影。                       |
| `title`, `stopped_at`, `metadata_json`                                                                                  | 可空 `TEXT`                             | 显示标题、终端时间和会话元数据（包括所有权）。 |
| `metadata_agent_id`                                                                                                     | 可空 `TEXT`                             | 元数据的字符串值代理 ID 的查询投影。              |
| `export_manifest_json`                                                                                                  | `TEXT NOT NULL`，默认`{}`               | 导出工件所有权清单。                                     |
| `export_pending_json`                                                                                                   | `TEXT NOT NULL`，默认`[]`               | 待导出的工件。                                               |
| `next_utterance_seq`                                                                                                    | 非负`INTEGER NOT NULL`，默认`0` | 下一个附加序列。                                                   |
| `created_at_ms`, `updated_at_ms`                                                                                        | 非负 `INTEGER NOT NULL`              | 存储时间戳。                                                       |

重新打开占用驱动的捕获会清除 `stopped_at`，而不更改主键，因此同一会议保留其话语。新成绩单录取记录`sessionIdOrigin`（`generated`或`supplied`）在`metadata_json`中。以后写入同一主键时，存储会保留该值，包括旧行中该值的缺失或无效。重新开放占用需要明确生成的来源；未知来源开始了新的捕获，并完好无损地保留了旧记录。现有的最新候选查询和十分钟窗口保持不变。

这不会添加架构、索引、版本或回填。医生元数据恢复保留了明确记录的起源，并使未知的起源未知。较旧的运行时不强制执行此规则，因此降级还会删除固定的 ID 历史记录保护。参见[接受ID-原点判决](https://github.com/openclaw/openclaw/pull/130860)。

#### `meeting_transcript_utterances`

附加排序的语音记录。主键为`(session_id, session_started_at, sequence)`；会话对引用 `meeting_transcript_sessions(session_id, started_at)` 和 `ON DELETE CASCADE`。

| 专栏                                  | 类型                           | 用途                                          |
| ---------------------------------------- | ------------------------------ | ------------------------------------------------ |
| `session_id`, `session_started_at`       | `TEXT NOT NULL`                | 拥有捕获身份。                         |
| `sequence`                               | 非负 `INTEGER NOT NULL` | 捕获内稳定的附加顺序。          |
| `utterance_id`, `started_at`, `ended_at` | 可空 `TEXT`                | 提供者的话语身份和时间。          |
| `speaker_id`, `speaker_label`            | 可空 `TEXT`                | 提供说话者身份和显示标签。     |
| `text`                                   | `TEXT NOT NULL`                | 捕获的转录文本。                        |
| `final`                                  | 可为空 `INTEGER`、`0` 或 `1` | 提供者是否将话语标记为最终的。 |
| `metadata_json`                          | 可空 `TEXT`                | 提供者话语元数据。                     |

#### `meeting_transcript_summaries`

每次捕获一个当前摘要。主键为 `(session_id, session_started_at)`，并引用 `ON DELETE CASCADE` 的会话主键。 `summary_json` 或 `markdown` 中至少之一必须为非空。

| 专栏                            | 类型                           | 用途                                                                                                     |
| ---------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `session_id`, `session_started_at` | `TEXT NOT NULL`                | 拥有捕获身份。                                                                                    |
| `generated_at`                     | 可空 `TEXT`                | 摘要生成时间。                                                                                    |
| `summary_json`                     | 可空 `TEXT`                | 自由格式摘要，包括参与者、`source`（`model` 或 `heuristic`）和可选模型参考。 |
| `overview`                         | 可空 `TEXT`                | 摘要的字符串值概述的查询投影。                                                   |
| `markdown`                         | 可空 `TEXT`                | 呈现的会议记录。                                                                                     |
| `utterance_count`                  | 非负 `INTEGER NOT NULL` | 存储的摘要涵盖的话语数。                                                         |

源、元数据代理和概述投影已添加到 [ 状态模式 21](/reference/database-schemas/state-schema-history#state-schema-21) 中。作者将它们与规范的 JSON 一起维护；读者不会退回到 JSON 谓词。占用事件和模型支持的注释不会添加进一步的架构更改。

### <a id="update-run-ledger"></a> 更新运行账本

`update_runs` 每次更新都会在共享 `state/openclaw.sqlite` 数据库中存储一条持久记录。 `src/infra/update-run-ledger.ts` 拥有来自接纳网关、协调器 CLI 和重新启动的网关的写入。该表在共享模式版本 15 中是附加的：当前模式声明它，并且如果在同一写入事务中丢失，则首次使用会创建它。现有表和架构版本保持不变；老读者会忽略新表。

`run_id` 是 UUID 主键。行保留 creation/update 时间戳、触发器、阶段、状态、原因、来源、目标、before/after 版本、步骤、验证事实、修复尝试、confirmation/finish 时间戳和已知停机时间。每个 JSON 列都有 16 个 KiB 硬限制，并具有固定的截断规则和编辑。分类账存储有限的诊断摘要，而不是原始日志或凭证。没有自动历史记录删除。

考生准入在现有 `origin_json` 列中添加可选的 `origin.admission` 元数据：`owner`（`candidate` 或 `installed`）、可选的 `protocol`、`candidateVersion`、`checks` 和`fallbackReason`。读取公开与 `run.admission` 相同的元数据。 `origin.candidateAdmission` 在现有的编辑和字节限制内记录候选人的判决、理由、警告和事实。这些意见并不授予执行权。没有列、表或架构版本更改；较旧的记录可以省略它们。请参阅 [ 考生拥有的入场 ](/cli/update#candidate-owned-admission)。

异步历史查找、列表和状态投影在共享状态读取工作线程中运行查询并记录解码。它们保留源工件和继承的快照或一次性读取范围，重用保留的身份匹配的热源而不复制它，并返回空历史记录而不创建丢失的数据库或分类帐表。协调通过其异步查找和共享状态写入工作器操作保留选定的物理数据库。它的同步现有模式事务在终止之前重新检查行、恢复描述符和驱动程序活动性；在提交之前再次检查源托管和取消。轻量级修复还会重新检查该事务中较新的核心后历史记录。普通运行创建、进度和终端写入保留其当前的分类帐所有者。

新驱动程序将可选的 `origin.driver` 字段 `host`（主机名）、`pid` 和 `startIdentity`（操作系统的进程启动标识作为十进制字符串）存储在现有的 `origin_json` 列中。每个采用者都成为当前驱动程序，并在 `origin.previousDrivers` 中保留不同的早期身份。总共最多有八个身份。只有明确死亡的身份才会被修剪；拒绝收养，而不是丢弃正在运行的或无法检查的驱动程序。如果无法捕获本地进程身份，则继续采用并发出警告并保留 `driver:identity-unavailable` 步骤。即使已知的父母后来退出，该标记也会永久地将运行排除在自动调节之外；现有记录的身份仍然受到保护。没有身份的新运行遵循下面的旧显式 repair/supersession 规则。这是附加的 JSON 元数据；没有新的列、表或架构版本。单独的 `verification.pid` 仍然标识网关服务，而不是更新程序。采用记录保留的 `driver:adopted` 步骤。疏离的孩子可能比父母活得更久，因此任何一个人的寿命都可能阻碍和解。采用终端运行被拒绝。长命令和最终确定阶段每 30 秒更新一次 `updated_at_ms`；只有当前或保留的身份可以更新行。每次驱动程序运行时，心跳写入失败都会发出警告，并且不会中止命令或最终确定；步骤和结果写入保留其现有的失败行为。在限制和编辑其他源诊断之前，编码会为精确的身份字节保留空间。

账本具有废弃分类和终端化功能。自动恢复需要自 `updated_at_ms` 和最新步骤时间戳起超过 30 分钟，再加上每个记录的驱动程序在同一主机上已死亡的积极证据：其 PID 消失或其进程启动标识不同。无法读取的和外国主机的身份是不确定的。网关在启动时和主动运行轮询时执行协调，重新检查终端写入事务中的当前行和进程身份。共享的 30 分钟常量还拥有 [Schema 颠簸和旧更新程序 ](/reference/database-schemas/versioning#schema-bumps-and-older-updaters) 中描述的旧更新程序架构发布绑定。

调节写入状态 `failed`、原因 `abandoned` 以及保留的 `reconcile:abandoned` 步骤（其详细信息名称为 `inactive-driver-dead` 或 `operator-reconciled-inactive-run`）。所有未完成的步骤都将成为终点，并且历史记录将被保留。当当前网关一代运行正常并且没有待处理的核心后修复时，显式 `update repair` 可以协调不活动的无身份行。当每个记录的驱动程序确实已死亡并且不存在 `driver:identity-unavailable` 标记时，显式恢复不需要不活动窗口。它不能覆盖实时或不确定的记录驱动程序。 [2026.9.2 更新程序](https://github.com/openclaw/openclaw/blob/v2026.9.2/src/cli/update-cli/update-command.ts#L465) 不记录采用情况：程序包管理器和注册表预检可以在其单个 `requested/in_progress` 步骤中留下实时更新程序。较老的编写者可能会删除未知的驱动程序 JSON 字段；无标识行通常需要显式恢复。

未受影响的旧版准入将在超过 24 小时后自动过期：它仍然是 `requested` / `running`，具有相同的创建和更新时间戳，没有完成时间戳，没有记录的驱动程序，并且只有其初始 `requested` 步骤。账本将其保留为 `failed`，原因为 `legacy-driver-expired` 和 `reconcile:abandoned` 步骤。 Startup、`update status`、`status` 和 Control UI 的更新读取通过同一事务协调此形状。状态和故障报告说明更新从未取得进展，并建议 `openclaw update` 重试。即使更新完成后，Status 也会保留最新的此类建议。这个固定的遗留过期不会导致进程死亡。这是2026.9.2-era孤儿入学的有界恢复政策。较新的行、进步的行、记录的驱动程序和保留的恢复描述符保留其现有的保护。记录 `driver:identity-unavailable` 本身就是一种突变，因此采用无法与未受影响的承认相匹配。所有其他 `update status` 历史记录保持只读；现有的 30 分钟不活动窗口保持不变。网关更新读取还运行现有的自动失效驱动程序协调，因此 Control UI 准入使用与其启动观察程序相同的恢复决策。

仅当旧行是唯一正在运行的行、没有当前或先前的驱动程序标识并且超出相同的不活动限制时，显式新 CLI 更新准入才能取代旧行。该事务以 `failed` 的形式完成，原因为 `superseded` 和保留的 `reconcile:superseded` 步骤（其详细信息为 `operator-started-update-supersedes-inactive-identityless-run`），然后创建新行。这包括试运行入场，但不包括继承的延续和战役。 `abandoned`和`superseded`是现有自由文本原因合约中的附加值。两种恢复路径都不会删除历史记录。

成功的仅分类帐修复会记录保留的 `reconcile:acknowledged` 步骤。航站楼废弃排只能在完成时间后 30 分钟内替代全面维修一次；稍后的修复调用保持正常的插件收敛行为。 Repair 还会检查更新的 failed/abandoned 历史记录中是否有未确认的核心后工作，无论其年龄如何。较旧的活动行无法隐藏该工作。如果有界历史前缀未到达选定的恢复行，则修复将使用完全完成，而不是声称没有任何后核心工作剩余。当需要完全确定时，仅在成功收敛后、成功输出之前重新检查和协调所选的非活动行。显式恢复在一个事务中验证并提交其选定的行；任何选定运行中的更新活动都会保留整个选择。如果另一个活动运行不在该选择范围内，则仅分类账修复也会拒绝写入。最终确定 （`finalize:*`） 和更新后验证标记可以在步骤计数和诊断字节逐出中幸存下来，因为修复依赖于该历史记录。如果仅保留的元数据超出了硬限制，则写入会失败，而不会更改行。

这CLI和网关共享WAL-支持交易，包括在网关停止时。第一个最终结果获胜；后续验证可以丰富其观察到的事实，而无需重写成功、失败、跳过或回滚状态。中断完成有一个经过严格验证的例外：候选人记录其安装的版本和构建ID在保留的`finalize:installed-candidate`将核心后完成返回到已安装的更新程序之前的步骤。 Gateway watcher 和 Doctor 共享一个账本对账所有者，该所有者可以完成最近一次中断的验证或者更正其账本对账所有者。`abandoned`结果到`succeeded`只有在所有记录的驱动程序都已完全失效并且新安装的构建、服务构建、准备情况和生成检查一致之后。恢复描述符和记录的修复、故障或回滚证据会阻止纠正。事务在检查后重新检查完整的行和最新运行的身份，然后一起记录验证、结果和解释性警告。没有目标身份的旧行保持不变，Doctor 解释了缺失的证据。这使用现有的步骤和验证字段；架构和回滚读取器保持不变。显式的`update repair`可以将旧的包所有者拒绝错误分类纠正为`skipped`一旦安装的版本满足其解决的目标。此异常要求最新运行仅包含未更改的请求和可选的驱动程序采用元数据，没有恢复或活动更新。它保留拒绝详细信息和完成时间，并记录现有的确认标记；后续修复使用正常终结。重启哨兵携带`stats.runId`并仍然是延续所有者；使用它不会删除运行行。聊天，CLI，状态报告读取该行。看[运行历史记录和报告](/cli/update#run-history-and-reports)。

### <a id="update-installation-control"></a> 更新安装控制

托管更新租约使用安全 OpenClaw 临时目录下的单独计算机本地 `managed-update-handoffs.sqlite` 数据库。当更新替换安装或更改其运行时状态时，该所有者必须保持可用。上述更新历史记录保留在配置文件的共享状态数据库中。

第一次创建专门创建一个带有一个文件系统链接的私有文件。并发初始化程序使用同一文件而不替换它。 SQLite 以原子方式提交现有模式；当首次使用模式为空时，普通租赁检查报告没有租赁。读取不存在的数据库不会创建任何状态。现有的租赁行、索赔事务以及一个更新者拥有安装的规则均保持不变。

正常的切换父进程在启动其密封助手之前准备该数据库。帮助程序接收捕获的数据库标识，并仅对现有数据库进行操作，而不解析安装包或重新创建丢失或空状态。包恢复助手也是独立的：它们的状态和恢复命令不需要相邻的安装资产或服务控制器。

当前更新、医生和切换所有者在固定读取快照之前序列化协调器写入。他们准备现有目录功能并使用协调器的现有锁定文件，将剩余的五秒等待预算放入 SQLite 中。当写入者处于活动状态时，其他装置仍然可以检查其租约。在保存保护快照时，SQLite 准入保持非等待状态，因此它不会死锁写入者的提交或重播热日志。已经发布的同步助手保留了保守的 SQLite 拒绝；新的序列化不会更改其协议或租用行。当较旧的更新或 Doctor 持有 SQLite 时，当前调用者会解释争用并要求操作员等待其完成，然后重新运行命令。如果持有者在检查期间解除了锁定，则准入通过相同的目录功能和剩余预算重新观察缺席的插槽。仍然存在的替换 sidecar 或已更改的目录标识将被拒绝。

文件创建在 SQLite 打开文件之前应用私有权限，包括 Windows 上受保护的 ACL。初始化遵循现有的目录持久性策略，不需要可选的 fs 安全本机绑定。失败会在其操作运行之前停止租用许可。首次创建中断后，普通所有者可以通过其已有的空库恢复路径完成初始化；已提交的行仍受 SQLite 的正常事务管理。此更改不需要架构迁移。参见[接受的初始化设计](https://github.com/openclaw/openclaw/pull/144155)。

### <a id="managed-worktree-acceleration-templates"></a> 托管工作树加速模板

[托管工作树加速](/concepts/managed-worktrees#filesystem-acceleration)使用共享状态数据库中首次使用的`worktree_templates`表。每行记录一个可重构的源模板：存储库和 Git 公共目录、目标根目录、文件系统后端、工件路径、源提交、签出内容密钥、准备状态以及创建和上次使用时间戳。缓存键允许每个存储库和目标根目录有一个模板。该模板不包含已配置的忽略文件或存储库设置输出。

工作树服务在每个模板缓存键的突变租约下拥有模板创建、重用、失效和清理。它在创建工件之前保留 `preparing` 行，并仅在准备完成后发布 `ready`。持久的读者保留一代，而结账则独立克隆；当读者留下来时，清理和更换就会推迟。持久突变重新检查同步状态交易内的托管；文件系统工作在这些事务之外运行。清理使用保留模板 ID，因此旧操作无法删除其替换模板。当提交或签出策略更改时，模板将被替换，并在 7 天未使用后停用。

如果首次使用时缺失，则会创建附加表，并且不会更改数字数据库架构版本。现有的工作树和快照记录保留其含义；不会迁移或移动现有的结账。模板工件是可重构的，而注册的工作树内容和恢复快照保留其现有的保存规则。

### <a id="conversation-environments"></a> 对话环境

附加到对话的临时桌面和应用程序预览使用共享状态数据库中的 `worker_environment_session_attachments`。工作环境存储拥有这个附加伴随表。一行将精确的会话 ID 和生命周期修订绑定到一个环境，并具有附件生成、创建和最后使用时间戳以及可为空的关闭时间戳。环境行继续拥有配置、提供者租赁、传输身份、凭证和拆卸。执行放置保持独立。

分配意图和附件预留在配置之前一起提交。并发创建和重试会重用拥有的分配。 Stop 在等待远程清理之前关闭关系；清理失败会保留关系并阻止替换，直到确认旧租约已被销毁。会话重置或删除会使其失效，并且启动会在允许访问之前检查存储的会话具体化。配置的配置文件的 `suspendAfter` 使空闲附件过期；活动代理运行，桌面观察者使它们保持活动状态。提供商租赁生命周期限制继续适用。关闭侧边栏面板只会释放其查看器。终端附件行通过级联外键遵循环境所有者的 7 天保留期。

如果工作环境存储打开时缺少该表，则会创建该表，并且不会更改数字架构版本或现有放置列的含义。较旧的版本忽略这种关系并将这些机器显示为普通的未分配环境；他们不维护对话附件活动或清理。当连接的机器不应继续运行时，请在降级之前停止它们。现有的环境破坏和提供商生命周期限制仍然可用。重新升级会验证保留的会话身份并重试挂起的清理。数据库备份和回滚包括与现有共享状态数据库的伴随表；没有外部依恋状态需要重建。

### <a id="cloud-repository-workspaces"></a> Cloud 存储库工作区

仅存储库 [ 云会话](/gateway/cloud-workers#dispatching-a-session) 使用共享状态数据库中的首次使用 `session_repository_workspaces` 表。现有会话表项仅携带`repositoryWorkspaceId`；共享行拥有规范化的 agent/session 密钥、存储库 URL、请求的引用、会话分支、设置意图、固定的基本提交和清单、接受的检查点指针和修订。会话重置保留该所有者；叉子有一个独特的所有者。

`github_repository_publication_requests` 根据不可变的接受检查点和会话的接受生命周期修订来记录共享和个人发布。重置会保留会话 ID 和存储库检查点，但会使重置之前授权的发布无效。个人请求还保留选定的配置文件和连接生成，并在发布中断后需要同一所有者确认。即使在显式移动具体化网关工作树之后，待发布仍会保留其原始来源。

这两个表都是附加的，如果第一次使用时丢失，则创建，并保持数字数据库模式版本不变。这不是旧的云会话实现的兼容性承诺：在使用此状态时运行理解仅存储库会话的构建。现有本地托管工作树会话保留其现有表示。

Checkpoint Git 工件位于 `state/repository-workspaces/<workspace-id>.git` 下，位于共享数据库旁边。这些是包含完整文件清单、累积更改文件 blob 和发布快照的裸存储库；它们无法进行检查或上游 Git 历史记录的备份。恢复整个签出仍然需要访问固定的上游提交。将这些工件与共享数据库和每个代理数据库一起备份。

接受的检查点历史记录和发布源工件将保留到显式会话删除为止，包括停止、存档、重置或网关重新启动后。没有定时检查点到期。删除会在删除其工件存储库之前取消发布请求和源所有权；报告清理失败。托管工作树空闲清理和快照保留规则不适用于这些检查点。

## <a id="sandbox-runtime-reservations"></a> Sandbox运行时预留

现有的 `sandbox_registry_entries` 表拥有运行时标识和清理。选择保留的后端会在提供者分配之前保留一代。入口净荷保留原来的`workspaceDir`，并将`runtimeState`记录为`pending`、`ready`、`removing`或`removing-pending`；不添加架构版本、表或列。较旧的条目在首次使用时采用，后端毫无保留地保留其现有的注册表行为。工厂在重放和共享范围重用时接收保留的工作空间，而不是最新调用者的本地工作空间。因此，提供程序执行和存储库范围内的清理使用相同的原始所有者。

预留和发布使用同步 SQLite 事务。提供程序工作在共享数据库旁边的每个运行时文件锁下在事务外部运行。锁定竞争者最多等待 15 分钟，涵盖后端的预热和检查预算。并发创建者重用同一代。失败的配置保留其挂起的 ID 以便在重新启动后重播。在等待配置之前重新创建并修剪记录删除意图，然后在删除行之前删除提供程序运行时。清理失败会保留重试意图；过时的句柄在删除开始后无法发布准备情况或启动新操作。

`removing-pending` 保留了配置从未发布准备情况的事实。如果普通清理失败，Crabbox 适配器可以从其原始工作区重播相同的固定 ID，然后释放它。这也涵盖了 Crabbox 记录请求之前的故障：恢复可能会分配并立即释放保留的运行时。未知结果保留恢复行；缺少本地声明或错误消息并不能证明提供者资源不存在。

保留存储恢复状态。不要删除它来清除提供商错误。在降级到不支持预留的版本之前，请禁用后端并使用当前版本协调其挂起的租约。老读者可以打开数据库，但不实现此生命周期。

## <a id="package-publication-recovery-receipt"></a> 包裹-出版回收回执

仅包激活所有者在 `<installation-parent>/.openclaw.package-activation-<install-key-hash>.control/operation.sqlite` 中保留一项操作。这是现有的单槽 `package_activation` 表，而不是共享状态数据库。其列和数字模式版本保持不变。严格描述符记录原始执行者数据库身份、确切的 package/launcher 身份、移动前托管、帮助者身份和修订。控制目录还保存操作范围的 `recovery.mjs` 直至停用。一次性出版，附完整期刊及助手；一次性包目录是一个单独的同级目录。该描述符区分安装父级、控制目录和原始执行器数据库父级。

打开现有日志，无需创建或迁移。外部辅助布局在描述符中是明确的；遗留平面日志和目录内日志将被拒绝并保留在其原始恢复所有者手中。成功的退休将在目录和助手消失后保留一张有界完成收据。只有新的原始存储允许的操作才能替换该插槽。状态读取不会授予许可或执行清理。

## <a id="immutable-installation-preparation"></a> 不可变安装准备

不可变适配器使用相同的安装同级控制数据库路径，并使用一个 `immutable_installation` 行而不是包操作。已接受的 [ 不可变更新设计](/reference/team-immutable-update-design#detect-and-adopt-an-immutable-installation) 将显式采用与物理安装和当前一代、系统服务和帐户、state/config/profile、固定外部运行时和官方源绑定。其严格描述符记录采用状态：版本 1 记录仅准备采用，版本 2 记录显式启用的激活。修订和可选的准备生成收据记录验证准备。激活记录拥有指针发布、服务效果、验证、恢复等功能；仅仅准备工作并不能赋予这种权力。

最初的采用拒绝现有的包控制，而不是迁移或替换包日志。现有的包描述符和权限保持不变。不可变控件是 root 拥有的目录，模式为 `0755` 和 root 拥有的 `0644` 数据库：服务帐户可以读取这些非秘密事实，但只有更新程序可以写入。运行时观察使用现有的只读工作线程； CLI 采用和准备使用同步的修订检查事务，并在准入和提交时检查当前执行程序。现有的回滚日志持久性和目录同步所有者发布完整的采用记录。

准备好的收据只能在观察到的修订后更换；这不会删除其先前引用的树。运行时字节的回滚并不授权指针或状态更改。保留的恢复运行时消耗相同的严格控制记录，因此描述符升级必须保留其在新所有者写入该格式之前读取它的能力。

### <a id="immutable-release-retention-inventory"></a> 不可变的释放保留库存

释放-保留检查需要兼容的服务桥。该基础提供读取器和存储合约，但不会在其包清单中宣传版本 3 功能，因此单独安装它并不能启用检查。在综合建造、迁移和保留恢复合同使桥梁合格之前，仅使用合成桥梁固定装置进行检查。

描述符版本 3 可能包含此明确的、仅检查的策略：

```json
{
  "releaseRetention": {
    "version": 1,
    "mode": "inspect",
    "keepVerifiedGenerations": 3,
    "pins": []
  }
}
```

每个 pin 都是一个具有完整提交 `sha` 和记录目录 `identity` 的对象。计数记录了三个最近成功验证的本地代的预期保留，按所有者记录的验证修订排序；当当前一代拥有成功的验证证据时，它包括当前一代。未来的收集器还必须保护当前的、以前的、实时的、准备好的、期刊引用的、固定的和恢复运行时根；更改后的引脚标识不得解除其保护。该策略记录了未来的收集意图：`inspect`是唯一支持的模式，并且不删除发布目录。

安装的现有控制数据库拥有标准化库存：

```sql
CREATE TABLE immutable_release_generations (
  sha TEXT PRIMARY KEY NOT NULL,
  path TEXT NOT NULL,
  identity TEXT NOT NULL,
  build_digest TEXT NOT NULL,
  published_revision INTEGER NOT NULL,
  verified_revision INTEGER
) STRICT;
```

`path` 是规范包含的发布路径； `identity` 将其绑定到物理目录，`build_digest` 标识经过验证的密封版本。准备将所有权和 `published_revision` 记录在同一事务中作为更改的准备生成收据。成功激活会在完成验收的交易中为现有库存行记录 `verified_revision`。接受旧的准备生成不会回填所有权行。移动当前、以前或准备好的引用不会删除清单行。单独构建或密封的一代并不能建立成功的激活验证。

不可变的安装所有者承认该表并验证存储的路径、身份、摘要和修订顺序。没有文件名扫描或隐式回填：较早的和未知的目录保留在清单之外。备份和迁移快照保留在其现有恢复所有者手中，不会释放清单条目。

库存限制为 4,096 行，合并的控制记录和库存预测限制为 1 MiB。超过任一限制的写入都会回滚；它不会驱逐所有权证据或删除文物。状态包括策略和 `generations` 列表，其中包含用于检查的 `publishedRevision` 和可为空的 `verifiedRevision`。

现有的版本 1 和版本 2 描述符保持不变。未来的明确采用需要一个合格的桥，其安装的 `package.json` 声明 `openclaw.immutableInstallDescriptorVersion: 3`，并通过现有版本 2 所有者激活。在该桥接和任何恢复完成后，采用界面接受 `--inspect-release-retention` 以及 `--enable-activation --previous-updater-stopped` 和原始安装绑定。新的检查采用需要在已安装的当前一代上使用相同的标记。仅候选者的标记并不能限定已安装的运行时间。不要手动添加标记来启用该选项。

采用验证服务桥，拒绝挂起的操作，并在元数据接纳之前检查已安装的格式标记。它通过现有备份所有者仅升级已知的版本 2 独立启动器，在写入版本 3 描述符之前保留 `openclaw-gateway.v2`。安装的更新程序和保留的恢复运行时必须在编写版本 3 之前理解它。随后的准备、激活和恢复会在耗尽之前拒绝无支持的世代。状态和预览不采用策略或迁移控制数据库。该清单不支持收集、磁盘空间回收或主机维护删除。