Headroom 是什么？给 Claude Code、Codex 压缩上下文减少 Token

Thu, 13 Aug 2026 22:22:00 +0800

如果你经常使用 Claude Code、Codex、Cursor 这类 AI Agent，会发现 Token 不只是消耗在自己输入的问题上。

Agent 执行一次任务时，可能反复读取代码、终端输出、日志、JSON、搜索结果和历史上下文，其中不少内容最终都会进入模型。

Headroom 解决的就是这部分问题：先在本地把这些上下文压缩，再发送给 LLM。官方将它定位为 AI Agent 的“Context Compression Layer（上下文压缩层）”。

Headroom 是怎么减少 Token 的？

它并不是简单删除聊天记录。

按照官方目前的架构，Headroom 会识别不同类型的上下文，再使用不同方法处理，例如：

JSON、工具输出；
代码和文件；
日志；
RAG 检索结果；
对话历史。

处理流程大致可以理解成：

Claude Code / Codex / AI Agent
        ↓
日志、文件、工具输出、上下文
        ↓
      Headroom
        ↓
压缩后的上下文
        ↓
       LLM

Headroom 在本地运行，并且设计了可逆压缩机制。原始内容可以保存在本地缓存中，如果模型后续确实需要完整数据，可以再次获取，而不是单纯粗暴截断内容。

这也是它和“让 AI 回复简短一点”最大的区别。

Caveman 一类 Skill 更偏向减少模型输出内容，而 Headroom 主要处理进入模型之前的上下文。

到底能够省多少 Token？

这里需要区分场景。

Headroom 官方目前给出的参考范围是：

JSON 等结构化数据：约减少 60%～95%；Coding Agent：整体约减少 15%～20%。

项目仓库还公布了几个实际工作负载：

场景	原始 Token	压缩后	官方节省率
Code Search	17,765	1,408	92%
SRE 故障排查	65,694	5,118	92%
GitHub Issue 分类	54,174	14,761	73%
Codebase Exploration	78,502	41,254	47%

可以看出来，不存在所有任务固定节省 60%～95% 的情况。输入中 JSON、日志和重复信息越多，压缩空间通常越明显。

压缩之后会不会影响回答？

这也是 Headroom 最需要关注的问题。

官方公布的基准测试中，GSM8K 使用 100 个样本，Baseline 与 Headroom 都得到 0.870；TruthfulQA 测试则从 0.530 变为 0.560。项目还提供了对应测试方法用于复现。

但这里不能直接得出：

“Headroom 压缩后永远不会影响模型准确率。”

这些只能说明在项目方公布的测试条件下暂未观察到明显精度下降。

如果是大型代码库修改、复杂 Debug 或包含大量细节的长任务，最好还是自己做一次开启与关闭 Headroom 的对照测试。

哪些场景更适合 Headroom？

Headroom 更适合那些会大量读取外部内容的 AI Agent，例如：

Claude Code；
Codex；
Cursor；
大型项目代码分析；
大量终端日志排查；
JSON / API 返回数据处理；
RAG 知识库应用。

官方目前已经提供 Library、Proxy、MCP Server 以及 headroom wrap 等接入方式，并明确支持 Claude、Codex、Cursor、Aider 等工具。

如果只是偶尔问几句话，输入上下文本身只有几百 Token，那么专门部署 Headroom 的意义就没有那么大。

使用前需要知道的限制

Headroom 最大的价值并不是“让任何 AI 都省 95% Token”，而是减少 Agent 工作过程中大量机器生成上下文的浪费。

同时需要注意：

节省比例与任务类型高度相关；
60%～95% 不能直接套用到所有 Coding Agent；
引入上下文压缩层后，系统本身也会增加一定复杂度；
关键代码修改和复杂任务仍建议验证压缩前后的结果；
官方测试不能代替自己的真实使用环境测试。

总结

Headroom 的思路比较直接：

不要等一大堆日志、JSON 和工具输出进入 LLM 后再考虑 Token，而是在发送之前先压缩。

对于 Claude Code、Codex 这类频繁读取代码和工具输出的 Agent，这个方向确实具有实际价值。官方目前给出的 Coding Agent 参考节省幅度约为 15%～20%，而 JSON、日志等高冗余数据在特定场景下可能达到更高压缩比例。

至于能不能真正降低自己的 Token 消耗，最好还是用同一个真实项目分别开启、关闭 Headroom 跑一次，再比较输入 Token、任务结果和执行过程。

参考资料

Headroom 官方 GitHub：headroomlabs-ai/headroom
Headroom 官方 Documentation
项目许可证：Apache License 2.0

AI Token 压缩 on 拾光集