会话管理深度解析

• 会话路由（传入消息如何映射到 sessionKey）
• 会话存储（sessions.json）以及它记录的内容
• 转录持久化（*.jsonl）及其结构
• 转录清理（运行前针对特定 provider 的修复）
• 上下文限制（context window 与已跟踪 token）
• 压缩（手动和自动压缩）以及在哪里挂接预压缩工作
• 静默清理（不应产生用户可见输出的内存写入）

• 会话管理
• 压缩
• 内存概览
• 内存搜索
• 会话修剪
• 转录卫生

​

事实来源：Gateway

• UIs（macOS app、web Control UI、TUI）应向 Gateway 查询会话列表和 token 计数。
• 在远程模式下，会话文件位于远程主机上；“检查你本地的 Mac 文件”并不会反映 Gateway 正在使用的内容。

​

两层持久化

1. 会话存储（sessions.json）
   • 键值映射：sessionKey -> SessionEntry
   • 体积小、可变、可安全编辑（或删除条目）
   • 跟踪会话元数据（当前 session id、最后活动时间、开关、token 计数等）
2. 转录（<sessionId>.jsonl）
   • 追加写入式转录，具有树状结构（条目带有 id + parentId）
   • 存储实际对话 + 工具调用 + 压缩摘要
   • 用于为未来轮次重建模型上下文
   • 压缩检查点是压缩后继转录上的元数据。新的压缩不会再写入第二份 .checkpoint.*.jsonl 副本。

​

磁盘上的位置

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

​

存储维护与磁盘控制

• mode: enforce (默认) 或 warn
• pruneAfter: 过期条目的年龄截止时间（默认 30d）
• maxEntries: sessions.json 中条目上限（默认 500）
• resetArchiveRetention: *.reset.<timestamp> 转录归档的保留期（默认与 pruneAfter 相同；false 可禁用清理）
• maxDiskBytes: 可选的 sessions 目录预算
• highWaterBytes: 清理后的可选目标值（默认 maxDiskBytes 的 80%）

1. 先移除最旧的归档、孤立转录或孤立 trajectory 工件。
2. 如果仍高于目标值，则逐出最旧的会话条目及其转录/trajectory 文件。
3. 持续进行，直到使用量低于或等于 highWaterBytes。

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

​

Cron 会话与运行日志

• cron.sessionRetention (默认 24h) 会从会话存储中清理旧的隔离 cron 运行会话（false 可禁用）。
• cron.runLog.keepLines 会按 cron 作业清理保留的 SQLite 运行历史行（默认：2000）。cron.runLog.maxBytes 仍被接受，以兼容旧的文件式运行日志。

​

会话键（sessionKey）

• 主/直接聊天（每个 agent 一个）：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>（除非被覆盖）

​

会话 id（sessionId）

• Reset (/new, /reset) 会为该 sessionKey 创建一个新的 sessionId。
• Daily reset（默认在 gateway 主机本地时间凌晨 4:00）会在重置边界后的下一条消息时创建新的 sessionId。
• Idle expiry（session.reset.idleMinutes 或旧版 session.idleMinutes）会在消息于空闲窗口之后到达时创建新的 sessionId。当 daily 和 idle 同时配置时，哪个先过期就以哪个为准。
• System events（heartbeat、cron 唤醒、exec 通知、gateway 记账）可能会修改会话行，但不会延长 daily/idle reset 的新鲜度。重置轮换会在构建新提示词之前丢弃上一会话的排队系统事件通知。
• Parent fork policy 在创建线程或 subagent fork 时使用 OpenClaw 的活动分支。如果该分支过大，OpenClaw 会为子级启动隔离上下文，而不是失败或继承不可用的历史。分支大小策略是自动的；旧的 session.parentForkMaxTokens 配置已被 openclaw doctor --fix 移除。

​

会话存储 schema（sessions.json）

