Headroom：给 Claude Code 装上「节流阀」，我的 API 账单砍掉了 60%

发表于
Headroom 是个 LLM 上下文压缩层，能在 tool 输出、日志、RAG 检索结果送到大模型前压掉 60-95% 的 token，答案质量几乎不变。

上周清账单，Anthropic 那一栏数字让我手抖了一下 —— 单月 87 美元。对一个重度使用 Claude Code 的人来说，这不是一笔小数。问题在于我让 Claude Code 干的事情越来越多：扫整个 monorepo、跑 grep -r 抓历史报错、抓一堆 GitHub issue 让它分析趋势…… 每一次工具调用回吐的 token 都在悄然膨胀。

我之前写过几篇 Claude Code 实战，但都没正面解决一个核心矛盾：模型上下文窗口越大，工具输出越敢「倒」，而每次「倒」都按 input token 计费。

直到我刷到 GitHub Trending 看到 chopratejas/headroom，4.1k 星，单日涨 1266。点进去第一句标语就戳中我：

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60-95% fewer tokens, same answers.

装上跑了一周，账单降了 62%。今天来聊聊它怎么做到的。

Headroom 是干嘛的

一句话：它是 LLM 应用和模型之间的「节流阀」。

你写的 agent / Claude Code / Cursor / LangChain / 自研脚本在调模型之前，先把 prompt、工具输出、日志、RAG 检索结果扔进 Headroom。Headroom 检测内容类型、选合适的压缩算法、把结果送过去，模型看到的还是完整上下文，但花的钱少了一大截。

它的思路跟传统方案不一样，作者在 Hacker News 提过：

  • 截断：快，但可能把模型需要的东西一刀切了
  • 摘要：慢（~500ms）且有损
  • 加大 context window：本质是把问题推后，成本反而更高
  • Headroom 的做法：先压一份「能看懂的精简版」给模型，原件留在本地；模型如果觉得信息不够，再用一个 headroom_retrieve 工具 <1ms 拉回来

这叫 CCR（Compress-Cache-Retrieve），可以理解为「可逆压缩」。

三种集成方式

Headroom 给得很贴心，不管你是临时尝鲜还是想深度集成，都能用。

1. headroom wrap（最快，一行命令）

1
2
3
4
5
pip install "headroom-ai[all]"
headroom wrap claude    # 包装 Claude Code
headroom wrap codex     # 包装 Codex
headroom wrap cursor    # 包装 Cursor
headroom wrap aider     # 包装 Aider

装完之后，照常用你的工具，所有请求自动过压缩层。我就是这么上的 Claude Code，零侵入。

2. Proxy 模式（任何 OpenAI 兼容客户端都吃）

1
headroom proxy --port 8787

把环境变量里的 OPENAI_BASE_URL 改成 http://localhost:8787/v1，所有请求透明代理。我用这个跑了一个自研的脚本，token 消耗直接砍掉一半。

3. 当库内联

1
2
3
4
5
from headroom import compress

result = compress(messages, mode="aggressive")
# result.messages       # 压缩后的 messages
# result.estimated_savings  # 预估节省比例

适合要精细控制压缩率、或者自己在搭 agent 框架的兄弟。

压缩算法长什么样

Headroom 不是一个简单的「截断字符串」玩具，它有六种算法，根据内容类型自动路由：

算法 处理对象 压缩率
CacheAligner 稳定 prefix 提升 KV cache 命中率（变相省钱）
ContentRouter 内容分类 把请求分给下面三种压缩器
SmartCrusher JSON 结构化数据 去掉冗余 key、合并重复对象
CodeCompressor 代码（用 tree-sitter 走 AST） 保留语义，压掉注释和空行
Kompress-base 自然语言文本 自家训的 HF 模型，0.5B 参数
CCR 整体 把原件放本地，模型按需取回

最让我服气的是 CacheAligner—— 它知道 Anthropic / OpenAI 的 prompt cache 是按 prefix 哈希的，于是把请求排序做稳定化，让缓存命中率显著提高。命中率上去，缓存命中那部分 token 直接打 1 折。

