夜雨聆风Headroom 是什么？ Headroom 是一款本地运行的 AI 代理上下文压缩工具，通过智能压缩算法将发送给 AI 的 token 数量减少 60-95%，让你的 Claude Code 或 Codex 订阅计划用更久。完全免费开源，支持命令行使用。
关键数据：
• 🌟 GitHub Stars: 51,900+（仓库链接[1]） • 📦 当前版本：v0.27.0 • ⚖️ 许可证：Apache-2.0（完全免费开源） • 🧠 核心特性：SmartCrusher（JSON 压缩）——智能压缩 JSON 格式的工具输出和 API 响应 • 🔧 核心特性：CodeCompressor（AST 压缩）——语法树感知的代码压缩，支持 Python/JS/Go/Rust/Java/C++ • 📦 核心特性：Kompress-base（文本压缩）——基于 HuggingFace 训练的专用压缩模型 • 🔄 核心特性：CCR（可逆压缩）——原始内容本地缓存，需要时可恢复 • 🌐 核心特性：跨代理内存——Claude、Codex、Gemini 等多代理共享上下文记忆
你是否遇到过这样的情况：使用 Claude Code 或 Codex 时，发现 5 小时额度很快就用完了？或者 AI 的响应变慢了，因为上下文被大量日志和工具输出填满？
这就是 Headroom 要解决的问题。它能在 AI 读取内容之前进行智能压缩，让你在不牺牲回答质量的前提下，让同样的订阅计划用更久。
在开始使用 Headroom 之前，你需要准备：
• Python 3.10+ • 一个 AI API 密钥（如 Anthropic、OpenAI、DeepSeek、GLM 等） • 基本的命令行操作知识
安装 Headroom
Headroom 提供多种安装方式，选择最适合你的：
Python 用户：
pip install "headroom-ai[all]"Node.js/TypeScript 用户：
npm install headroom-ai💡 提示：
[all]安装所有可选功能。如果你只需要特定功能，可以安装对应的额外包：[proxy]、[mcp]、[ml]、[code]、[memory]等。
使用场景：看看你属于哪类用户
场景一：AI 开发者
你在代码中直接调用 AI API，或者集成到自己的工具中。使用 Headroom 可以：
• 在代码中直接调用压缩功能 • 启动本地代理，自动压缩所有请求 • 一键包装现有 AI 工具 • 集成到 LangChain 等框架中
场景二：命令行用户
你使用 Claude Code、Codex 等 AI 编程助手进行日常开发。使用 Headroom 可以：
• 一键包装你的 AI 工具，自动启用压缩 • 无需修改代码，零配置使用 • 查看详细的压缩效果统计
详细使用教程
模式一：库模式集成
在你的 Python 或 TypeScript 代码中直接使用：
from headroom import compress# 压缩消息compressed = compress(messages, model="claude-sonnet-4-20250514")import { compress } from 'headroom-ai';// 压缩消息const compressed = await compress(messages, { model: 'claude-sonnet-4-20250514' });模式二：代理模式
启动一个本地代理，所有请求自动压缩：
headroom proxy --port 8787模式三：一键包装模式
直接包装你正在使用的 AI 编程助手：
headroom wrap claude # 包装 Claude Codeheadroom wrap codex # 包装 Codexheadroom wrap aider # 包装 Aiderheadroom wrap copilot # 包装 Copilot CLI💡 提示：一键包装模式会自动配置代理并启动你的 AI 工具，无需手动设置。对于 Cursor，需要手动配置代理设置。
验证压缩效果
运行性能测试，查看压缩效果：
headroom perf这将运行一系列测试，展示 Headroom 的压缩能力。
实际效果：能省多少？
根据官方基准测试：
| 92% | |||
| 92% | |||
| 73% | |||
| 61% | |||
| 47% |
典型工作负载可节省 60-95% token，这意味着同样的订阅计划可以完成更多任务。
准确性保持
Headroom 在压缩的同时保持了回答质量：
高级功能
使用可逆压缩（CCR）
Headroom 的独特功能是 可逆压缩（CCR），原始内容会被缓存，需要时可以恢复：
from headroom import compress, retrieve# 压缩compressed = compress(messages)# 如果 LLM 需要原始内容，可以通过工具调用 retrieve# LLM 会自动判断是否需要恢复原始内容启用跨代理内存
如果你使用多个 AI 代理（如 Claude 和 Codex），可以启用跨代理内存共享：
# 启用内存功能headroom wrap claude --memory# Codex 会自动共享 Claude 的内存headroom wrap codex --memory输出 token 节省
Headroom 不仅可以压缩输入 token，还能减少输出 token：
export HEADROOM_OUTPUT_SHAPER=1 # 默认关闭headroom proxy --port 8787这会通过 verbosity steering 和 effort routing 减少模型"写回来"的冗余内容。
集成到 LangChain
如果你使用 LangChain，可以轻松集成：
from headroom.integrations import HeadroomChatModelfrom langchain_anthropic import ChatAnthropicllm = HeadroomChatModel(ChatAnthropic(model="claude-sonnet-4-20250514"))response = llm.invoke("你的问题")使用 MCP 工具
Headroom 提供 MCP 服务器，可以在任何 MCP 客户端中使用：
headroom mcp install这将安装 headroom_compress、headroom_retrieve 和 headroom_stats 三个工具。
常见问题
Q: Headroom 会降低 AI 的回答质量吗？A: 不会。Headroom 的压缩算法经过精心设计，在标准基准测试中保持了原始准确率。例如在 GSM8K 数学测试中，压缩前后准确率完全一致（0.870）。
Q: Headroom 需要联网吗？A: 不需要。Headroom 完全在本地运行，你的数据不会发送到任何外部服务器。唯一的网络请求是下载压缩模型（首次使用时）。
Q: 支持哪些 AI 模型/代理？A: Headroom 支持所有主流 AI 代理，包括 Claude Code、Cursor、Codex、Aider、Copilot CLI 等。任何 OpenAI 兼容的客户端都可以通过代理模式使用。
Q: 压缩后的 token 数量能减少多少？A: 典型工作负载可节省 60-95% token，具体取决于输入内容的类型和大小。
Q: Headroom 和 RTK 有什么区别？A: RTK 主要压缩 CLI 命令输出，而 Headroom 压缩所有上下文（工具输出、RAG 结果、日志、文件、对话历史）。Headroom 内部也集成了 RTK 作为 shell 输出重写工具。
Q: Headroom 支持 Docker 部署吗？A: 支持。可以使用 docker pull ghcr.io/chopratejas/headroom:latest 拉取镜像，适合服务器环境或 CI/CD 流程。
Q: 输出 token 也能节省吗？A: 可以。Headroom 支持输出 token 减少，通过 verbosity steering 和 effort routing 减少模型"写回来"的冗余内容，设置 HEADROOM_OUTPUT_SHAPER=1 即可启用。
总结
Headroom 是一款强大的 AI 代理上下文压缩工具，它通过本地运行的智能压缩算法，让你的 AI 订阅计划用更久。
关键特性：
• 60-95% 的 token 节省，同样的计划完成更多任务 • 完全本地运行，数据安全 • 完全免费开源，无需付费 • 支持 Claude Code、Codex 等主流 AI 工具 • 可逆压缩，原始内容可恢复 • 跨代理内存共享
现在就尝试安装 Headroom，体验 AI 开发的新范式吧！
引用链接
[1] 仓库链接: https://github.com/headroomlabs-ai/headroom