headroomlabs-ai/headroom · 上手攻略

  • 仓库：headroomlabs-ai/headroom
  • 链接：https://github.com/headroomlabs-ai/headroom
  • 分类：agent, rag, llm-infra
  • 作者：Tom
  • 更新：2026-07-05

这是什么

Headroom 是一个上下文压缩层（context compression layer），运行在 AI 编码助手和 LLM 提供商之间，把 tool 输出、日志、文件内容、RAG 检索结果、对话历史等压缩后再发给 LLM，Token 减少 60–95%，答案质量基本不变。

它的核心定位是：在你不动代码的前提下，给任何 AI 编码助手省 Token。支持三种使用形态——Python/TypeScript 库、HTTP 透明代理、MCP Server，兼容 Claude Code、Codex、Cursor、Aider、Copilot CLI 等 15+ 平台。

官方提供性能数据：100 条生产日志压缩后 10,144 → 1,260 tokens（-87.6%），同一 FATAL 错误仍然被正确识别。

解决什么问题

  1. Token 费用爆炸：Claude Code / Opus 级模型输入 Token 费用高，一个中等规模项目的 tool 输出动不动就数万 Token。Headroom 把这些压缩到原来的几分之一。
  2. 上下文窗口塞满：RAG 检索结果、GitHub issue triage、代码库探索等场景，原始内容动辄几十 KB。压缩后同样的上下文窗口能容纳更多有效信息。
  3. 多 Agent 共享记忆：Claude Code 和 Codex 之间的记忆无法互通，Headroom 提供 Cross-agent memory 让两个 Agent 共享压缩后的上下文。
  4. 输出 Token 也收费：不只是压缩输入，Headroom 还通过 verbosity steering 和 effort routing 减少模型输出的废话（"Great, let me..." 开场白、深思熟虑的标准步骤等），输出 Token 费用是输入的 5 倍（Opus 模型）。
  5. 可逆压缩：压缩不是丢弃，原文缓存在本地 CCR（Compress-Cache-Retrieve）store，模型随时可通过 headroom_retrieve 工具取回原始内容。

快速安装

环境要求

  • Python 3.10+
  • pip 或 uv

安装

# Python 包（含 CLI）
pip install "headroom-ai[all]"

# TypeScript SDK（仅库，无 CLI）
npm install headroom-ai

⚠️ [all] 包含所有扩展：proxy, mcp, ml, code, memory, vector（HNSW 向量索引，需 C++ 工具链）, relevance, image, agno, langchain, evals。若不需要全部，可安装子集如 [proxy,mcp,ml]。

验证安装

headroom doctor   # 健康检查
headroom perf     # 性能测试
headroom dashboard  # 实时节省仪表盘（需先启动 proxy）

核心用法

模式一：透明 Proxy（零代码改动，推荐）

启动本地代理，所有请求自动走 Headroom 压缩：

headroom proxy --port 8787

然后把 AI 助手或应用的 API 请求发到 http://localhost:8787，Headroom 在后台转发给真正的 LLM 提供商并压缩请求/响应。

配合 Claude Code：

# wrap 命令：自动修改 Claude Code 配置、启动 proxy、注入 token
headroom wrap claude

# 撤销
headroom unwrap claude

配合其他 Agent（wrap）：

headroom wrap codex      # Codex
headroom wrap copilot    # GitHub Copilot CLI
headroom wrap cursor     # Cursor（需手动配置 base URL）
headroom wrap aider      # Aider
headroom wrap opencode   # OpenCode
headroom wrap cline      # Cline
headroom wrap continue   # Continue
headroom wrap goose      # Goose
headroom wrap openhands  # OpenHands
headroom wrap openclaw   # OpenClaw（作为 ContextEngine 插件安装）

配合 Copilot CLI 订阅用户：

headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o

对于企业版 GitHub Copilot（GHES），先设置域名再 wrap：

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com
headroom wrap copilot

模式二：Python 库（内联使用）

from headroom import compress

result = compress(messages, model="gpt-4o")
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

response = client.messages.create(
    model="gpt-4o",
    messages=result.messages,
)

TypeScript：

import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'gpt-4o' });
console.log(`Saved ${result.tokensSaved} tokens (${(result.compressionRatio * 100).toFixed(0)}%)`);

模式三：SDK 集成（各框架）

# LangChain
from langchain.chat_models import ChatAnthropic
from headroom.langchain import HeadroomChatModel

llm = HeadroomChatModel(ChatAnthropic())

# Agno
from headroom.agno import HeadroomAgnoModel

model = HeadroomAgnoModel(your_model)

# LiteLLM
from headroom.callbacks import HeadroomCallback

litellm.callbacks = [HeadroomCallback()]

# Vercel AI SDK
import { wrapLanguageModel, headroomMiddleware } from 'headroom-ai';
const model = wrapLanguageModel({ model, middleware: headroomMiddleware() });

模式四：MCP Server

headroom mcp install   # 注册 headroom_compress / headroom_retrieve / headroom_stats

MCP client（如 Claude Desktop）通过标准 MCP 协议调用这些工具。

Cross-agent Memory（跨 Agent 共享上下文）

from headroom import SharedContext

ctx = SharedContext()
ctx.put("user_context", compressed_summary)  # 写入
retrieved = ctx.get("user_context")          # 读取，自动去重

输出 Token 节省（Output Shaping）

默认关闭，在 proxy 模式下启用：

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

效果： - Verbosity steering：追加"be terse, don't restate context"到 system prompt 末尾（prompt cache 仍然命中）。 - Effort routing：模型恢复执行（tool result 返回后继续）时，自动降低思考力度；新问题和报错保持全力度。

