【无标题】当工具返回 50KB 结果时发生了什么？—— OpenClaw 处理大工具输出的工程实践

1. 引言：50KB 的“定时炸弹”

假设你给 Agent 下达了一个指令：“在项目代码库里搜索所有使用旧版 API 的地方，列出来。” Agent 调用grep或ast-grep，返回了 50KB 的匹配结果。

这 50KB 看起来不多，但一旦进入上下文窗口，它就像一个隐形炸弹——在后续对话中不断累积 Token，挤压其他信息的空间，最终撑爆 Context Window。更糟的是，模型不会报错说“结果太大了”，它会直接超时或返回 400 错误。

在 OpenClaw 的实际运行中，工具调用返回超大结果会引发一系列连锁问题。本文将逐一拆解这些问题，并展示 OpenClaw 和更广泛的 Agent 工程社区如何处理它们。

2. 大工具输出带来的三大问题

2.1 问题一：直接撑爆 Context Window

这是最直观的问题。假设你的模型上下文窗口是 128K Token，系统提示词占 10K、对话历史占 30K、工具定义占 8K——剩余可用空间不到 80K。50KB 的工具输出（约 13K-17K Token）还能塞进去，但如果多个工具连续返回大结果，或者单个结果超过 100KB，窗口会被瞬间填满。

微软官方文档明确指出，Azure OpenAI API 对tool_outputs有硬性限制：combined tool outputs must be less than 512kb，且该限制与订阅计划无关，无法通过配置提升。AWS 的 Strands Agents 同样面临tool result too large错误，建议通过截断、分块或摘要来处理。

2.2 问题二：Token 消耗失控

大工具输出不只是“占空间”，还直接烧钱。IBM 研究院 2026 年发表的一篇论文给出了一个触目惊心的对比：在材料科学场景中，工具返回一个 128×128×128 的 3D 矩阵（200 万个 float32 元素），传统方式仅处理到这个环节就需要约 2,082 万 Token。而使用“指针式”方法（稍后会详述），整个过程仅消耗约 1,234 Token——相差近 17,000 倍。

2.3 问题三：上下文污染与注意力稀释

即使结果没有完全撑爆窗口，大段的结构化数据（日志、JSON、表格）也会污染上下文。研究表明，LLM 对位于上下文中间位置的信息关注度显著下降。当大量工具输出堆积在历史记录中，Agent 的注意力资源被稀释，关键的系统指令和用户意图被“淹没”，导致推理质量下降。

核心风险：工具输出过大不只是“占地方”，它会系统性侵蚀 Agent 的推理能力和经济效益。

3. OpenClaw 的应对策略

OpenClaw 针对大工具输出问题采取了组合拳式的处理方案。

3.1 策略一：会话剪除（Session Pruning）

剪除（Pruning）是 OpenClaw 的一种轻量级机制，专门针对工具调用的输出进行修剪。

与压缩（Compaction）摘要整个对话不同，剪除只关注工具返回内容——当一个工具的输出过大时，系统会在内存中截断或修剪该输出，只保留头部和尾部关键信息。剪除按请求在内存中处理，不会保存到磁盘上的会话转录中。

适用场景：当工具返回的是日志、列表等“可截断”的连续数据时。

局限性：如果工具返回的是完整的、不可分割的结构化数据（如 JSON 对象），剪除可能会破坏数据完整性，导致后续工具调用失败。

3.2 策略二：自动压缩（Compaction）

当剪除不足以解决问题时，压缩会介入。压缩是更彻底的“瘦身”——它将早期对话历史（包括大工具输出）摘要为一条精简条目，释放出大量窗口空间。

关键机制：压缩会确保工具调用与结果的配对不被打断。如果拆分点落在工具块内部，系统会自动移动边界，让配对保持在一起。完整的对话历史仍保留在磁盘上——压缩只改变模型在下一轮“看到”的内容，不删除任何原始数据。

3.3 策略三：Skill 机制——工具输出不进上下文

这是 OpenClaw 最根本的防御手段。在前几篇博客中我们提到，Skills 的核心设计是脚本代码本身从不进入上下文窗口，只有脚本执行的输出结果（如“验证通过”或具体错误信息）才会被加载。

对于工具调用，同样的原则可以延伸：如果工具需要处理大量数据，可以将其封装为一个 Skill，让 Skill 的执行脚本在本地处理数据，只把处理后的摘要或结论返回给 Agent。这样，即使工具内部处理了 50MB 的数据，Agent 的上下文中也只有几百个 Token 的摘要。

4. 更前沿的解法：IBM 的“记忆指针”方案

除了 OpenClaw 的现有机制，2026 年 IBM 研究院提出了一种更具突破性的方法——用“记忆指针”代替原始数据。

4.1 核心思路：模型操作指针，而非数据

IBM 的方法的核心是：当工具输出超过阈值时，将输出存储在外部“运行时记忆”中，仅向模型返回一个指针（如/memory/grid_generator/result_001）。模型后续需要用到该数据时，传递这个指针，由系统在工具执行时自动解析为原始数据。

这种方法的关键在于：

1. 模型从不“看到”大块数据——它只操作短标识符
2. 工具执行时自动解析指针——对工具来说透明，无需修改原代码
3. 数据完整保留——不是截断或摘要，而是完整存储

4.2 效果对比

IBM 的实验数据极具说服力：

传统方式连第一步都走不完，而指针方式以 17,000 分之一的 Token 消耗完成了全部工作流。

这种“存储-指针-按需解析”的模式，与 OpenClaw 的 Memory 系统和 Skills 机制在哲学上高度一致——核心信息不常驻上下文，只在需要时按精度加载。

5. 一张图看懂大工具输出的处理策略

6. 日常实践建议

基于以上分析，给 Agent 开发者的实操建议：

1. 工具设计时主动控制输出大小：在工具实现中加入limit、head、tail等参数，让调用方能控制返回量
2. 对于已知的大结果场景，优先封装为 Skill：让数据处理在本地完成，只返回结论
3. 启用 OpenClaw 的自动剪除和压缩（默认开启）
4. 监控 Token 消耗：通过/status观察历史中哪些工具调用是“Token 大户”
5. 参考“指针模式”：对于必须完整保留的大数据，考虑外部存储 + 引用 ID 的模式

7. 结语

工具返回大结果是 Agent 系统中最常见也最隐蔽的“慢性杀手”。OpenClaw 通过剪除、压缩、Skill 封装三层机制构建了防御体系。而 IBM 的“指针模式”则展示了一条更激进的路径——让模型操作数据引用而非数据本身，从根本上解决了大工具输出对上下文的侵蚀。

无论采用哪种策略，核心原则是一致的：上下文是稀缺资源，应该留给真正需要模型“思考”的信息；而原始数据、脚本代码、大块结果，应该留在上下文之外，只在需要时按需加载。