OpenClaw 如何理解并调整会话压缩 Compaction，让长对话不超上下文？

OpenClaw 如何理解并调整会话压缩 Compaction，让长对话不超上下文？

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

每个模型都有上下文窗口（context window），即一次能处理的最大 token 数。长对话不断累积消息和工具输出，迟早会撞上这个上限。OpenClaw 的解决办法是Compaction（会话压缩）：把较早的对话轮次总结成一条摘要，写回会话 transcript，只保留近期消息原文，让对话可以继续而不超出模型的上下文限制。

这篇文章面向正在使用 OpenClaw 的开发者，讲清楚三件事：压缩实际做了什么、怎么确认它发生了、以及如何通过openclaw.json里的agents.defaults.compaction配置和/compact等命令调整它的行为。

Compaction 到底做了什么

按 Compaction 文档 的说明，压缩分三步：

1. 较早的对话轮次被总结成一条紧凑的摘要条目（compactionentry，持久化在 transcript 中，记录firstKeptEntryId和tokensBefore）；
2. 摘要保存在 session transcript；
3. 近期消息保持原样。

几个关键事实，直接影响你对压缩结果的预期：

• 完整历史仍在磁盘上。压缩只改变模型下一轮看到的内容，不改写原始记录。
• 工具调用成对保留：选择切分点时，OpenClaw 会把 assistant 的工具调用与对应的toolResult放在一起；如果切分点落在工具块中间，会移动边界而不是拆开配对。
• 默认模式：新配置的agents.defaults.compaction.mode默认为"safeguard"（更严格的护栏 + 摘要质量审计）；想回到旧行为需显式设置mode: "default"。
• safeguard 质量审计：保留的摘要正文必须包含要求的标题，待处理的问题和精确标识符必须保留在将要写入的摘要文本中；不合格时只做配置允许次数的纠正尝试，若始终不通过，压缩在写入前停止，原始历史保留不变。
• 内置 summarizer 只接收文本，不接收图片像素；被省略的图片会以[image data omitted from summary input]之类的标记表示，不会谎称模型处理过这些数据。

自动压缩默认开启。它的三条触发路径见 Session management deep dive：

1. 溢出恢复：模型返回 context-overflow 错误（如request_too_large、context length exceeded、input is too long for the model、ollama error: context length exceeded等各 provider 变体）时，先压缩再重试。如果恢复仍失败，OpenClaw 会保留当前会话映射并给出明确指引——重试消息、执行/compact或/new。
2. 基于用量的维护：内置运行时在推理前检查投影用量，达到模型窗口减去压缩保留量的阈值时先做 memory checkpointing，再做压缩。
3. 会话内阈值维护：default模式会话的实际上下文用量超过窗口减去保留量时触发；safeguard模式禁用这条竞争路径，把主动调度交给上面的维护路径。

保留量（reserve）的规则：80,000 token 及以上窗口默认保留 20,000 token；更小的窗口至少保留四分之三容量给提示和对话，reserve 为压缩摘要和 memory flush 等杂务留空间。文档给了一个 32,768-token 窗口的文档示例：使用 8,192-token reserve 和 4,000-token 软边距，约 20,576 投影 token 时开始提前 memory flush，24,576 起触发阻塞式压缩。

怎么确认压缩发生了

压缩默认静默执行。确认它是否发生、发生了多少次，有这几个观察面（来自 Session management deep dive 的 "User-visible surfaces"）：

• 聊天中发送/status，会显示🧹 Compactions: <count>；
• CLI：openclaw status、openclaw sessions或openclaw sessions --json；
• Gateway 日志（openclaw logs --follow）中出现embedded run auto-compaction start和complete；
• verbose 模式下看到🧹 Auto-compaction complete。

openclaw status openclaw sessions --agent main --json openclaw logs --follow

注意 token usage 文档 的提醒：/status里的上下文用量是运行时估计值，计费统计与当前上下文窗口是分开维护的，不要把contextTokens当作严格保证。

