ClawCN - OpenClaw 中文版

主题

会话管理与压缩(深入探讨) ​

本文档解释了 OpenClaw 如何端到端管理会话:

  • 会话路由(入站消息如何映射到 sessionKey)
  • 会话存储(sessions.json)及其跟踪内容
  • 记录持久化(*.jsonl)及其结构
  • 记录清理(运行前特定提供商的修复)
  • 上下文限制(上下文窗口 vs 跟踪的令牌)
  • 压缩(手动 + 自动压缩)以及在何处挂钩压缩前工作
  • 静默清理(例如不应产生用户可见输出的内存写入)

如果您想先了解更高层次的概述,请从以下内容开始:

真实来源:网关 ​

OpenClaw 围绕单个网关进程设计,该进程拥有会话状态。

  • UI(macOS 应用程序、Web 控制 UI、TUI)应该查询网关以获取会话列表和令牌计数。
  • 在远程模式下,会话文件位于远程主机上;"检查本地 Mac 文件"不会反映网关正在使用的内容。

两个持久化层 ​

OpenClaw 在两个层中持久化会话:

  1. 会话存储(sessions.json)

    • 键/值映射:sessionKey -> SessionEntry
    • 小型、可变、安全编辑(或删除条目)
    • 跟踪会话元数据(当前会话 ID、最后活动、切换、令牌计数器等)

  2. 记录(<sessionId>.jsonl)

    • 具有树结构的仅追加记录(条目具有 id + parentId)
    • 存储实际对话 + 工具调用 + 压缩摘要
    • 用于为未来回合重建模型上下文

磁盘位置 ​

每个代理,在网关主机上:

  • 存储:~/.openclaw/agents/<agentId>/sessions/sessions.json
  • 记录:~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
    • Telegram 主题会话:.../<sessionId>-topic-<threadId>.jsonl

OpenClaw 通过 src/config/sessions.ts 解析这些。

会话键(sessionKey) ​

sessionKey 标识_您所在的对话桶_(路由 + 隔离)。

常见模式:

  • 主/直接聊天(每个代理):agent:<agentId>:<mainKey>(默认 main)
  • 群组:agent:<agentId>:<channel>:group:<id>
  • 房间/频道(Discord/Slack):agent:<agentId>:<channel>:channel:<id> 或 ...:room:<id>
  • Cron:cron:<job.id>
  • Webhook:hook:<uuid>(除非被覆盖)

规范规则记录在 /concepts/session。

会话 ID(sessionId) ​

每个 sessionKey 指向当前的 sessionId(继续对话的记录文件)。

经验法则:

  • 重置(/new、/reset)为该 sessionKey 创建新的 sessionId。
  • 每日重置(默认网关主机本地时间凌晨 4:00)在重置边界后的下一条消息上创建新的 sessionId。
  • 空闲过期(session.reset.idleMinutes 或旧版 session.idleMinutes)当消息在空闲窗口后到达时创建新的 sessionId。当同时配置每日 + 空闲时,先过期的优先。

实现细节:决策发生在 src/auto-reply/reply/session.ts 中的 initSessionState()。

会话存储架构(sessions.json) ​

存储的值类型是 src/config/sessions.ts 中的 SessionEntry。

关键字段(非详尽):

  • sessionId:当前记录 ID(除非设置了 sessionFile,否则文件名从此派生)
  • updatedAt:最后活动时间戳
  • sessionFile:可选的显式记录路径覆盖
  • chatType:direct | group | room(帮助 UI 和发送策略)
  • provider、subject、room、space、displayName:群组/频道标签的元数据
  • 切换:
    • thinkingLevel、verboseLevel、reasoningLevel、elevatedLevel
    • sendPolicy(每个会话覆盖)
  • 模型选择:
    • providerOverride、modelOverride、authProfileOverride
  • 令牌计数器(尽力而为/依赖于提供商):
    • inputTokens、outputTokens、totalTokens、contextTokens
  • compactionCount:此会话键完成自动压缩的频率
  • memoryFlushAt:上次压缩前内存刷新的时间戳
  • memoryFlushCompactionCount:上次刷新运行时的压缩计数

存储可以安全编辑,但网关是权威:它可能在会话运行时重写或重新生成条目。

记录结构(*.jsonl) ​

记录由 @mariozechner/pi-coding-agent 的 SessionManager 管理。

文件是 JSONL:

  • 第一行:会话头(type: "session",包括 id、cwd、timestamp、可选的 parentSession)
  • 然后:带有 id + parentId(树)的会话条目

显著的条目类型:

  • message:用户/助手/工具结果消息
  • custom_message:扩展注入的消息,_确实_进入模型上下文(可以从 UI 中隐藏)
  • custom:_不_进入模型上下文的扩展状态
  • compaction:带有 firstKeptEntryId 和 tokensBefore 的持久化压缩摘要
  • branch_summary:导航树分支时的持久化摘要

