夜雨聆风1. 先区分三件事，不然后面容易混乱
OpenClaw 里常见的“上下文减小”其实是三种完全不同的动作。
1.1 压缩 compaction
目标：缩小整个会话上下文。
理解方式：
像是把聊天记录整理成摘要，让会话整体瘦下来。1.2 截断 truncation
目标：只砍掉一个超大的局部内容，最典型就是某个 tool result。
理解方式：
像是一份工具输出太长，先把它剪短，而不是把整段会话都压缩。1.3 上下文保护 context guard
目标：不一定改磁盘里的 transcript，只是为了这一轮调用模型时别超预算。
理解方式：
像是“临时上车前减重”，而不是“永久修改档案”。2. 什么时候开始进入恢复阶段
恢复阶段不是每轮都会进入。
2.0 Mermaid 恢复入口图
flowchart TDA[组装上下文并调用模型] --> B{本轮是否正常返回?}B -- 是 --> C[afterTurn 结束]B -- 否 --> D[外层 run.ts 分类错误]D --> E{是 context overflow?}E -- 否 --> F[走 auth overload timeout 等其他分支]E -- 是 --> G[进入上下文恢复链]
正常路径是：
组装上下文-> 调模型-> 正常返回-> afterTurn
只有当外层 run.ts 发现错误是下面这些情况，才会进入恢复判断：
context overflow compaction failure auth/profile 问题 overload timeout
这一篇只聚焦和上下文相关的那条链：
context overflow-> 判断是否已经 auto-compaction-> 必要时显式 compaction-> 必要时截断 oversized tool result-> 仍失败才真正收敛成错误
3. auto-compaction 和 explicit compaction 的区别
3.1 auto-compaction
这是 attempt 内部发生的。
你可以把它理解成：
模型这轮跑着跑着，底层 session/runtime 自己发现该压缩了，于是内部先压了一轮。它通过事件暴露：
auto_compaction_start auto_compaction_end
而且 attempt 结束时不会立刻算完成，还要：
waitForCompactionRetry()
意思是：
即使 prompt 已经返回，只要 compaction 还在收尾，这一轮上下文还不算稳定。3.2 explicit compaction
这是外层 run.ts 主动调用：
contextEngine.compact(...)
你可以理解成：
这轮已经结束了，外层看了一眼，发现还是像 overflow，那就主动发起一次显式压缩。
当前默认 legacy engine 最后桥接到老的 compaction 实现。
4. 为什么已经 auto-compaction 过了，外层还不一定立刻再压一次
代码里是有意这么设计的。
如果这轮内部已经 auto-compaction 但外层仍然看到 overflow 信号 外层先 retry 一轮 不马上 double-compact
原因很简单：
内部 compaction 可能已经改变了 transcript，只是这一轮返回时错误信号还没完全收敛。如果立刻再压一次，可能是重复压同一批内容。
所以它先给“已经发生的压缩”一个发挥作用的机会。
5. tool result truncation 到底是什么时机触发的
5.0 Mermaid overflow 恢复链
flowchart TDA[attempt 返回] --> B[外层判断像 context overflow]B --> C{本轮已经 auto-compaction?}C -- 是 --> C1[先 retry 一轮]C -- 否 --> C2[尝试 contextEngine.compact]C1 --> D{仍像 overflow?}C2 --> DD -- 否 --> E[恢复成功]D -- 是 --> F{存在 oversized tool result?}F -- 否 --> G[返回 context_overflow 或 compaction_failure]F -- 是 --> H[truncateOversizedToolResultsInSession]H --> I[再 retry]I --> J{还像 overflow?}J -- 否 --> EJ -- 是 --> G
触发顺序是这样的：
attempt 返回 外层判断是 context overflow 如果没有足够收敛，先考虑 compaction compaction 不行，再看是不是有 oversized tool results 如果有，就执行 truncateOversizedToolResultsInSession(...) 截完再 retry
也就是说：
tool result truncation 不是第一反应，而是 overflow 恢复链里的一个定向补救分支。
它专门解决一种问题：
不是整段会话都老旧了，而是某一个或几个工具结果胖得离谱。
6. “头部”和 “tail” 到底是什么意思
在 truncateToolResultText(...) 里：
head 就是保留文本前面的那一段 tail 就是保留文本最后的那一段
不是抽象概念，就是字符串的前半段和后半段。
7. 截断时，到底保留前面，还是前后都保留
看 truncateToolResultText(...) 的逻辑，可以总结成一句话：
默认保留前面；如果系统认为“后面也很重要”，那就后都保留
7.1 默认情况：只留前面
如果没发现尾部有明显价值，就只保留前面。
因为前面通常能告诉模型：
这是哪种输出 输出的大致结构是什么 工具到底读了什么、列了什么、返回了什么
7.2 特殊情况：保留前后两端
如果 hasImportantTail(text) 判断尾部可能很重要，就改成 head+tail。
它会检查尾部有没有这些迹象：
error exception failed fatal traceback panic stack trace errno exit code JSON 末尾闭合 } summary result complete finished done
大概意思就是：
如果结尾看起来像报错、总结、结果、或者 JSON 收尾结构，那就不能只保留前面，因为真正有用的话很可能就在最后。
8. 代码里“头部”和 “tail” 是怎么切的
truncateToolResultText(...) 里大概是这样做的：
8.1 先算总预算
const budget = Math.max(minKeepChars, maxChars - suffix.length);8.2 如果尾部重要，就切成两段
代码会给 tail 一个小预算，默认大概占正文预算的 30%，最多 4000 字符。
剩下的留给 head。
也就是：
大头留给前面，小头留给最后面，中间整块省略。中间会插入一个标记：
[... middle content omitted — showing head and tail ...]8.3 如果尾部不重要，就只切前面
这时就只保留开头那一截，后面全部不要。
9. 什么时候是“写入前截断”，什么时候是“调用前截断”
这是另一个必须分清的点。
9.1 写入前截断
入口：
session-tool-result-guard.ts
这里做的是：
capToolResultSize(...) 使用 HARD_MAX_TOOL_RESULT_CHARS
工具结果刚准备写进 transcript，就先设一个绝对上限。太离谱的内容，根本不允许原样存进去。
这一步是“持久化守门”。
9.2 调用前截断
入口：
tool-result-context-guard.ts tool-result-truncation.ts
这里做的是：
按当前 context window 估算预算 如果单个 tool result 太大，先砍短 如果整体上下文仍超预算，优先把旧 tool result 替换成占位符
就算磁盘里已经有一条很大的 tool result，这一轮送给模型时，也可以临时把它瘦身，甚至直接换成“已压缩占位符”。
10. “压缩前保留快照”到底是在保留什么，为什么要保留
10.0 Mermaid snapshot fallback 图
flowchart TDA[prompt 结束] --> B[先抓当前 messages snapshot]B --> C{抓取前后是否都没在 compaction?}C -- 是 --> D[记为 pre-compaction snapshot]C -- 否 --> E[不信任这份快照]D --> F[随后等待 compaction retry]E --> FF --> G{是否在 compaction 期间超时?}G -- 否 --> H[使用 current snapshot]G -- 是 --> I{有可信 pre-compaction snapshot?}I -- 是 --> J[回退到 pre-compaction snapshot]I -- 否 --> H
在 attempt.ts 里，prompt 结束后、等待 compaction retry 前，会先抓一份：
snapshot = activeSession.messages.slice()
但不是无条件相信它。
会检查：
捕获前是否正在 compaction 捕获后是否正在 compaction
只有前后都没在压，才把这份 snapshot 当作可信的：
preCompactionSnapshot
它的用途是什么
如果后来 timeout 恰好发生在 compaction 过程中，那当前 session 里的消息可能处在“压到一半”的过渡状态。这时就优先退回到 compaction 之前抓到的那份快照。
对应逻辑在：
selectCompactionTimeoutSnapshot(...)
它会在两种快照间选：
pre-compaction current
你可以把它理解成：
为了避免“压缩压到一半就超时”导致上下文状态半新半旧，系统提前留一张安全快照，必要时回退到那张更稳定的版本。
11. tool result context guard
如果说前面的 truncation 更像“恢复分支”，
那么 installToolResultContextGuard(...) 更像“预防分支”。
它做两层守卫：
11.1 单条太长，先截短
如果一条 tool result 本身就超预算：
先截断这条
11.2 总体还是太长，就压旧结果
如果全部消息加起来还是超预算：
从旧的 tool result 开始 一个个替换成：
[compacted: tool output removed to free context]注意这里的策略是：
先压旧的，再尽量保新的一点。12. 最终什么时候真正放弃
当下面这些情况出现时，恢复链会结束并返回错误：
compaction 被认定失败 compaction 尝试次数用完 tool result truncation 也做过了，还是不行
这时才会真正收敛成：
context_overflow compaction_failure
13. 结论
OpenClaw 的“上下文减小”至少有三类动作：整体压缩、局部截断、调用前保护。 head 就是保留开头的内容，tail 就是保留结尾的内容，代码里本质上是按字符位置切，而不是按语义切。 默认只保留前面；如果尾部像报错、总结、结果或 JSON 收尾，就变成“开头 + 结尾”。 截断分成两层：写入 transcript 前的硬上限，和调用模型前按 context window 动态再缩一次。 pre-compaction snapshot 是为了防止“压缩压到一半超时”时拿到半成品的上下文。 真正报 context_overflow 前，系统通常已经尝试过等待 auto-compaction、显式 compaction、tool result truncation 这些恢复步骤。