手动触发压缩

聊天内：/compact

在任意聊天中输入/compact强制压缩一次，可以带指令引导摘要重点：

/compact Focus on the API design decisions

手动压缩的切分预算同样由agents.defaults.compaction.keepRecentTokens（默认 20,000 token）决定，该预算内的近期尾部会原样保留。

两个容易踩的坑：

• openclaw agent --message '/compact ...'不是压缩路径——CLI 传入的斜杠命令会被 authorized-sender 检查拒绝，命令非零退出并指路到openclaw sessions compact。
• 外部渠道上，未被授权的发送者执行/compact会得到授权拒绝回复。

CLI：openclaw sessions compact

针对卡住或超大的会话，Sessions CLI 文档 提供了一等封装，要求 Gateway 正在运行：

openclaw sessions compact "agent:main:main" openclaw sessions compact "agent:main:main" --max-lines 200 openclaw sessions compact "agent:work:main" --agent work --json

• 不带--max-lines时，Gateway 用 LLM 总结 transcript（走配置的压缩生命周期，CLI 默认不设客户端超时）。
• 带--max-lines <n>是另一回事：它把 SQLite transcript 永久截断到最后 n 行，不生成备份归档。对卡死会话可用，但属于不可逆操作，先用/status和openclaw sessions确认会话 key 无误。
• Gateway 报告压缩失败或不可达时命令非零退出，方便脚本判断。

不带--max-lines的成功响应（文档示例）：

{ "ok": true, "key": "agent:main:main", "compacted": true, "result": { "tokensBefore": 243868, "tokensAfter": 34941 } }

其中tokensBefore/tokensAfter只是文档中的示例数值，不要当成固定预期。

调整压缩行为

所有压缩配置位于~/.openclaw/openclaw.json的agents.defaults.compaction下。完整字段参考见 Agent heartbeat、compaction 与流式配置，最常用的几个开关如下。

换一个小模型专门做摘要

压缩默认使用当前会话模型。用compaction.model可以指定另一个总结模型，接受provider/model-id字符串或agents.defaults.models下配置的裸别名（裸值同时匹配别名和字面模型 ID 时，字面 ID 优先）。适合主对话用大模型、摘要用本地小模型的场景：

{ "agents": { "defaults": { "compaction": { "model": "ollama/llama3.1:8b" } } } }

未设置时压缩使用会话主模型；若总结遇到可 fallback 的 provider 错误，会沿会话既有的模型 fallback 链重试，但这个选择是临时的，不会写回会话状态。显式设置了compaction.model后则精确命中该模型，不继承 fallback 链。

保留更多近期上下文

keepRecentTokens（默认20000）是"原样保留的最近 transcript 尾部"的切分预算；recentTurnsPreserve（默认3）是 safeguard 总结之外原样保留的最近 user/assistant 轮数。压缩后觉得上下文变"旧"，调大前者能让摘要覆盖得更靠后、原文留得更多。

用字节阈值提前触发

maxActiveTranscriptBytes用于长时会话：模型上下文可能还健康，但持久化的 transcript 历史一直在增长。设为正数字节数或"20mb"之类的字符串后，transcript 窗口（自最近一次压缩或 reset 以来的部分）达到阈值就在一轮运行开始前触发常规语义压缩；0或不设置则关闭。它不直接切字节，而是让正常压缩管线生成摘要。

{ "agents": { "defaults": { "compaction": { "maxActiveTranscriptBytes": "20mb" } } } }

工具循环中途的上下文压力

midTurnPrecheck.enabled: true（默认关闭）加一道工具循环护栏：每次工具结果追加后、下一次模型调用前，用与轮次开始相同的预算逻辑估算提示压力。上下文放不下时它不会就地压缩，而是发出结构化的 mid-turn 信号、停止当前提交，让外层循环走既有恢复路径——够用的话截断超大工具结果，否则触发配置的压缩模式并重试。default和safeguard模式都支持。

让压缩可见、让 memory flush 走本地模型

