一个工具，累计省下 418 亿 token、17.6 万美元

大家好，我是左手。

有个开源项目，做的事情说简单也简单——在你跟大模型说话之前，把那些冗余的废话删掉。说复杂也复杂，删完之后模型回答的质量不变，甚至更好。

这个项目叫 Headroom。截至现在，全球 889 个活跃实例，累计省下418 亿个 token，换算成钱大概是17.6 万美元，优化了 120 万次请求——不是 benchmark 推演，是真金白银在每天的生产环境里跑出来的。数据来自官方社区实时榜单：

https://headroom-docs.vercel.app/docs/community-savings

你想想这个画面。你让 Claude Code 帮你 debug，它哗哗哗搜了几十个文件，读了十几个函数签名，翻了 build log，查了 issue 讨论……啪，10K token 进去了。可问题是，这些内容里有大量跟你当前问题没半毛钱关系的东西。import 语句你没改过、已经 pass 的 test case、跟当前文件风格完全一致的 boilerplate。

这些 token，你都是要付钱的。

Headroom 做的，就是在这些内容到达 Claude 或者 GPT 之前，先过一遍筛子，把真正有用的部分挑出来，把冗余的裁剪掉。裁完之后，模型该答什么还答什么——准确率不掉的。

Headroom 的实际压缩效果：一次真实代码搜索，17,765 token → 1,408 token，节省 92%。同样的结果，十分之一的成本。

这东西到底是个啥

一句话说清楚，Headroom 是一个上下文压缩层，跑在你的 AI Agent 和 LLM 之间。

你用 Claude Code 写代码的时候，每次 Claude 调工具、读文件、看日志，这些内容都会塞进上下文，然后发给 Anthropic 的 API。发的越多，花的越多，响应越慢。

Headroom 插在中间，自动识别内容类型——JSON 就用 SmartCrusher 压缩，代码就用 CodeCompressor 走 AST 裁剪，自然语言就用 Kompress-base 模型精简。压缩完再发给 LLM，省 60-95% 的 token。

而且它不是一刀切全删掉。被裁掉的原内容存在本地，LLM 如果在回答时需要细节，可以通过 MCP 工具把原始内容取回来。这叫什么，CRR，Compress-Cache-Retrieve，可逆压缩。

我一开始听到这个概念的时候是有点怀疑的。压缩 90%，答案不变？？？这不科学啊。

后来翻了他们的 benchmark 才明白怎么回事。说真的我当时的心情就是，好家伙。。。GSM8K 数学推理，压缩前后准确率一模一样（都是 0.870）。TruthfulQA 事实性问答，用压缩之后反而高了 0.030。SQuAD v2 和 BFCL 工具调用准确率都是 97%。

四种典型 Agent 工作场景下的 token 节省数据：Code Search 和 SRE 排查都能省 92%，代码库探索省 47%。所有场景准确率不变。

我自己的理解是这样的——LLM 其实不需要读完整文件才能理解一段代码。它需要的是函数签名、关键逻辑块、跟当前问题相关的上下文。一个 800 行的文件，可能只有 3 个函数跟你的问题有关。Headroom 做的事就是把那 3 个函数挑出来，剩下的存起来备用。

为啥你会需要这东西

说真的，如果你只是偶尔问 ChatGPT 几个问题，根本不需要这个。

但如果你在用 Claude Code、Cursor、Aider 这些 AI 编码 Agent，情况就不一样了。这些 Agent 的特点是它们会自己不停地调工具、读文件、搜代码——每一次操作都在烧 token。

我给大家算一笔账。Code search 场景，压缩前 17,765 token，压缩后 1,408 token，省了 92%。SRE 故障排查，65,694 → 5,118，也是 92%。你的 Claude Code 或者 Codex 用了 Headroom 之后，单次请求的成本直接缩到原来的十分之一以下。

而且不光省钱。token 少了响应也更快，一轮对话能塞进上下文的东西更多——你想想看，Agent 可以处理更复杂的任务而不会因为上下文窗口满了被迫截断。