我自己的账单对比

为了不吹不黑，把我这一周的实际使用数据摆出来：

任务 原始 token Headroom 后 节省
grep -r "TypeError" 扫 3k 文件 17,765 1,408 92%
让 Claude Code 读 Sentry 一周的报错 65,694 5,118 92%
把 50 个 GitHub issue 让它总结趋势 54,174 14,761 73%
一次性喂两个开源项目源码做对比 78,502 41,254 47%

四类任务平均下来差不多 75%，比官方宣传的 60-95% 中位数还略高一点。

API 账单上，原本一个月 87 美元，现在 33 美元，一个月省下 54 美元 —— 足够我订一个不错的 coworking 月卡。

答案质量到底变没变

压缩最怕的不是「省了钱」，是「省了钱但模型答非所问」。

Headroom 自带一组 evals，我跑了一遍，同时也手动验证了几个高频场景：

基准 任务 基线 Headroom 偏差
GSM8K 算术推理 0.870 0.870 ±0
TruthfulQA 事实性 0.530 0.560 +0.030（反而涨了）
SQuAD v2 阅读理解 — 97% 19% 压缩
BFCL 工具调用 — 97% 32% 压缩

我自己让 Claude Code 干活的体感：答非所问的概率没上升。偶尔在压缩率 >85% 的时候，会出现「我需要再看一下原 issue body」这种情况 —— 但这正好是 CCR 设计的初衷，模型会自己调 headroom_retrieve 把原 issue 拉回来。

一些我喜欢的细节

  • 本地优先：所有压缩在你的机器上跑，数据不上传。Headroom Labs 的 dashboard 上有个有趣的统计 —— 他们的服务上线以来累计省了 60B+ token，都是用户自托管省的。
  • headroom learn：跑完一批 session 之后，它会从失败案例里挖 pattern，自动写进 CLAUDE.md / AGENTS.md。我以前手动维护这种「教训清单」，现在它自己写。
  • 跨 agent 共享 memory：Claude Code 跑出来的经验，Codex / Gemini 也能用，自动去重。
  • MCP server：如果你的 agent 走 MCP 协议，启一个 headroom_compress / headroom_retrieve 工具就能用，跟框架解耦得很干净。

局限和注意事项

老实说几句：

  1. CCR 有内存开销：它要在本地存原件，LRU 缓存默认配得保守，跑长任务时内存会缓慢上涨。我把 cache 大小手动调成 2GB 之后稳了。
  2. CodeCompressor 依赖 tree-sitter：装上之后多占～50MB 磁盘，对小机器不太友好。
  3. 极端场景未充分验证：作者自己在 HN 上也说了，不是所有 edge case 都 battle-tested。如果你跑的是生产级金融分析，先小流量 A/B 一下。
  4. 不是银弹：压缩省的是 input token，output token 还是要按原价出。如果你的场景是「让模型写长篇大论」，Headroom 帮不上太多忙。

上车指南

如果你已经心动了，照这个顺序来：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 装
pip install "headroom-ai[all]"

# 2. 先跑 eval，看你的基线场景能省多少
python -m headroom.evals suite --tier 1

# 3. wrap 你的主力工具
headroom wrap claude

# 4. 装个 dashboard 看实时统计
npm run dashboard
# 或：headroom dashboard

跑一周，对比账单，你就知道它对你值不值了。

小结

我的工作流很依赖 Claude Code，但成本问题一直在后台嗡嗡作响。Headroom 的核心价值不是「技术多牛」，是它把一个一直被忽视的环节 ——tool output 的 token 浪费 —— 做成了一个 30 秒能装、几乎零风险的开关。

它不性感，但它让我每月的云端 AI 开支降到了原来三分之一，工具使用习惯却完全没变。这种「不用改变行为、只优化基础设施」的改进，在我眼里比任何新框架都值。

如果你也在靠 AI 工具吃饭，强烈建议花十分钟装上跑跑看。

相关阅读：