notifyUser: true（默认 false）会在压缩开始、完成、以及 memory flush 耗尽时发送简短状态消息（如 "Compacting context..."）。默认行为是静默的。

压缩前 OpenClaw 会运行一个静默 memory flush 轮次，把持久笔记写到磁盘（如工作区的memory/YYYY-MM-DD.md），防止压缩抹掉关键上下文。它由memoryFlush子块控制：enabled默认 true，softThresholdTokens默认 4000，forceFlushTranscriptBytes默认"2mb"。如果这个杂务轮次想留在本地模型上，单独指定模型即可：

{ "agents": { "defaults": { "compaction": { "memoryFlush": { "model": "ollama/qwen3:8b" } } } } }

该 override 不继承会话 fallback 链；失败（含重试耗尽）不会重置会话或丢弃历史，只是继续回复，notifyUser开启时会给出降级提示。工作区为只读（workspaceAccess: "ro"或"none"）时 flush 会跳过。

关掉自动压缩（保留手动路径）

enabled: false禁用嵌入式运行时的阈值自动压缩和直接命令的 post-turn 维护，但 overflow 恢复压缩和手动/compact仍然可用：

{ "agents": { "defaults": { "compaction": { "enabled": false } } } }

压缩太频繁、或上下文变旧了怎么办

Compaction 文档 的 Troubleshooting 一节给出了三个方向：

• 压缩太频繁：多半是模型上下文窗口偏小，或工具输出太大。可以启用 session pruning——它只裁剪旧工具结果（不进摘要、不改写磁盘历史），在两次压缩之间把工具输出控制住。开启方式：

  { "agents": { "defaults": { "contextPruning": { "mode": "cache-ttl", "ttl": "5m" } } } }

  pruning 默认关闭；它对toolResult消息生效，超过 4,000 字符的结果软裁剪为保留首尾各 1,500 字符，上下文占用仍高时再硬清空为占位符。

• 压缩后上下文感觉变旧：用/compact Focus on <topic>引导摘要侧重，或保持 memory flush 开启让笔记存活。

• 需要彻底重来：/new直接开新会话，不做压缩（/new [model]还可以同时指定模型别名）。

deep dive 文档 的排查清单还补了两条判断：

• Compaction spam？检查模型上下文窗口（太小会逼出频繁压缩）和工具结果膨胀（调 session pruning）。
• 小本地模型几乎每条提示都溢出？确认 provider 报告的模型上下文窗口是否正确——OpenClaw 只有在窗口已知时才能限制有效 reserve。

边界与限制

• 压缩只改变模型下一轮看到的内容；完整历史保留在磁盘，可用openclaw sessions相关命令查看会话行与 transcript。
• keepRecentTokens与 reserve 是压缩管线的预算，不是 provider 的 token 硬上限；选更大的摘要模型也不会扩大前台模型的上下文窗口。
• maxActiveTranscriptBytes作用于活跃 SQLite transcript 历史，旧版 JSONL checkpoint 工件不在其目标内。
• 溢出恢复并非万能：provider 表示单次请求本身超过其全部 token 上限时（文档以 Groq 的 HTTP 413 为例），压缩的摘要请求会被同一上限拒绝，OpenClaw 会直接给出 reset 指引而不反复压缩重试。
• 插件可通过registerCompactionProvider()注册自定义压缩 provider，并在配置中设置compaction.provider；设置 provider 会强制mode: "safeguard"，provider 失败或返回空时自动回退到内置 safeguard 摘要管线。

验证是否配置生效的闭环是：改完~/.openclaw/openclaw.json后，继续跑一段长对话，用/status看🧹 Compactions: <count>是否增长、openclaw logs --follow里是否出现embedded run auto-compaction start/complete，以及openclaw sessions --json中会话行的压缩计数是否更新。计数不变且日志无压缩记录，说明要么阈值还没到，要么enabled/mode与你预期的路径不一致，再对照上面的触发路径逐项核对。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw