会话密钥、ids 和转录事件
会话键 (sessionKey)¶
一个 sessionKey 标识你所在的对话桶(路由与隔离)。规范规则: /concepts/session。
| 模式 | 示例 |
|---|---|
| 主/直接聊天(每个 agent) | agent:<agentId>:main |
| 群组 | agent:<agentId>:<channel>:group:<id> |
| 房间/频道(Discord/Slack) | agent:<agentId>:<channel>:channel:<id> 或 ...:room:<id> |
| Cron | cron:<job.id> |
| Webhook | hook:<uuid>(除非被覆盖) |
会话 ID (sessionId)¶
每个 sessionKey 指向当前的 sessionId(即延续对话的 SQLite 转录身份)。决策逻辑位于 src/auto-reply/reply/session.ts 的 initSessionState() 中。
- 网关重置(
/new、/reset)会在现有持久化 session 中记录一个重置边界,并保留其sessionId。尚不存在的 session 会获得一个新 id。 - 默认不自动重置。当前的
sessionId会继续,而压缩会保持活动模型上下文有界。 - 每日重置(
session.reset.mode: "daily")会在配置的本地小时边界(session.reset.atHour,默认4)之后的下一条消息时创建新的sessionId。 - 空闲过期(
session.reset.mode: "idle"配合session.reset.idleMinutes,或旧的session.idleMinutes)会在消息到达空闲窗口后创建新的sessionId。如果同时配置了每日和空闲重置,以先到期者为准。 - Control UI 重连恢复会为一次重连发送保留当前可见的 session,当 Gateway 从操作员 UI 客户端收到匹配的
sessionId时。这是一个一次性信号;普通的过期发送仍会创建新的sessionId。 - 系统事件(心跳、cron 唤醒、exec 通知、Gateway 簿记)可能会变更 session 行,但绝不延长每日/空闲重置的新鲜度。重置切换会在构建新提示之前,丢弃之前 session 中排队的系统事件通知。
- 自动父分支策略在创建线程或子 agent 分支时使用 OpenClaw 的活动分支。如果该分支过大(超过固定内部上限,目前为 100K tokens),OpenClaw 会以隔离上下文启动子级,而不是失败或继承不可用的历史记录。大小自动确定且不可配置;旧的
session.parentForkMaxTokens配置由openclaw doctor --fix移除。 - 操作员分支:
sessions.create { parentSessionKey, fork: true }从父级的当前状态分支。准入使用所选子模型的可用有效输入容量;当模型容量不可用时,回退到 100K 安全上限。当父级有活动运行时,普通分支会被拒绝;添加forkFrom: "last-completed"只复制最后一个已完成的助手消息之前的内容,排除进行中的尾部。与自动父分支不同,超过容量限制的操作员分支会被拒绝,而不是以隔离上下文接受。除非显式传入模型,否则子级继承父级的模型选择。响应会将其标记为forkedFromParent,token 计数器从零开始。 - 消息分支:
sessions.fork { sessionKey, entryId }从所选用户消息之前的活动路径前缀创建一个子级,并将该消息返回给编辑器进行编辑。父级保持不变。隐身分支保留父级的内存存储类别;重启 Gateway 会删除两个 session。Codex 分支验证会比较完整的、经证明的已提交提示(包括空白);有界的显示导入投影不能替代该证据。有关分支与回退操作,请参阅 Control UI。
会话存储架构¶
运行时存储将 SessionEntry 值保留在每个 agent 的 SQLite 中。值类型为 src/config/sessions.ts 中的 SessionEntry。关键字段(非详尽):
sessionId:当前转录 id,用于寻址 SQLite 转录行sessionStartedAt:当前sessionId的开始时间戳;每日重置新鲜度使用此字段。旧行可能从 JSONL session 头部推导该值。lastInteractionAt:最后真实用户/频道交互时间戳;空闲重置新鲜度使用此字段,因此心跳、cron 和 exec 事件不会让 session 保持存活。没有此字段的旧行会回退到恢复的 session 开始时间。updatedAt:最后存储行变更时间戳,用于列表/剪枝/簿记——不是每日/空闲重置新鲜度的权威来源。archivedAt:可选的归档时间戳。已归档 session 会保留在存储中,其转录完整,并从正常活动列表中排除。pinnedAt:可选的固定时间戳。活动的已固定 session 排在未固定 session 之前;归档 session 会清除其固定状态。- Codex 线程互操作:两个字段都遵循 Codex 线程管理形状——传输中的
archived/pinned布尔值始终从时间戳推导,并在服务端盖章,与 Codexthreads.archived_at语义和 camelCase 序列化匹配。OpenClaw 时间戳是自纪元起的毫秒数,而 Codex 使用自纪元起的秒数,因此桥接在codex插件接缝处转换。Codex 线程方法仅覆盖归档(thread/archive/thread/unarchive),且不包含固定方法,因此固定状态保留在 OpenClaw 侧。形状匹配,因此如果 Codex 有固定方法,绑定 session 就能机械地往返固定状态。 - Codex 监督列表只列出未归档的原生线程。对于 Gateway 本地、活动状态未知(
idle或notLoaded)的线程,只有在操作员明确确认没有其他 Codex 进程拥有它之后,才能通过原生thread/archive进行归档;插件首先执行一次新的进程本地状态读取,然后该线程从目录中消失。该读取无法证明另一个 App Server 进程未在使用该线程。OpenClaw 拒绝归档活动行和错误行,并且在节点桥接能够拥有完整的流式线程生命周期之前,配对节点归档不可用。在原生 Codex 客户端中取消归档会使线程再次有资格出现。 snoozedUntil/snoozedAt:可选的唤醒时间(自纪元起的毫秒数)和服务端盖章的休眠时间,仅存储在session_nodes.entry_json中。sessions.patch { snoozedUntil }接受未来的正整数或null来唤醒 session,且需要expectedSessionId。休眠会在不改变生命周期或工作准入的情况下,将符合条件的活动根 session 从 Control UI 的 Active 侧边栏中隐藏。行暴露时间戳;客户端将唤醒时间与自己的时钟比较,没有派生的snoozed布尔值或服务器计时器。过期字段可以保留,直到后续写入清除它们。用户/频道交互以及更新用户可见活动的已完成运行会清除两个字段;系统事件和保留状态运行会保留它们。休眠保留固定状态,而固定或归档会清除休眠。lastReadAt/markedUnreadAt:读取状态时间戳由sessions.patch { unread }在服务端盖章——unread: false记录一次读取(设置lastReadAt,清除markedUnreadAt);unread: true记录markedUnreadAt并将 session 标记为未读,直到下次激活或显式读取。Session 行会同时暴露标记和派生的unread布尔值,以便已打开的客户端保留手动提醒,同时仍然感知新活动。支持公告的未读确认合约的客户端发出的自动读取补丁包含expectedMarkedUnreadAt(null表示没有标记);较新的标记会使该确认成为成功的 no-op,而不是抹掉更新的意图。裸的unread: false请求保留旧的清除行为,因此在多个已连接客户端之间进行保护要求每个活动客户端都支持该合约。从未被标记为已读的 session 保持unread: false,因此现有安装在升级时不会显示未读标记。lastActivityAt:最后一次符合未读资格的活动(用户、频道和 cron 运行)的已完成 agent 运行的时间戳。心跳和内部事件轮次以及元数据补丁不会更新它;updatedAt不是活动信号。sessionFile:为迁移/归档兼容性保留的旧标记;活动运行时使用 SQLite 身份chatType:direct | group | roomlabel:显式自定义名称;始终优先,包括早期记录中标签看起来像自动设备名称的情况。使用sessions.patch { label: null }清除它会恢复自动命名。autoLabel:可选的自动设备标签,与自定义名称分离。Android 通过sessions.patch写入它;允许重复值,null会清除它。它是已保存的displayName之下的显示回退,而不是唯一的 session 标签。subject、groupChannel、space、displayName:群组/频道标签元数据;displayName还存储生成的对话标题。- 开关:
thinkingLevel、verboseLevel、reasoningLevel、elevatedLevel、sendPolicy(按 session 覆盖) - 模型选择:
providerOverride、modelOverride、authProfileOverride - Token 计数器(尽力而为/依赖 provider):
inputTokens、outputTokens、totalTokens、contextTokens compactionCount:此 session key 已完成的压缩总数memoryFlushAt/memoryFlushCompactionCount:上次压缩前内存刷新的时间戳和压缩计数
现有的仅含 label 的记录会被保留:Gateway 不会从已保存 label 的文本推断其是否为自动生成的。请显式清除或替换它,以更改其优先级。不支持 autoLabel 的旧版 Gateway 会拒绝该补丁字段;Android 不会将设备名称作为 label 重试,以免覆盖自定义名称。Android 仍会将本地已知的设备名称作为仅用于显示的备用名称,用于其自身会话,排在服务器提供的名称之下。此备用名称既不会发送到 Gateway,也不会存储在会话缓存中。
Gateway 是权威方:它可能会在会话运行期间重写或重新水合(rehydrate)条目。对于旧版基于文件的安装,请使用 openclaw doctor --session-sqlite import --session-sqlite-all-agents 进行迁移,而不要编辑 sessions.json 并期望运行时继续读取该文件。
转录事件结构¶
转录记录由 OpenClaw 会话访问器管理,并通过基于身份的辅助函数暴露给运行时代码。事件流是仅追加(append-only)的:
- 第一个条目:会话头部 ——
type: "session"、id、cwd、timestamp,以及可选的parentSession - 随后是:带
id+parentId的条目(树状结构)
值得注意的条目类型:
message:user/assistant/toolResult 消息custom_message:扩展注入的消息,_确实会_进入模型上下文(当display: true时在 TUI 中渲染,当display: false时完全隐藏)custom:扩展状态,_不会_进入模型上下文(用于在重载之间持久化扩展状态)compaction:持久化的压缩摘要,包含firstKeptEntryId和tokensBeforereset:新的历史窗口,可选地从firstKeptEntryId起保留消息branch_summary:在浏览树分支时持久化的摘要
历史读取器会在后续压缩中保留最新的重置窗口:显式保留的重置消息以及该重置之后的消息仍然可见,但更早的消息和压缩摘要不会重新出现。模型上下文则跟随最新的重置或压缩,因此压缩可以总结当前对话,而无需重新打开其更早的历史。
仅使用模型的调用方应等待(await)SessionManager.openModelContextAsync(target, { admission?, signal? }),以创建独立的、非持久化的视图,而不会在扫描持久化历史时阻塞 Gateway 事件循环。openModelContext() 为同步消费者提供相同的视图。读取器在 SQLite 中选择负载,并在模型窗口之外保留轻量级导航,而不会引入历史大小截断。仅存储用的原生 prompt 文本和工具结果详情不会出现在该视图中;镜像身份、发送者与媒体事实、工具内容以及有效的提供者重放状态仍然可用。原生 fork 验证、重放、导出以及 doctor 操作继续使用全保真证据读取器。
SessionManager.readSessionContext(target, read, { admission? }) 允许同步消费者在单个只读快照内处理全保真上下文消息。回调接收 (messages, header):一个惰性消息可迭代对象,以及未经验证的已存储头部。缺失的存储会提供空的可迭代对象,且不提供头部,也不会创建数据库。可选的 admission 会排除当前已接纳的用户行及之后的事件。回调错误会向上传播,迭代器在回调返回或抛出时关闭;该迭代器无法保留以供后续读取使用。这使得重放消费者可以在获取期间强制执行其现有限制,而不会静默丢弃更早的历史。导航仍随转录记录扩展,且单个选中的行会被整体解码;这不是固定的进程内存上限。
持久化的模型上下文读取在工作线程中运行。Codex 原生重放和已结算回合验证会将惰性读取及其消费者一起保留在工作线程中。工作线程读取按读取器串行化,并复用空闲的工作线程。Admission 收据在读取快照内部验证,并在接受结果之前再次验证;没有 admission 的读取则改为检查会话的重写代次和最后事件序号。已接纳的读取保留其回合边界,因此仅追加后续事件不会使其失效。失效的读取或已取消的信号会拒绝该结果。调用方在上下文获取期间携带其原始取消信号,并在调用钩子、启动模型运行或应用提议之前检查其所有者是否仍然处于活动状态。隐身(incognito)会话在 Gateway 进程中执行相同操作,因为其 SQLite 数据库保存在内存中。
OpenClaw 有意不“修复”转录记录;Gateway 使用 SessionManager 来读取/写入它们。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw