会话管理深入解析

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 会话路由（入站消息如何映射到 sessionKey）
• 会话存储（sessions.json）及其跟踪的内容
• 转录持久化（*.jsonl）及其结构
• 转录卫生（运行前的提供商特定修正）
• 上下文限制（上下文窗口与已跟踪 token）
• 压缩（手动压缩和自动压缩）以及预压缩工作应挂接的位置
• 静默内务处理（不应产生用户可见输出的记忆写入）

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

​

事实来源：Gateway 网关

• UI（macOS 应用、Web 控制 UI、TUI）应向 Gateway 网关查询会话列表和 token 计数。
• 在远程模式下，会话文件位于远程主机上；“检查你的本地 Mac 文件”无法反映 Gateway 网关正在使用的内容。

​

两个持久化层

1. 会话存储（sessions.json）
   • 键值映射：sessionKey -> SessionEntry
   • 小型、可变、可安全编辑（或删除条目）
   • 跟踪会话元数据（当前会话 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：warn（默认）或 enforce
• pruneAfter：陈旧条目的年龄截止值（默认 30d）
• maxEntries：限制 sessions.json 中的条目数（默认 500）
• resetArchiveRetention：*.reset.<timestamp> 转录归档的保留期（默认：与 pruneAfter 相同；false 会禁用清理）
• maxDiskBytes：可选的会话目录预算
• highWaterBytes：清理后的可选目标值（默认是 maxDiskBytes 的 80%）

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

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

​

Cron 会话和运行日志

• cron.sessionRetention（默认 24h）会从会话存储中修剪旧的隔离 cron 运行会话（false 会禁用）。
• cron.runLog.maxBytes + cron.runLog.keepLines 会修剪 ~/.openclaw/cron/runs/<jobId>.jsonl 文件（默认：2_000_000 字节和 2000 行）。

​

会话键（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>（除非被覆盖）

​

会话 ID（sessionId）

• 重置（/new、/reset）会为该 sessionKey 创建新的 sessionId。
• 每日重置（默认是 Gateway 网关主机本地时间凌晨 4:00）会在重置边界后的下一条消息到达时创建新的 sessionId。
• 空闲过期（session.reset.idleMinutes 或旧版 session.idleMinutes）会在空闲窗口之后有消息到达时创建新的 sessionId。当每日重置和空闲过期都配置时，先过期者生效。
• 系统事件（Heartbeat、cron 唤醒、exec 通知、Gateway 网关内务处理）可能会变更会话行，但不会延长每日/空闲重置的新鲜度。重置滚动会在构建新提示前丢弃前一个会话的排队系统事件通知。
• 父级派生策略在创建线程或子智能体派生时使用 PI 的活动分支。如果该分支过大，OpenClaw 会使用隔离上下文启动子级，而不是失败或继承不可用的历史。大小策略是自动的；旧版 session.parentForkMaxTokens 配置会被 openclaw doctor --fix 移除。

​

会话存储架构（sessions.json）

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

​

转录结构（*.jsonl）

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

• message：用户/助手/toolResult 消息
• custom_message：扩展注入的消息，_会_进入模型上下文（可从 UI 隐藏）
• custom：扩展状态，_不会_进入模型上下文
• compaction：带 firstKeptEntryId 和 tokensBefore 的持久化压缩摘要
• branch_summary：浏览树分支时持久化的摘要

​

上下文窗口与已跟踪 token

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

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

​

压缩：它是什么

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

​

压缩块边界和工具配对

• 如果按 token 占比拆分的位置落在工具调用与其结果之间，OpenClaw 会将边界移动到 assistant 工具调用消息，而不是拆开这一对。
• 如果尾随的工具结果块原本会让该块超出目标大小， OpenClaw 会保留该待处理工具块，并保持未摘要的尾部完整。
• 已中止/错误的工具调用块不会让待处理拆分保持打开。

​

自动压缩发生的时机（Pi 运行时）

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 以及类似的提供商形态变体) → 压缩 → 重试。
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 并保留 Pi 的近期尾部截断点。如果没有显式保留预算， 手动压缩仍是硬检查点，重建后的上下文会从 新摘要开始。
• 设置 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
• 详细模式：🧹 Auto-compaction complete + 压缩次数

​

静默内务处理（NO_REPLY）

• assistant 以精确的静默 token NO_REPLY / no_reply 开始其输出，以表示“不要向用户交付回复”。
• OpenClaw 会在交付层剥离/抑制它。
• 精确静默 token 抑制不区分大小写，因此当整个载荷只是静默 token 时，NO_REPLY 和 no_reply 都会计入。
• 这仅用于真正的后台/不交付轮次；它不是处理 普通可执行用户请求的捷径。

​

压缩前“记忆刷新”（已实现）

1. 监控会话上下文使用量。
2. 当它跨过一个“软阈值”（低于 Pi 的压缩阈值）时，向智能体运行一条静默的 “立即写入记忆”指令。
3. 使用精确的静默 token NO_REPLY / no_reply，这样用户不会看到 任何内容。

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

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

​

故障排除检查清单

• 会话键错误？从 /concepts/session 开始，并确认 /status 中的 sessionKey。
• 存储与转录不匹配？通过 openclaw status 确认 Gateway 网关主机和存储路径。
• 压缩刷屏？检查：
  • 模型上下文窗口（过小）
  • 压缩设置（reserveTokens 相对于模型窗口过高会导致更早压缩）
  • 工具结果膨胀：启用/调优会话修剪
• 静默轮次泄漏？确认回复以 NO_REPLY 开头（不区分大小写的精确 token），并且你使用的构建包含流式传输抑制修复。

​

相关

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