### [Headroom：16.4k Stars！LLM上下文压缩层，最高省95% token消耗](https://www.willai.cc/article/1328)

**Published:** 2026-06-07T12:17:35

**Author:** hiyoho

**Excerpt:** 用AI Agent干活，token消耗像流水。工具输出一多，日志一长，上下文就爆了。Headroom就是来解决这个问题的。 项目是什么 Headroom是一个面向AI Agent的上下文压缩层，在内容进入LLM之前先做压缩处理。工具输出、日

用AI Agent干活，token消耗像流水。工具输出一多，日志一长，上下文就爆了。Headroom就是来解决这个问题的。

![Headroom](https://admin.hiyoho.com/wp-content/uploads/2026/06/headroom_featured.png)

### 项目是什么

Headroom是一个面向AI Agent的上下文压缩层，在内容进入LLM之前先做压缩处理。工具输出、日志、RAG检索结果、代码文件、对话历史，统统可以压。官方数据说能省60-95%的token，而且答案质量不降。

### 安装要求和过程

要求Python 3.10以上。安装本身很简单：

```
# 全量安装（推荐）
pip install "headroom-ai[all]"

# Node.js版本
npm install headroom-ai

# Docker
docker pull ghcr.io/chopratejas/headroom:latest
```

如果你想按需安装，可以只装指定模块：\[proxy\]、\[mcp\]、\[ml\]、\[code\]、\[memory\]、\[relevance\]、\[image\]，不用全量。装完直接 `headroom wrap claude` 就能把Claude Code包起来用，零代码修改。

### 核心功能

-   **三种接入模式**：当作Python/TypeScript库直接调用 `compress()`，或者跑一个本地代理让任意应用零改动接入，或者直接wrap主流AI编码工具（Claude Code、Cursor、Aider、Copilot都支持）。
-   **MCP服务器模式**：提供了 `headroom_compress`、`headroom_retrieve`、`headroom_stats` 三个工具，可以接进任何MCP客户端。对用Claude Desktop或者Cline的人很方便。
-   **可逆压缩（CCR）**：原始内容不会删，LLM觉得信息不够的时候可以通过工具调用把原始内容拿回来。不是有损压缩，是”按需取用”。
-   **跨Agent共享内存**：多个Agent（Claude、Codex、Gemini）可以共享同一套上下文存储，自动去重。做多Agent协作的人会喜欢这个功能。
-   **自动学习**：跑一下 `headroom learn`，它会去分析失败的会话，把修正规则自动写进 CLAUDE.md / AGENTS.md 这些配置文件。相当于Agent自己进化。

### 典型使用场景

先看数据。官方跑了一些真实工作负载的压缩测试：

| 工作负载类型 | 压缩前token | 压缩后token | 压缩率 |
| --- | :---: | :---: | :---: |
| 代码搜索（100条结果） | 17,765 | 1,408 | 92% |
| SRE故障排查 | 65,694 | 5,118 | 92% |
| GitHub Issue分类 | 54,174 | 14,761 | 73% |

实际场景里，最爽的是这两个：

第一，**长日志排查**。SRE场景里把6万多token的日志压缩到5千多，压缩率92%，而且LLM给出的排查结论和质量没差。这意味着你可以用更便宜的模型、更短的上下文窗口，处理同样复杂的任务。

第二，**RAG场景**。把检索回来的大量chunk先压缩再塞给LLM，原本只能放5条chunk的上下文窗口，现在能放20条。检索质量上去了，token消耗反而下来了。

### 为什么推荐它

我试过几个类似的方案，RTK、lean-ctx，还有OpenAI自己出的压缩方案。Headroom最打动我的是”可逆压缩”这个设计。很多压缩方案是单向的，压完原始信息就没了，LLM判断需要细节的时候拿不到原文。Headroom的CCR机制让LLM可以按需取回原始内容，这个设计很聪明。

另外就是接入成本真的低。如果你用的是Claude Code或者Cursor，一条命令 `headroom wrap claude` 就搞定，不需要改代码，不需要重新配置，直接生效。对于已经用上这些工具的人来说，几乎是零成本的优化。

本周Headroom在GitHub周增长榜排第一，新增了13,000+ star。16.4k的总star数不算高，但增长曲线很陡，说明用过的人都在往上加。这种”开发者口碑传播”的项目，通常比营销驱动的项目更值得跟。

* * *

**GitHub**：[github.com/chopratejas/headroom](https://github.com/chopratejas/headroom)  
**官网文档**：[headroom-docs.vercel.app](https://headroom-docs.vercel.app)  
**协议**：Apache 2.0（可商用）

**Tags:** AI, AI Agent, AI开源, CLI工具, GitHub, headroom, LLM, LLM优化, Python, token压缩

**Categories:** 开源项目

---