几十万 token 压到几千，Agent 省钱的秘密开源了。

大家好，今天 GitHub 上翻到一个项目，值得聊聊。

headroomlabs-ai/headroom

01-github.png

Agent 越智能，每一步往上下文里塞的东西就越多。日志、代码搜索结果、RAG 片段、文件内容、历史消息……模型真正仔细看完的，可能还不到一小半。

headroom 想在这中间加一道筛子。

02-headroom-demo-fast.gif

1. 它到底是什么

headroom 说白了，就是给 AI Agent 配的一层上下文压缩器。

它夹在 Agent 和模型中间，工具输出、日志、RAG 片段、文件内容，全部先过它一道，压完了再送给大模型。

而且它不是只做一个函数就完事。

README 里入口给得很全：Python / TypeScript 库、本地代理、MCP server，还有 headroom wrap claude|codex|cursor|aider|opencode|cline 这种——把你用的 Agent 包一层再启动。

我觉得它聪明的地方在于：不是让你选一种用法，而是你习惯怎么用，它就有那个入口。

简单说，headroom 想解决的不是「怎么调模型」，而是「Agent 每步往上下文塞东西的时候，怎么少塞点，但别丢关键线索」。

03-headroom-savings.png

2. 它解决什么麻烦

现在 Agent 用起来贵，不光是模型本身贵。

一次代码搜索、一次日志排查、一次 RAG 查询，工具能给你返回几千行。模型真正需要的，其实没那么多——结构、异常、边界，几条有代表性的就够了。

headroom 就是在这些东西进模型之前先过一遍。

比如一个 JSON 数组，它会扫一眼字段分布、哪些值重复、有没有异常、边界在哪。日志里要是有错误，它会把错误保住。原始内容先存本地缓存，后面模型万一真需要，再通过 headroom_retrieve 拿回来。

这个点对编码 Agent 来说特别直接——不是每次 rg、cat、API 返回都得原样往里塞。

04-headroom-2.gif

3. 核心看点

headroom 有几个地方我觉得值得看。

第一，入口铺得很宽。

代码里直接调 compress(messages) 也行，开个 headroom proxy --port 8787 也行，OpenAI、Anthropic、Codex 这些客户端走代理也能用上。本地跑着压缩服务，不用动现有代码。

第二，它还搞了 MCP。

MCP server 暴露了 headroom_compress、headroom_retrieve、headroom_stats。Agent 看到大块内容，完全可以自己决定要不要打个压缩。

第三，它不会一刀切全压了。

用户消息不压，系统提示词内容留着，普通代码默认不动，短内容直接放过去。它更像一个路由器，先看内容类型再决定怎么处理。这比直接搞摘要靠谱多了。

第四，它还做了缓存对齐，压完的东西能还原回来。

原始内容能用 hash 找回——这个设计比"压完就丢"让人放心不少。

05-subscription-window-active.png

4. 为什么值得看

headroom 的文档里给了几个挺实在的压测结果。

一个生产日志测试，原始输入 10,144 tokens，压缩完 1,260 tokens，让模型找错误、错误码、修复方式和影响数量，结果 4/4 全对。

文档里的真实工作负载也很直观：

• code search：17,765 tokens → 1,408 tokens
• SRE incident debugging：65,694 tokens → 5,118 tokens
• GitHub issue triage：54,174 tokens → 14,761 tokens
• codebase exploration：78,502 tokens → 41,254 tokens

这些数字不一定你本地也能省这么多，但指向的方向很明显——它最适合那些工具输出很长、结构重复很多的 Agent 场景。

说句实话，现在大家都在研究怎么让模型吃更多，headroom 在想的是怎么让它吃得更精。我觉得这个方向反而更值钱。

07-cache-ttl-dashboard-live.png

5. 怎么用起来

想最快试，Python 这条路最直接：

uv tool install "headroom-ai[all]"
headroom wrap codex

走代理模式也行：

pip install "headroom-ai[proxy]"
headroom proxy --port 8787

然后把兼容 OpenAI 或 Anthropic 的客户端指到本地代理。

要是用 MCP 客户端，可以只装 MCP：

pip install "headroom-ai[mcp]"
headroom mcp install

文档里还提醒了两个容易踩的坑。

一个是 npm 包 headroom-ai 主要是 TypeScript SDK，不带 headroom CLI——CLI 来自 PyPI 的包。装之前先看清自己走的是哪条路。

另一个是 Codex 或其他 MCP host 有时候拿不到 shell 里的 PATH。这时候得用 command -v headroom 找到绝对路径，再写进 MCP 配置。

06-subscription-window-inactive.png

6. 适合谁，以及先注意什么

主要三类人值得先看看。

一类是重度用编码 Agent 的。经常读大文件、跑测试、查日志、扫 issue，headroom 有机会在这些场景里帮你降低上下文噪声。

一类是做 RAG 或搜索应用的。检索结果多、重复字段多、异常项又不能丢——这种场景正好对上它的 SmartCrusher。

一类是自己维护内部 Agent 平台的人。代理、MCP、SDK 三种入口都给了，往现有链路里试比较方便。

不过有几件事得提前知道。

它不是万能药，不是所有东西塞进去都能变短。文档里的 benchmark 也显示，grep 结果和 Python 源码可能是 0% 压缩——因为这些内容本来就不该动。

代理模式还会多一层本地服务。接到团队工具链之前，最好拿自己的日志、搜索结果和真实任务跑一遍。

压缩这事，关键其实是知道什么时候不该压。headroom 至少在这点上想得挺明白的。

08-cache-ttl-dashboard-history.png

有正在被 Agent 上下文塞满困扰的同学，装一个试试，欢迎留言区说说你实际省了多少。

今天就先聊到这里。我们下期再见！