会话管理深度解析

Documentation Index

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

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

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

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

​

事实来源：Gateway 网关

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

​

两个持久化层

1. 会话存储（sessions.json）
   • 键/值映射：sessionKey -> SessionEntry
   • 小型、可变、可安全编辑（或删除条目）
   • 跟踪会话元数据（当前会话 id、最后活动时间、开关、令牌计数器等）
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 移除。

​

会话存储 schema（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
• 令牌计数器（尽力而为 / 取决于提供商）：
  • 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：导航树分支时持久化的摘要

​

上下文窗口与跟踪令牌

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

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

​

压缩：它是什么

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

​

压缩分块边界与工具配对

• 如果按 token 占比进行的拆分落在工具调用及其结果之间，OpenClaw 会将边界移动到助手工具调用消息处，而不是拆开这一对。
• 如果尾部工具结果块原本会让分块超过目标大小，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
• 详细模式：🧹 Auto-compaction complete + 压缩计数

​

静默内务处理（NO_REPLY）

• 助手以精确的静默 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"）时，会跳过刷新。
• 请参阅 Memory 了解工作区文件布局和写入模式。

​

故障排除清单

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

​

相关

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