Headroom 的实际管道：ContentRouter 识别内容类型后并发分发给 SmartCrusher、CodeCompressor、Kompress-base 三个压缩器，经过 CacheAligner 对齐前缀后发给 LLM，原始内容存 CCR 可随时取回。

我记得之前在某个 Agent 群里看到一个朋友吐槽，说他在 Cursor 里 debug 一个复杂 bug，来回搞了 20 多轮，那一个下午花了 40 多刀。当时我还想这也太离谱了。现在回头想，如果他那会儿装了 Headroom，大概率不会花到 10 刀。

它怎么做到的

Headroom 肚子里装了 6 套压缩算法，各干各的活。

SmartCrusher专门对付 JSON。AI Agent 最烧 token 的环节之一就是工具返回的 JSON——API 响应、搜索结果、结构化数据。SmartCrusher 能识别 JSON 里的冗余字段、重复结构、默认值，然后把它们压到只剩骨架。70-90% 的压缩率。

CodeCompressor走的是 AST（抽象语法树）的路子。它不是草率的删代码，而是保留 import 声明、函数签名、类型注解和关键逻辑，把函数体里跟当前上下文无关的部分精简掉。Python、JS、Go、Rust、Java、C++ 都能识别。

Kompress-base是 Headroom 自己在 HuggingFace 上开源的一个文本压缩模型。专门在 AI Agent 的真实工作流上训练的，不是通用压缩模型。处理自然语言搜索、日志输出、diff 结果这些东西。

另外还有三个辅助性的：CacheAligner 负责对齐前缀让 Anthropic/OpenAI 的 KV Cache 能命中，Image compression 处理图片压缩，IntelligentContext 做重要性评分和上下文窗口适配。

你可能会想——这么多算法一起上，不会搞混吗？Headroom 的做法很聪明，一个 ContentRouter 自动判断内容类型然后分发到对应的压缩器。你不需要告诉它「这段是 JSON」「那段是代码」，它自己判断。

坦率的讲，这个架构设计让我想到一个挺妙的类比。TCP/IP 协议栈每一层解决不同的问题，数据流从上到下逐层封装。Headroom 类似，只是它是往上走的——每一层负责一类内容的压缩，最后拼出一个极致精简的上下文。

跟同类比

说到上下文压缩，市面上其实有好几个方向的东西。

RTK 走得比较早，做的是 CLI 命令输出的精简——git show、ls的结果压缩成要点。很轻量，也很好用。Headroom 直接把 RTK 集成了进去作为第一层，然后再往下继续压。

lean-ctx 是最近出来的，专注 CLI 命令和 MCP 工具的上下文优化，设计很干净。Headroom 也能把 lean-ctx 当 context tool 来用，你在环境变量里设一下就行。

Compresr 和 The Token Company 走的是云端 API 路线——你把文本发给他们的服务器，他们帮你压缩。这个路线有个天生的问题，你的数据得先发出去。对很多公司来说，代码和 log 发到第三方服务，合规这关就过不了。

OpenAI 自己也有原生 compaction，但那只是对话历史的压缩，不碰工具输出、不碰 RAG chunk、不碰文件内容。

Headroom 跟这些比，最大的不同是三个字，全覆盖。它不满足于只压一种类型的内容——工具返回的 JSON、读进来的代码、搜出来的文档片段、build log、diff 结果，只要是往 LLM 送的，全部截一道。而且是本地跑，数据不出你的机器。

有一说一，也不是说 Headroom 就全方面碾压。RTK 在 CLI 输出这个单一场景下做得极好，而且只做一件事，配置简单。如果你只需要压命令输出，装 RTK 足够。但如果你跑的是全功能 Agent——调工具、读代码、搜 RAG、看日志——那 Headroom 的全覆盖优势就体现出来了。

怎么装

三种方式，看你习惯：

装完选运行模式：