OpenClaw 故意不"修复"记录;网关使用 SessionManager 来读取/写入它们。

上下文窗口 vs 跟踪的令牌 ​

两个不同的概念很重要:

  1. 模型上下文窗口:每个模型的硬性上限(模型可见的令牌)
  2. 会话存储计数器:写入 sessions.json 的滚动统计(用于 /status 和仪表板)

如果您要调整限制:

  • 上下文窗口来自模型目录(可以通过配置覆盖)。
  • 存储中的 contextTokens 是运行时估计/报告值;不要将其视为严格保证。

更多信息,请参见 /token-use。

压缩:它是什么 ​

压缩将较旧的对话总结为记录中的持久化 compaction 条目,并保持最近的消息完整。

压缩后,未来回合会看到:

  • 压缩摘要
  • firstKeptEntryId 之后的消息

压缩是持久的(与会话修剪不同)。参见 /concepts/session-pruning。

自动压缩何时发生(Pi 运行时) ​

在嵌入式 Pi 代理中,自动压缩在两种情况下触发:

  1. 溢出恢复:模型返回上下文溢出错误 → 压缩 → 重试。
  2. 阈值维护:成功回合后,当:

contextTokens > contextWindow - reserveTokens

其中:

  • contextWindow 是模型的上下文窗口
  • reserveTokens 是为提示 + 下一个模型输出保留的余量

这些是 Pi 运行时语义(OpenClaw 使用事件,但 Pi 决定何时压缩)。

压缩设置(reserveTokens、keepRecentTokens) ​

Pi 的压缩设置位于 Pi 设置中:

json5
{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

OpenClaw 还为嵌入式运行强制执行安全下限:

  • 如果 compaction.reserveTokens < reserveTokensFloor,OpenClaw 会提高它。
  • 默认下限是 20000 个令牌。
  • 设置 agents.defaults.compaction.reserveTokensFloor: 0 以禁用下限。
  • 如果已经更高,OpenClaw 不会改动。

原因:为多回合"清理"(如内存写入)留出足够的余量,然后压缩变得不可避免。

实现:src/agents/pi-settings.ts 中的 ensurePiCompactionReserveTokens() (从 src/agents/pi-embedded-runner.ts 调用)。

用户可见界面 ​

您可以通过以下方式观察压缩和会话状态:

  • /status(在任何聊天会话中)
  • openclaw status(CLI)
  • openclaw sessions / sessions --json
  • 详细模式:🧹 Auto-compaction complete + 压缩计数

静默清理(NO_REPLY) ​

OpenClaw 支持后台任务的"静默"回合,其中用户不应看到中间输出。

约定:

  • 助手以 NO_REPLY 开始其输出,以指示"不要向用户传递回复"。
  • OpenClaw 在传递层剥离/抑制这一点。

从 2026.1.10 开始,当部分块以 NO_REPLY 开头时,OpenClaw 还会抑制草稿/键入流,因此静默操作不会在回合中泄漏部分输出。

压缩前"内存刷新"(已实现) ​

目标:在自动压缩发生之前,运行一个静默代理回合,将持久 状态写入磁盘(例如代理工作区中的 memory/YYYY-MM-DD.md),以便压缩不能 删除关键上下文。

OpenClaw 使用阈值前刷新方法:

  1. 监控会话上下文使用情况。
  2. 当它越过"软阈值"(低于 Pi 的压缩阈值)时,向代理运行静默 "立即写入内存"指令。
  3. 使用 NO_REPLY 以便用户看不到任何内容。

配置(agents.defaults.compaction.memoryFlush):

  • enabled(默认:true)
  • softThresholdTokens(默认:4000)
  • prompt(刷新回合的用户消息)
  • systemPrompt(为刷新回合追加的额外系统提示)

注意:

  • 默认提示/系统提示包含 NO_REPLY 提示以抑制传递。
  • 刷新每个压缩周期运行一次(在 sessions.json 中跟踪)。
  • 刷新仅针对嵌入式 Pi 会话运行(CLI 后端跳过它)。
  • 当会话工作区为只读时(workspaceAccess: "ro" 或 "none"),跳过刷新。
  • 参见 Memory 了解工作区文件布局和写入模式。

Pi 还在扩展 API 中公开了 session_before_compact 钩子,但 OpenClaw 的 刷新逻辑目前位于网关端。

故障排除清单 ​

  • 会话键错误?从 /concepts/session 开始,并确认 /status 中的 sessionKey。
  • 存储 vs 记录不匹配?从 openclaw status 确认网关主机和存储路径。
  • 压缩垃圾?检查:
    • 模型上下文窗口(太小)
    • 压缩设置(reserveTokens 对于模型窗口来说太高可能导致更早的压缩)
    • 工具结果膨胀:启用/调整会话修剪
  • 静默回合泄漏?确认回复以 NO_REPLY(精确令牌)开头,并且您使用的构建包含流抑制修复。