Headroom：给 AI Agent 装上上下文压缩引擎，省 60-95% 的 Token

在与 AI 编程助手打交道时，你有没有遇到过这种场景——工具输出了几千行日志，模型花了大把 token 读完，最后告诉你”没发现问题”？或者在 RAG 场景下，塞进去一堆文档后，对话变得又慢又贵？

Headroom 就是为解决这个问题而生的。它是一个上下文压缩层，在发送给 LLM 之前自动压缩工具输出、日志、RAG 块、文件和对话历史——平均省 60-95% 的 token，但答案质量不变。

项目地址：https://github.com/chopratejas/headroom （38K+ ⭐）

核心特性

多种使用模式

• Library 模式：Python/TypeScript 中直接调用 compress() 函数嵌入应用
• Proxy 模式：headroom proxy --port 8787，零代码改动，任何语言可用
• Agent Wrap：一行命令包装 Claude Code、Codex、Cursor、Aider、Copilot
• MCP Server：提供 headroom_compress、headroom_retrieve、headroom_stats 工具

六大压缩引擎

• SmartCrusher：通用 JSON 压缩，处理数组、嵌套对象、混合类型
• CodeCompressor：AST 感知的代码压缩，支持 Python、JS、Go、Rust、Java、C++
• Kompress-base：HuggingFace 模型，专为 Agent 追踪数据训练
• CacheAligner：稳定前缀让 Anthropic/OpenAI KV 缓存真正命中
• Image 压缩：40-90% 缩减，ML 路由自动选择
• IntelligentContext：基于评分的重要性感知上下文裁剪

跨 Agent 记忆

支持 Claude、Codex、Gemini 等工具共享记忆存储，自动去重。切换工具时上下文不丢失。

可逆压缩 (CCR)

原始内容缓存本地，LLM 需要时通过 headroom_retrieve 找回。压缩仅限传输部分，信息零丢失。

输出 Token 缩减

不光压缩输入，还减少模型输出的废话——去掉”好的，让我看看…”这类开场白、重复代码片段、常规步骤的冗长思考。实测减少约 31% 的输出 token。

安装

pip install "headroom-ai[all]"   # Python 全功能
npm install headroom-ai          # Node/TypeScript

快速上手

方式一：包装你的 Agent

headroom wrap claude   # 包装 Claude Code
headroom wrap codex    # 包装 GitHub Codex
headroom wrap cursor   # 包装 Cursor
headroom wrap aider    # 包装 Aider
headroom wrap copilot  # 包装 Copilot CLI

方式二：作为代理运行

headroom proxy --port 8787
# 然后配置客户端指向 localhost:8787

方式三：Python 库内联使用

from headroom import compress

compressed = compress(messages, model="kompress-v2-base")

真实效果

在 GSM8K、TruthfulQA、SQuAD v2、BFCL 等标准基准上，准确性保持 ±0～3%，几乎零损失。

与 OpenClaw 的兼容

Headroom 官方支持 OpenClaw，直接安装为 ContextEngine 插件：headroom wrap openclaw。这意味着我们日常的 Agent 任务也可以享受 token 节省。

与同类工具对比

结语

Headroom 是一个实用到有点”反直觉”的项目——压缩 60-95% 的输入数据，答案质量却不变。对于每天大量调用 LLM API 的开发者来说，价值非常直接：省钱、省时、不降质。本地运行、数据不出机器、Apache 2.0 开源，值得一试。