--- summary: "网关保存会话行和记录以及每个代理的磁盘路径的位置" read_when: - "调试网关实际使用的存储或转录文件" - "在网关主机上找到代理会话数据库或旧工件" title: "磁盘上的会话状态" --- ## 双层持久化 1. **会话行（每个代理 SQLite）** - key/value 映射 `sessionKey -> SessionEntry`。网关拥有的可变运行时状态。跟踪元数据：当前会话 ID、上次活动、切换、令牌计数器。 2. **转录事件（每个代理 SQLite）** - 仅附加、树形结构（条目具有 `id` + `parentId`）。存储对话、工具调用和压缩摘要；为未来的转弯重建模型上下文。压缩摘要和可用令牌测量保留在记录中，没有单独的检查点记录或快照副本。 受保护的记录会保留所选的存储密钥和会话窗口。诸如 `agent:main:global` 之类的合格标识可以附加到其现有的原始 `global` 行，而无需重命名它或创建另一行。如果两种拼写都已经存在，则 write 会拒绝不明确的选择；精确读取使两个存储的地址分开。这也适用于保留的历史窗口。 新的聊天回合使用合格的准入身份，同时保留所选的存储密钥和数据库。如果原始 `global` 或 `unknown` 行及其限定拼写将共享该标识，则聊天执行会拒绝不明确的选择，包括尚未创建原始行时。选择一个明确的会话；现有行和历史记录不会合并或重命名。已完成的发送重试仍会返回其记录的结果。只读历史记录和存储的父项、生成项和分叉引用保留其物理地址。输入持久性和排队输入清理与已承认的数据库保持绑定；替换其路径无法将运行传输到复制的数据库。 在受保护的转录读取和写入期间，即使历史主别名元数据命名另一个后缀，完全限定的密钥（例如 `agent::main`）仍保持字面标识。在恢复冷历史记录之前和追加之前，排队轮次会重新检查其选定的会话和生命周期，因此替换的选择无法恢复或写入后继的历史记录。这些检查不会重新设置会话行的密钥或更改数据库模式。 当配置的主别名更改时，Doctor 会保留这些合格的存储地址及其父级、派生和分叉引用。在默认代理被删除后，它仍然可以修复原始别名、经过交付验证的旧密钥以及存储在替换代理下的旧默认代理主密钥。请求别名继续遵循当前配置。 较旧的安装在代理 `sessions/` 目录下可能仍然有 `sessions.json` 文件。将这些文件视为遗留会话行迁移输入或显式离线维护目标。网关启动时不会导入它们。停止网关，备份其状态，并使用 `openclaw doctor --fix` 将旧行和转录历史记录导入到每个代理 SQLite 存储中。运行 `openclaw doctor --session-sqlite inspect --session-sqlite-all-agents`，然后按照 [Doctor 迁移顺序 ](/cli/doctor#session-sqlite-migration) 进行检查和验证。如果在存档旧转录本工件后迁移失败，请使用该序列中的 Doctor 恢复模式。恢复使用迁移清单，仅恢复受影响的存档支持工件，根据请求准备经过清理的 GitHub 问题报告，并且不会使活动运行时再次读取 JSONL 文件。 网关历史阅读器避免具体化整个记录，除非表面需要任意历史访问。首页历史记录、嵌入式聊天历史记录、重新启动恢复和 token/usage 检查使用来自 SQLite 的有界尾部读取。 磁盘支持的历史页面在专用的会话转录工作器中运行 SQLite 读取并显示准备情况。等效请求可以共享排队读取，直到工作线程开始执行；已完成的页面不会被缓存。网关应用当前配置文件显示并在发布之前重新检查会话身份和访问权限。冷恢复和投影重建仍由现有网关存储所有者负责。隐身历史记录保留在网关进程中，并且绑定的外部 CLI 导入保留其本地导入所有者。当没有提供限制时，HTTP 历史记录端点仍然返回完整的历史记录。 [ 提议的转录工作集设计](/reference/session-management-compaction/resident-history) 描述了实时 `SessionManager` 历史读取器的剩余迁移以及写入后执行居民预算之前所需的消费者合同。 ## 磁盘上的位置 每个 agent，在 Gateway 主机上（通过 `src/config/sessions.ts` 解析）： - 运行时会话行存储：`~/.openclaw/agents//agent/openclaw-agent.sqlite` - 运行时转录行：`~/.openclaw/agents//agent/openclaw-agent.sqlite` - Legacy/archive 转录工件：`~/.openclaw/agents//sessions/` - 旧版行迁移输入：`~/.openclaw/agents//sessions/sessions.json`