这里面我最喜欢的是headroom wrap这个命令。一行，不用改任何代码，不用配环境变量，直接把你的 Claude Code 或者 Codex 包上压缩层。我手残如我一开始还跑去读了半天 proxy 文档，配了半天环境变量，结果发现其实只要一行headroom wrap claude。

看一下省了多少：

会输出详细的 token 节省统计。

那些把我打动的小细节

除了核心功能，有几个细节让我觉得这个作者是真的在用 agent 的人。

Cross-agent memory。你同时在用 Claude Code 和 Codex？两个 agent 之间的上下文可以通过 Headroom 的 shared memory 共享。Claude Code 搜到的东西，Codex 不用再搜一遍。自动去重，跨项目隔离。这个功能对于那种要在两个工具间切换的工作流来说太省事了。

headroom learn。这个功能有点骚。它分析你 failed 的 Agent 对话记录，找出哪里出了问题，然后自动往你项目里的CLAUDE.md或者AGENTS.md写改进建议。等于说——你的 Agent 失败的教训，能变成下一次对话的配置改进。我不是在吹，你去看它的文档，这个 feature 是真实存在的。

压缩安全护栏。0.25 版本加的。意思是 Headroom 能识别压缩是不是把错误信息裁掉了、是不是导致 LLM 要求重新取原文的频率突然升高。如果发现异常，它会自动降低压缩力度或者暂停压缩。这个设计说明作者考虑的不只是「怎么压得更多」，也包括「压过头了怎么办」。

本地优先。数据不出机器这件事，对个人开发者来说是隐私安心，对企业来说是合规必选项。Headroom 没有云端依赖，所有压缩全在本地跑，你甚至可以在完全离线的环境下用。

不适合谁

我觉得有几类朋友暂时不用考虑 Headroom。

如果你只偶尔用 ChatGPT 网页版聊天，装这个没意义，它不是给这种场景设计的。

如果你的 Agent 工作流非常简单——比如每次只问一个很具体的问题，不会触发大范围代码搜索——那 token 消耗本来就不高，装 Headroom 增加的复杂度可能得不偿失。

如果你在纯沙箱环境里跑，本地进程跑不了，那 Headroom 的代理模式用不了。不过你仍然可以用库模式在 Python 代码里直接调compress()。

另外有一点要说明，Kompress-base 模型首次运行需要从 HuggingFace 下载，如果你的网络访问 HuggingFace 比较困难，需要提前配好镜像或者HF_ENDPOINT。

我的判断

我觉得 Headroom 是那种「用了就回不去」的工具。

它不像一个新框架或者新模型那样让你折腾半天配环境跑 demo，它是锦上添花——你本来就在用 Claude Code 或者 Codex 写代码，你本来就在烧 token，Headroom 只是悄悄插进来帮你把不必要的消耗砍掉了。使用体验几乎透明。

这么多人用，不是因为 hyped。而是因为每天用 AI coding agent 的人越来越多了，token 成本变成了一个真实可感的痛点。你试试就知道了。

2026 年的 AI Agent 工具链正在成型。如果说 Agent 框架是骨架，MCP 是神经，那 Headroom 这种东西就是血液循环系统——把养分（信息）高效输送到需要的地方，同时不浪费能量（token）。它不会上头条，但它让你日常的开发体验一点点变好。

如果你已经在用 Claude Code 或者 Codex，花 5 分钟装一下试试。看不见它的时候它默默省钱，看见它的时候是你在查headroom perf统计的时候——那种「卧槽我省了这么多」的感觉，真的爽。

项目信息卡- 项目名称：Headroom- GitHub：https://github.com/chopratejas/headroom- Stars：26,466（截至 2026/06/14）- 语言：Python + TypeScript- 协议：Apache 2.0- 最新版本：v0.25.0（2026-06-12）- 文档：https://headroom-docs.vercel.app/docs- 安装：pip install "headroom-ai[all]"或npm install headroom-ai