• sessionId：当前转录 id（除非设置了 sessionFile，否则文件名由此派生）
• sessionStartedAt：当前 sessionId 的开始时间戳；daily reset 新鲜度使用它。旧行可能从 JSONL 会话头部中推导出它。
• lastInteractionAt：最后一次真实用户/频道交互时间戳；idle reset 新鲜度使用它，因此 heartbeat、cron 和 exec 事件不会让会话 保持活跃。没有此字段的旧行会回退到恢复出的会话开始时间 来判断 idle 新鲜度。
• updatedAt：最后一次存储行修改时间戳，用于列表、清理和 记账。它不是 daily/idle reset 新鲜度的权威依据。
• sessionFile：可选的显式转录路径覆盖
• chatType：direct | group | room（帮助 UI 和发送策略）
• provider、subject、room、space、displayName：用于群组/频道标记的元数据
• 开关：
  • thinkingLevel、verboseLevel、reasoningLevel、elevatedLevel
  • sendPolicy（每会话覆盖）
• 模型选择：
  • providerOverride、modelOverride、authProfileOverride
• token 计数器（尽力而为 / 依赖 provider）：
  • inputTokens、outputTokens、totalTokens、contextTokens
• compactionCount：该 sessionKey 的自动压缩完成了多少次
• memoryFlushAt：上一次预压缩内存刷新时间戳
• memoryFlushCompactionCount：上一次刷新运行时的压缩计数

​

转录结构（*.jsonl）

• 第一行：会话头部（type: "session"，包含 id、cwd、timestamp、可选的 parentSession）
• 然后：带有 id + parentId 的会话条目（树状）

• message：用户/assistant/toolResult 消息
• custom_message：扩展注入的消息，这些消息 会 进入模型上下文（可以在 UI 中隐藏）
• custom：扩展状态，这些内容 不会 进入模型上下文
• compaction：持久化的压缩摘要，包含 firstKeptEntryId 和 tokensBefore
• branch_summary：在导航树分支时持久化的摘要

​

上下文窗口 vs 已跟踪 token

1. 模型上下文窗口：每个模型的硬上限（对模型可见的 token）
2. 会话存储计数器：写入 sessions.json 的滚动统计（用于 /status 和仪表盘）

• 上下文窗口来自模型目录（也可以通过配置覆盖）。
• 存储中的 contextTokens 是运行时估算/报告值；不要把它当作严格保证。

​

压缩：它是什么

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

​

压缩块边界与工具配对

• 如果按 token 占比分割的位置落在工具调用和其结果之间，OpenClaw 会将边界移到 assistant 的工具调用消息处，而不是把这对内容分开。
• 如果尾随的工具结果块本会把分块推过目标大小，OpenClaw 会保留该 待处理的工具块，并保持未总结的尾部完整。
• 被中止/出错的工具调用块不会使待处理分割继续保持开启。

​

When auto-compaction happens (OpenClaw runtime)

1. 溢出恢复：模型返回上下文溢出错误 (request_too_large, context length exceeded, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, ollama error: context length exceeded, 以及类似的 provider 变体) → 压缩 → 重试。 当 provider 报告尝试使用的 token 数时，OpenClaw 会将该观察到的计数传递到溢出恢复压缩中。如果 provider 确认了溢出但没有提供可解析的计数，OpenClaw 会向压缩引擎和诊断传递一个仅略微超出预算的合成计数。 如果溢出恢复仍然失败，OpenClaw 会向用户显示明确的指导，并保留当前会话映射，而不是静默地把 session key 轮换为一个新的 session id。下一步由操作员控制：重试该消息、运行 /compact，或者在需要新会话时运行 /new。
2. 阈值维护：在一次成功回合之后，当：

• contextWindow 是模型的上下文窗口
• reserveTokens 是为提示词 + 下一次模型输出预留的头部空间

​

压缩设置（reserveTokens、keepRecentTokens）

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

• 如果 compaction.reserveTokens < reserveTokensFloor，OpenClaw 会将其提升。
• 默认下限为 20000 个 token。
• 设置 agents.defaults.compaction.reserveTokensFloor: 0 可禁用该下限。
• 如果它本来就更高，OpenClaw 会保持不变。
• 手动 /compact 会遵循显式设置的 agents.defaults.compaction.keepRecentTokens 并保留 OpenClaw 运行时最近尾部的切点。若未显式设置保留预算， 手动压缩仍然是一个硬检查点，重建后的上下文将从新的摘要开始。
• 设置 agents.defaults.compaction.midTurnPrecheck.enabled: true 可在新工具结果到达后、 下一次模型调用前运行可选的工具循环预检查。 这只是一个触发条件；摘要生成仍然使用已配置的压缩路径。 它与 maxActiveTranscriptBytes 相互独立，后者是一个在轮次开始时对活动转录字节大小进行保护的检查。
• 将 agents.defaults.compaction.maxActiveTranscriptBytes 设置为字节值或 类似 "20mb" 的字符串，可以在活动转录变大时于轮次开始前执行本地压缩。 该保护仅在同时启用 truncateAfterCompaction 时生效。保留未设置或设为 0 可禁用。
• 启用 agents.defaults.compaction.truncateAfterCompaction 时， OpenClaw 会在压缩后将活动转录轮换为压缩后的后继 JSONL。 分支/恢复检查点操作会使用该压缩后的后继；在被引用期间，旧的压缩前检查点文件仍可读取。

