跳到主要内容

压缩内部机制

会话管理深度解析

本文档详细解释 OpenClaw 如何端到端管理会话，涵盖以下内容：

  • 会话路由（入站消息如何映射到 sessionKey）
  • 会话存储（sessions.json）及其跟踪内容
  • 转录本持久化（*.jsonl）及其结构
  • 记录整理（运行前针对特定供应商的修复）
  • 上下文限制（上下文窗口与跟踪的令牌数）
  • 压缩（手动 + 自动压缩）以及在哪里挂钩压缩前工作
  • 静默后台维护（如不应产生用户可见输出的内存写入）

如果你想先了解高层次的概述，请从以下开始：

事实来源：网关​

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

  • 各类 UI（macOS 应用、网页控制 UI、TUI）应向网关查询会话列表和令牌计数。
  • 在远程模式下，会话文件位于远程主机上；"检查本地 Mac 文件"无法反映网关正在使用的实际内容。

两个持久化层​

OpenClaw 在两个层面持久化会话：

  1. 会话存储（sessions.json）
    • 键/值映射：sessionKey -> SessionEntry
    • 体积小、可变、可安全编辑（或删除条目）
    • 跟踪会话元数据（当前会话 ID、最后活动时间、开关状态、令牌计数器等）
  2. 转录本（.jsonl）
    • 具有树状结构的仅追加转录本（条目包含 id + parentId）
    • 存储实际的对话 + 工具调用 + 压缩摘要
    • 用于为后续轮次重建模型上下文

磁盘存储位置​

每个智能体，在网关主机上的路径：

  • 存储：~/.openclaw/agents//sessions/sessions.json
  • 转录本：~/.openclaw/agents//sessions/.jsonl
    • Telegram 话题会话：.../-topic-.jsonl

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

存储维护和磁盘控制​

会话持久化具有针对 sessions.json 和转录本文件的自动维护控制（session.maintenance）：

  • mode：warn（默认）或 enforce
  • pruneAfter：陈旧条目的保留期限（默认 30d）
  • maxEntries：sessions.json 中的条目上限（默认 500）
  • rotateBytes：当 sessions.json 过大时进行轮换（默认 10mb）
  • resetArchiveRetention：*.reset. 转录本归档的保留时间（默认：与 pruneAfter 相同；false 禁用清理）
  • maxDiskBytes：可选的会话目录磁盘预算
  • highWaterBytes：清理后的目标使用量（默认为 maxDiskBytes 的 80%）

磁盘预算清理的执行顺序（mode: "enforce"）：

  1. 首先删除最旧的归档或孤立的转录本文件。
  2. 如果仍高于目标，则逐出最旧的会话条目及其转录本文件。
  3. 持续清理，直到使用量达到或低于 highWaterBytes。

在 mode: "warn" 下，OpenClaw 只报告潜在的逐出操作，不会修改存储/文件。按需运行维护：

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

定时任务会话和运行日志​

独立的定时任务运行也会创建会话条目/转录本，它们有专门的保留控制：

  • cron.sessionRetention（默认 24h）从会话存储中清理旧的独立定时任务运行会话（false 禁用）。
  • cron.runLog.maxBytes + cron.runLog.keepLines 清理 ~/.openclaw/cron/runs/.jsonl 文件（默认值：2_000_000 字节和 2000 行）。

会话键（sessionKey）​

sessionKey 标识你所在的对话桶（用于路由和隔离）。常见模式：

  • 主/直接聊天（每个智能体）：agent::（默认 main）
  • 群组：agent:::group:
  • 房间/频道（Discord/Slack）：agent:::channel: 或 ...:room:
  • 定时任务：cron:<job.id>
  • Webhook：hook:（除非被覆盖）

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

会话 ID（sessionId）​

每个 sessionKey 指向一个当前的 sessionId（即继续对话的转录本文件）。规则概要：

  • 重置（/new、/reset）为该 sessionKey 创建新的 sessionId。
  • 每日重置（默认在网关主机本地时间凌晨 4:00）在重置边界后的下一条消息处创建新的 sessionId。
  • 空闲过期（session.reset.idleMinutes 或旧版 session.idleMinutes）在消息在空闲窗口后到达时创建新的 sessionId。当每日和空闲都配置时，先过期的生效。
  • 线程父分支防护（session.parentForkMaxTokens，默认 100000）在父会话已经太大时跳过父转录本分支；新线程从头开始。设置为 0 可禁用。

实现细节：该决策发生在 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：用户/助手/toolResult 消息
  • custom_message：扩展注入的、会进入模型上下文的消息（可从 UI 隐藏）
  • custom：不进入模型上下文的扩展状态
  • compaction：持久化的压缩摘要，包含 firstKeptEntryId 和 tokensBefore
  • branch_summary：导航树分支时持久化的摘要

OpenClaw 有意不"修复"转录本；网关使用 SessionManager 来读取/写入它们。

上下文窗口与跟踪的令牌数​

这里有两个不同的概念：

  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 设置中：

{
  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"）。
  • 有关工作区文件布局和写入模式，请参阅记忆。

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

故障排除清单​

  • 会话键错误？从 /concepts/session 开始，并确认 /status 中的 sessionKey。
  • 存储与转录本不匹配？确认网关主机和 openclaw status 中的存储路径。
  • 压缩频繁发生？检查：
    • 模型上下文窗口（太小）
    • 压缩设置（reserveTokens 相对于模型窗口过高可能导致较早压缩）
    • 工具结果膨胀：启用/调整会话修剪
  • 静默轮次泄露？确认回复以 NO_REPLY（确切令牌）开头，并且你使用的版本包含流抑制修复。

Node.js设置