使用 Claude Code、Codex、Cursor 等 AI 编程工具时，真正消耗 Token 的往往不只是你输入的提示词。

代码搜索结果、终端日志、报错堆栈、GitHub Issue、历史对话和 RAG 检索内容，都会被不断塞进上下文。随着任务持续进行，上下文越来越长，每次请求的成本和等待时间也会随之增加。

最近发现的开源项目 Headroom，就是专门解决这个问题的。

它会在日志、代码、文件和工具输出发送给大模型之前，先识别内容类型并压缩其中的重复信息和低价值内容，让模型尽量只接收真正需要的信息。

根据项目公开测试，部分场景可以减少约 47%—92% 的输入 Token。

Headroom 是什么？

Headroom 是一个面向 AI Agent 和 AI 编程工具的上下文压缩层。

简单理解，它位于 AI 工具与大模型 API 之间：

1
2
3
4
5
6

Claude Code / Codex / Cursor
            ↓
         Headroom
     压缩日志、代码和历史上下文
            ↓
   OpenAI / Anthropic 等模型

它并不是简单粗暴地删除历史消息，而是根据内容类型选择不同的压缩方式。

例如：

• JSON 数据使用结构化压缩
• 源代码按照 AST 语法结构处理
• 普通文本使用专门的压缩模型
• 重复日志、无关字段和冗余搜索结果会被优先精简
• 原始内容可保存在本地，需要时仍可重新获取

Headroom 默认在本地运行，项目说明中表示，处理的数据可以保留在本机，而不需要额外上传到第三方压缩服务。

实际能节省多少 Token？

Headroom 项目给出了几组真实 Agent 工作负载测试数据：

这组数据说明，Headroom 最适合处理大量结构化数据、搜索结果和重复日志。

如果只是几句话的简单问答，压缩空间通常不会特别明显；但在大型代码仓库、持续调试或多 Agent 工作流中，每次节省的 Token 会不断累积。

压缩后会不会影响回答质量？

这是使用上下文压缩工具时最需要关注的问题。

Headroom 项目公开了 GSM8K、TruthfulQA、SQuAD v2 和 BFCL 等测试结果：

从项目公布的数据看，压缩后没有出现明显的准确率下降，部分测试结果甚至略有提高。

不过需要注意，这些结果主要来自项目方自己的测试环境，并不能代表所有代码库和业务场景。更稳妥的做法，是先在自己的项目中运行一段时间，对比压缩前后的回答质量和 Token 消耗，再决定是否长期启用。

Headroom 支持哪些 AI 编程工具？

Headroom 已经适配多种常见 AI 编程工具，包括：

• Claude Code
• OpenAI Codex
• Cursor
• Aider
• GitHub Copilot CLI
• OpenCode
• Cline
• Continue
• Goose
• OpenHands
• Grok CLI
• Kimi CLI

对于 Claude Code、Codex 和 Aider 等工具，可以直接通过 headroom wrap 启动。

Cursor 目前主要采用手动配置代理地址的方式接入。

此外，Headroom 也支持 Python、TypeScript、LangChain、Agno、LiteLLM、Vercel AI SDK 和 MCP 客户端，适合接入已有的 AI 应用或 Agent 系统。

最简单的安装方法

Headroom 要求 Python 3.10 或以上版本。

推荐使用 uv 进行隔离安装：

1

uv tool install --python 3.13 "headroom-ai[all]"

也可以直接使用 pip：

1

pip install "headroom-ai[all]"

安装完成后检查版本：

1

headroom --version

需要注意，npm 版本只是 TypeScript SDK，并不包含 headroom 命令行工具：

1

npm install headroom-ai

因此，想直接使用 headroom wrap、代理服务或 MCP 功能，应该优先安装 Python 版本。

在 Claude Code 中使用

安装完成后执行：

1

headroom wrap claude

Headroom 会启动本地代理，并通过代理启动 Claude Code。

之后，Claude Code 读取代码、运行命令或分析日志时，相关上下文会先经过 Headroom 处理，再发送给模型。