自动学习用户偏好：

headroom learn --verbosity        # 预览（dry run）
headroom learn --verbosity --apply  # 应用到 proxy

查看节省数据：

headroom output-savings
# Reduction: 31.7% (95% CI 27.7% … 35.7%) [estimated]

# 若要实测（留 10% 不压缩作为对照组）：
export HEADROOM_OUTPUT_HOLDOUT=0.1
headroom dashboard   # 面板会显示 measured vs estimated

压缩技术细节

内容类型 压缩方式 典型节省
JSON 数组（tool 输出） SmartCrusher 统计分析，保留错误/异常/边界 70–90%
源代码（Python/JS/Rust/Go/Java/C++） CodeCompressor AST 感知，保留签名折叠函数体 40–70%
构建/测试日志 保留失败和错误，去掉通过的冗余行 80–95%
搜索结果 按相关性排序，保留 top 匹配 60–80%
纯文本 Kompress-v2-base（HF 模型，训练于 agent traces） 30–50%
Git diffs 保留变更 hunks，去掉未改动上下文 40–60%
图片 ML 路由器选择最优 resize/quality 组合 40–90%

CCR（可逆压缩）： 原文缓存在本地，模型通过 headroom_retrieve 工具在需要时取回，TTL 可配置。模型不主动调用就不取回，不浪费。

CacheAligner： 稳定请求前缀，使 Anthropic/OpenAI 的 KV Cache 能够真正命中（否则每次请求前缀略有不同导致 cache miss）。

典型适用场景

  1. 重度 Claude Code / Opus 使用者：Token 费用是大头，压缩 60–80% 直接等于账单打折。
  2. SRE / DevOps 场景：调试日志几百条、压缩后模型仍能准确定位 FATAL 错误（实测 10k→1.2k tokens）。
  3. GitHub Issue Triage：大量 issue 列表压缩后仍保留关键信息，节省 73% tokens。
  4. 多 Agent 并行工作：Claude Code + Codex 同时跑一个项目，Cross-agent memory 保证上下文不重复。
  5. RAG 管道优化：RAG 检索结果（通常是 5–10 个 chunks）经过压缩再喂给模型，context 更干净。
  6. 构建/测试日志分析：CI 日志动辄几十 MB，压缩后 LLM 仍能准确发现 regression。
  7. 输出 Token 优化：代码生成类任务（Claude Opus 输出费用高），verbosity steering 减少废话输出。

坑与注意

  1. headroom: command not found： - 只装了 npm install headroom-ai（TypeScript SDK）而没有装 PyPI 包，TypeScript SDK 不含 CLI。 - 解决：pip install "headroom-ai[all]" 安装 PyPI 包。

  2. Proxy 环境变量热更新： - headroom wrap 现在通过 loopback POST /admin/runtime-env 热同步环境变量，无需重启 proxy 就能让新设置生效（无 cold start，无请求丢失，无 cache 清空）。但如果是 headroom wrap 重用已有 proxy，则环境在启动时被 snapshot 了，之后 export 的变量不会生效——这种情况下需重启 proxy。

  3. macOS Copilot CLI 认证： - macOS + Keychain 的 auth reuse 已有冒烟测试；Windows Credential Manager、Linux Secret Service/Docker token injection 路径已实现但尚未完全验证。Docker/CI 场景建议显式传递 GITHUB_COPILOT_TOKEN 而非依赖 keychain。

  4. 向量索引（[vector]）需要 C++ 工具链： - HNSW 向量索引后端需要编译，不在 [all] 默认包含的范围内，如需该功能需单独安装。

  5. Python 3.13 与 Leiden 扩展： - Leiden 社区检测仅支持 Python < 3.13，Python 3.13 用户无法使用该功能。

  6. 输出 Token 节省是估计值： - 输出节省是反事实估计（模型实际写了什么 Headroom 无法看到），报告诚实给出 95% CI 范围。若要实测，用 HEADROOM_OUTPUT_HOLDOUT=0.1 留对照组。

  7. Cursor 手动配置： - Cursor wrap 后需要手动在 Cursor 设置中配置 proxy base URL（非自动注入）。

  8. 版权与商用： - Headroom OSS 是 Apache-2.0，库和 proxy 功能免费；企业级共享部署、集中管理、SSO、仪表盘等由 headroomlabs.ai 提供商业支持。

与同类对比

维度 Headroom lmql GPTCache Letta
核心能力 请求压缩 + 可逆缓存 LLM 约束解码 相似请求缓存 Agent 记忆管理
Token 节省 60–95%（实测 benchmark） 程序化查询省 Token 相同 Query 缓存命中 记忆压缩
透明 Proxy ✅ 零代码改动 ❌ ✅ ❌
多 Agent 共享 ✅ Cross-agent memory ❌ 部分 ✅ 但主要是 Letta 内
输出压缩 ✅ Output Shaping ❌ ❌ ❌
MCP 支持 ✅ ❌ ❌ ✅
平台覆盖 15+ Agent 通用 Python 通用 Letta Server

Headroom 的差异化：原生 Agent 场景 + 透明 Proxy + 输出压缩。GPTCache 主要针对相同 Query 的重复请求，Letta 侧重 Agent 长期记忆管理，而 Headroom 把压缩做到了对话内每次请求层，覆盖 tool 输出、日志、代码、RAG chunks 等所有输入类型。

一句话推荐结论

如果你每天开着 Claude Code 或其他 AI 编码助手工作，Headroom 是投入产出比最高的效率工具——一个命令启动 proxy，60–95% Token 节省，答案质量基本不变，直接反映在你的 API 账单上。