​

可插拔压缩提供方

• provider：已注册压缩提供方插件的 id。若保留未设置，则使用默认的 LLM 摘要。
• 设置 provider 会强制 mode: "safeguard"。
• 提供方接收与内置路径相同的压缩指令和标识保留策略。
• safeguard 在提供方输出后仍然会保留最近轮次和分割轮次的后缀上下文。
• 内置的 safeguard 摘要会用新消息重新提炼先前摘要， 而不是逐字保留完整的前一个摘要。
• safeguard 模式默认启用摘要质量审计；设置 qualityGuard.enabled: false 可跳过对格式不良输出的重试行为。
• 如果提供方失败或返回空结果，OpenClaw 会自动回退到内置的 LLM 摘要。
• 中止/超时信号会被重新抛出（不会被吞掉），以尊重调用方取消。

​

用户可见的表面

• /status（在任意聊天会话中）
• openclaw status（CLI）
• openclaw sessions / sessions --json
• Gateway 日志（pnpm gateway:watch 或 openclaw logs --follow）：embedded run auto-compaction start + complete
• 详细模式：🧹 自动压缩完成 + 压缩计数

​

静默事务处理（NO_REPLY）

• 助手以精确的静默令牌 NO_REPLY / no_reply 开头输出，以表示“不要向用户发送回复”。
• OpenClaw 会在交付层中移除/抑制这一内容。
• 精确静默令牌的抑制是大小写不敏感的，因此 NO_REPLY 和 no_reply 在整个载荷仅为静默令牌时都算有效。
• 这仅适用于真正的后台/不交付轮次；它不是普通可操作用户请求的快捷方式。

​

预压缩“内存刷新”（已实现）

1. 监控会话上下文使用量。
2. 当它超过一个“软阈值”（低于 OpenClaw 运行时的压缩阈值）时，向 agent 运行一个静默的 “现在写入内存” 指令。
3. 使用精确的静默令牌 NO_REPLY / no_reply，这样用户就 不会看到任何内容。

• enabled（默认：true）
• model（可选的精确 provider/model 覆盖，用于刷新轮次，例如 ollama/qwen3:8b）
• softThresholdTokens（默认：4000）
• prompt（刷新轮次的用户消息）
• systemPrompt（为刷新轮次附加的额外系统提示）

• 默认的 prompt/system prompt 包含 NO_REPLY 提示，以抑制交付。
• 当设置了 model 时，刷新轮次会使用该模型，而不会继承 活动会话的回退链，因此本地仅处理的维护工作不会静默回退到付费对话模型。
• 刷新每个压缩周期运行一次（在 sessions.json 中跟踪）。
• 刷新仅针对嵌入式 OpenClaw 会话运行（CLI 后端会跳过）。
• 当会话工作区为只读（workspaceAccess: "ro" 或 "none"）时会跳过刷新。
• 有关工作区文件布局和写入模式，请参见 Memory。

​

故障排查清单

• Session key 不对？先查看 /concepts/session，并在 /status 中确认 sessionKey。
• 存储与转录不匹配？请确认 Gateway 主机以及 openclaw status 中的存储路径。
• 压缩过于频繁？检查：
  • 模型上下文窗口（太小）
  • 压缩设置（reserveTokens 对模型窗口来说可能过高，导致更早触发压缩）
  • 工具结果膨胀：启用/调整会话剪枝
• 静默轮次泄露？确认回复以 NO_REPLY 开头（大小写不敏感的精确令牌），并且你使用的是包含流式抑制修复的构建版本。

​

相关内容

• 会话管理
• 会话剪枝
• 上下文引擎