可以使用以下命令检查运行状态：

1

headroom doctor

查看压缩性能：

1

headroom perf

打开节省统计面板：

1

headroom dashboard

在 Codex 中使用

Codex 可以通过下面的命令启动：

1

headroom wrap codex

如果 Codex 无法识别终端里的 headroom 命令，可以先查询完整路径：

1

command -v headroom

然后把返回的绝对路径写入 Codex 的 MCP 配置：

1
2
3

[mcp_servers.headroom]
command = "/你的绝对路径/headroom"
args = ["mcp", "serve"]

这种情况通常不是 Headroom 安装失败，而是 Codex 启动时没有继承当前终端的 PATH 环境变量。

跨 Agent 共享记忆

Headroom 不只是压缩工具，还提供跨 Agent 共享上下文的能力。

例如，你可以让 Claude Code 和 Codex 使用同一个本地记忆存储：

1
2

headroom wrap claude --memory
headroom wrap codex --memory

这样，在 Claude Code 中已经分析过的项目内容，可以被压缩、去重后继续提供给 Codex 使用，减少不同 AI 工具重复读取同一批文件。

Headroom 还提供 headroom learn 功能，可以分析失败的历史会话，并把修正经验写入：

• CLAUDE.local.md
• CLAUDE.md
• AGENTS.md
• GEMINI.md
• GROK.md

这类功能适合长期维护同一个代码库，但自动生成的规则仍然需要人工检查，避免错误经验被持续复用。

Headroom 适合哪些人？

Headroom 更适合以下场景：

• 经常使用 Claude Code、Codex 或 Cursor
• 需要分析大量终端日志和报错信息
• 经常进行大型代码库搜索
• 使用 API 按 Token 付费
• 同时使用多个 AI Agent
• RAG 检索结果较长且重复内容较多
• 希望降低上下文成本和请求延迟

下面这些情况则不一定需要安装：

• 只是偶尔使用网页版 AI 聊天
• 每次任务都很短，上下文内容很少
• 使用的环境不允许启动本地代理
• 已经完全依赖模型厂商自带的上下文压缩
• 项目涉及敏感业务，但尚未完成安全审查

使用前需要注意什么？

1. 最高 92% 不代表每次都能省 92%

92% 是代码搜索和事故排查等特定测试场景的数据。

根据任务类型不同，实际压缩效果可能只有 20%、40%，也可能在结构化日志中达到更高比例。

2. 先在测试项目中验证

代码上下文可能包含函数签名、错误细节、配置字段和依赖版本。

即使 Headroom 支持可逆压缩，也建议先在非关键项目中测试，确认不会遗漏影响判断的重要信息。

3. 本地运行不等于没有安全风险

Headroom 会位于 AI 工具与模型服务之间，能够接触请求内容。

在公司项目或敏感代码环境中使用前，应检查项目源码、依赖、日志保存方式和代理配置。

4. 定期查看节省数据

可以通过以下命令检查实际收益：

1
2

headroom perf
headroom dashboard

不要只因为项目宣传中的最高数字就长期启用。真正有价值的是，它在你的工作流中能否稳定降低 Token，同时保持结果可靠。

总结

Headroom 解决的不是“提示词写得不够好”，而是 AI Agent 工作过程中产生了太多无效上下文。

代码搜索结果、构建日志、历史对话、RAG 数据和工具返回内容，会不断占用上下文窗口，也会增加 API 成本。

Headroom 在这些内容进入模型前进行结构化压缩，并提供可逆内容检索、跨 Agent 记忆和失败经验学习等功能。对于频繁使用 Claude Code、Codex、Cursor 或其他 AI 编程工具的人，它确实值得测试。

但更准确的说法不是“安装后一定节省 92%”，而是：

在日志、搜索结果和大型代码库等高冗余场景中，Headroom 有机会显著减少 Token；最终效果应以自己的项目测试结果为准。

项目地址

• GitHub：https://github.com/headroomlabs-ai/headroom
• 开源协议：Apache License 2.0
• 当前 GitHub Stars：约 62.7K，数据会持续变化