OpenClaw源码解析(十三):上下文什么时候压缩,什么时候裁剪,什么时候放弃

1. 先区分三件事，不然后面容易混乱

OpenClaw 里常见的“上下文减小”其实是三种完全不同的动作。

1.1 压缩 compaction

目标：缩小整个会话上下文。

理解方式：

像是把聊天记录整理成摘要，让会话整体瘦下来。

1.2 截断 truncation

目标：只砍掉一个超大的局部内容，最典型就是某个 tool result。

理解方式：

像是一份工具输出太长，先把它剪短，而不是把整段会话都压缩。

1.3 上下文保护 context guard

目标：不一定改磁盘里的 transcript，只是为了这一轮调用模型时别超预算。

理解方式：

像是“临时上车前减重”，而不是“永久修改档案”。

2. 什么时候开始进入恢复阶段

恢复阶段不是每轮都会进入。

2.0 Mermaid 恢复入口图

flowchart TD    A[组装上下文并调用模型] --> 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 过了，外层还不一定立刻再压一次

代码里是有意这么设计的。

1. 如果这轮内部已经 auto-compaction
2. 但外层仍然看到 overflow 信号
3. 外层先 retry 一轮
4. 不马上 double-compact

原因很简单：

内部 compaction 可能已经改变了 transcript，只是这一轮返回时错误信号还没完全收敛。如果立刻再压一次，可能是重复压同一批内容。

所以它先给“已经发生的压缩”一个发挥作用的机会。

5. tool result truncation 到底是什么时机触发的

5.0 Mermaid overflow 恢复链

flowchart TD    A[attempt 返回] --> B[外层判断像 context overflow]    B --> C{本轮已经 auto-compaction?}    C -- 是 --> C1[先 retry 一轮]    C -- 否 --> C2[尝试 contextEngine.compact]    C1 --> D{仍像 overflow?}    C2 --> D    D -- 否 --> E[恢复成功]    D -- 是 --> F{存在 oversized tool result?}    F -- 否 --> G[返回 context_overflow 或 compaction_failure]    F -- 是 --> H[truncateOversizedToolResultsInSession]    H --> I[再 retry]    I --> J{还像 overflow?}    J -- 否 --> E    J -- 是 --> G

触发顺序是这样的：

1. attempt 返回
2. 外层判断是 context overflow
3. 如果没有足够收敛，先考虑 compaction
4. compaction 不行，再看是不是有 oversized tool results
5. 如果有，就执行 truncateOversizedToolResultsInSession(...)
6. 截完再 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 TD    A[prompt 结束] --> B[先抓当前 messages snapshot]    B --> C{抓取前后是否都没在 compaction?}    C -- 是 --> D[记为 pre-compaction snapshot]    C -- 否 --> E[不信任这份快照]    D --> F[随后等待 compaction retry]    E --> F    F --> 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. 结论

1. OpenClaw 的“上下文减小”至少有三类动作：整体压缩、局部截断、调用前保护。
2. head 就是保留开头的内容，tail 就是保留结尾的内容，代码里本质上是按字符位置切，而不是按语义切。
3. 默认只保留前面；如果尾部像报错、总结、结果或 JSON 收尾，就变成“开头 + 结尾”。
4. 截断分成两层：写入 transcript 前的硬上限，和调用模型前按 context window 动态再缩一次。
5. pre-compaction snapshot 是为了防止“压缩压到一半超时”时拿到半成品的上下文。
6. 真正报 context_overflow 前，系统通常已经尝试过等待 auto-compaction、显式 compaction、tool result truncation 这些恢复步骤。