磁盘上的 Session 状态

两种持久化层¶

1. 会话行（每个代理的 SQLite） - 键值映射 sessionKey -> SessionEntry。由 Gateway 拥有的可变运行时状态。跟踪元数据：当前会话 id、最后活动、开关、token 计数器。
2. 转录事件（每个代理的 SQLite） - 仅追加、树状结构（条目具有 id + parentId）。存储对话、工具调用和压缩摘要；为未来轮次重建模型上下文。压缩摘要和可用 token 测量值保留在转录中，没有单独的检查点记录或快照副本。

受保护的转录轮次保留所选存储键和会话窗口。诸如 agent:main:global 的限定标识可以追加到其现有原始 global 行，而无需重命名该行或创建另一行。如果两种拼写都已存在，写入会拒绝模糊选择；精确读取保持两个存储地址分离。这也适用于保留的历史窗口。

新的聊天轮次使用限定准入标识，同时保留所选存储键和数据库。如果原始 global 或 unknown 行及其限定拼写会共享该标识，聊天执行会拒绝模糊选择，包括原始行尚未创建时。选择一个无歧义的会话；现有行和历史不会被合并或重命名。已完成发送的重试仍会返回其记录的结果。只读历史以及存储的父级、派生和分叉引用保留其物理地址。输入持久化和排队输入清理仍绑定到已准入的数据库；替换其路径无法将运行转移到复制的数据库。

在受保护的转录读取和写入期间，完全限定键（如 agent:<agentId>:main）保持为字面标识，即使历史主别名元数据指定了另一个后缀。排队轮次在恢复冷历史之前和追加之前会重新检查其选定的会话和生命周期，因此被替换的选择无法恢复或写入后继者的历史。这些检查不会重新键控会话行或更改数据库架构。

Doctor 在配置的主别名更改时保留这些限定存储地址及其父级、派生和分叉引用。它仍然修复原始别名、交付已验证的旧版键，以及在默认代理被移除后存储在替代代理下的旧默认代理主键。请求别名继续遵循当前配置。

较旧的安装可能仍在代理 sessions/ 目录下有 sessions.json 文件。将这些文件视为旧版会话行迁移输入或显式离线维护目标。Gateway 启动不会导入它们。停止 Gateway，备份其状态，并使用 openclaw doctor --fix 将旧版行和转录历史导入每个代理的 SQLite 存储。运行 openclaw doctor --session-sqlite inspect --session-sqlite-all-agents，然后按照 Doctor 迁移序列 进行检查和验证。如果在旧版转录工件归档后迁移失败，请使用该序列中的 Doctor 恢复模式。恢复使用迁移清单，仅恢复受影响的已归档支持工件，在请求时准备脱敏的 GitHub 问题报告，并且不会让活动运行时再次读取 JSONL 文件。

Gateway 历史读取器避免物化整个转录，除非界面需要任意历史访问。首页历史、嵌入式聊天历史、重启恢复以及 token/用量检查使用来自 SQLite 的有界尾部读取。

基于磁盘的历史页面在专用的会话转录工作器中运行其 SQLite 读取和显示准备。等效请求可以共享一个排队读取，直到工作器执行开始；已完成的页面不会被缓存。Gateway 应用当前配置文件显示，并在发布前重新检查会话身份和访问权限。冷恢复和投影重建仍由现有 Gateway 存储所有者负责。隐身历史保留在 Gateway 进程中，绑定的外部 CLI 导入保留其本地导入所有者。当未提供限制时，HTTP 历史端点仍返回完整历史。

磁盘位置¶

每个代理，在 Gateway 主机上（通过 src/config/sessions.ts 解析）：

• 运行时会话行存储：~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• 运行时转录行：~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• 旧版/归档转录工件：~/.openclaw/agents/<agentId>/sessions/
• 旧版行迁移输入：~/.openclaw/agents/<agentId>/sessions/sessions.json