用 Headroom 把 Agent 的 token 账单压下来：wrap / proxy / SDK / MCP 四路线实操

安装这一步有两个容易踩的点。一是命令行的载体：headroom 这个命令随 PyPI 包发布，官方推荐用 uv 装成一个自包含的隔离环境（指定 Python 3.13）；直接 pip 安装也能拿到同一个命令行。而 npm 上的同名包是 TypeScript SDK，import 进去就能用，但它不带命令行。二是系统与 wheel 的兼容：在 macOS 上如果你的默认 python3 比当前 wheel 集还新，请按官方建议显式指定 3.13，否则可能装不上或装错组合。装完之后，先跑体检命令确认链路通了，再进入使用环节。

# 推荐：自包含命令行环境
uv tool install --python 3.13 "headroom-ai[all]"

# 或者：直接 pip（同样带 headroom 命令）
pip install "headroom-ai[all]"

# 按需要装 extras
pip install "headroom-ai[proxy]"       # 代理服务器 + MCP 工具
pip install "headroom-ai[ml]"          # ML 压缩（Kompress，需 torch）
pip install "headroom-ai[langchain]"   # LangChain 集成
pip install "headroom-ai[agno]"        # Agno 集成

# TypeScript 只装 SDK（不带命令行）
npm install headroom-ai

# 装完先体检：确认分派链路可用
headroom doctor

# 想知道压缩花了多少时间
headroom perf

# 想看实时省了多少（需先跑着代理）
headroom dashboard

最省事的落地方式是 wrap：一条命令把某个编码 Agent 拉起来，它会在背后顺手带起本地代理并把 Agent 的流量指向那里，之后这个 Agent 的每次文件读取、搜索结果与工具输出都会先过一遍压缩再发往模型。官方支持的 targets 包括 Claude Code、OpenAI Codex、Cursor、Aider、Copilot 等，不想用了就用 unwrap 还原，属是可逆操作。需要注意的是，wrap 不是一个纯粹的转发器：它会顺带安装语义代码导航能力，作为本地作用域的 MCP 服务注册给被包装的项目，目的是让 Agent 用更少token 定位到代码位置；你可以把作用域放大到用户级，也可以完全不要这层。

# 接管某个编码 Agent
headroom wrap claude        # Claude Code
headroom wrap codex         # OpenAI Codex CLI
headroom wrap cursor        # Cursor
headroom wrap aider         # Aider

# 还原（可逆）
headroom unwrap claude

# 调整随附的语义代码导航能力的作用域
headroom wrap claude --code-memory-scope user   # 所有项目可用
headroom wrap claude --code-memory none         # 完全不装

# 一条命令做托管式本地部署 + Agent 配置
headroom deploy

如果你不想包装某个具体工具，或者要给自己写的程序加上压缩，代理模式是最干净的形态：起一个本地监听端口，把客户端的 base URL 指过去，应用代码完全不用动。它兼容 OpenAI 兼容接口与 Anthropic 接口，也支持把后端直接指向 Bedrock、Vertex AI、Azure OpenAI 或 OpenRouter，走 LiteLLM 时还能覆盖上百家供应商。这种形态特别适合接进已有的 CI 或后端服务——不用改任何调用代码，把环境变量换成代理地址就行。

# 起本地代理（默认端口 8787）
headroom proxy

# 指定云后端
headroom proxy --backend bedrock     --region us-east-1
headroom proxy --backend vertex_ai   --region us-central1
headroom proxy --backend azure
headroom proxy --backend openrouter

# 把现有客户端指过来（应用代码零改动）
ANTHROPIC_BASE_URL=http://localhost:8787 claude
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

代理模式还能顺手解决一个常被忽视的成本项：前缀缓存。它的 CacheAligner 会标记那些会导致 provider KV 缓存失效的易变内容（比如时间戳、随机 ID），让前缀尽量稳定，从而拿到命中缓存时的折扣价。很多人只盯着 token 数而忽略了这部分收益，实际账单上的差距有时比压缩本身还明显。

自己写 Agent 循环的场景（也就是不与某种框架耦合的情况）推荐直接用 SDK：在调用模型之前把消息数组过一遍 compress()，拿到压缩后的消息与省下的 token 统计，再照常发给供应商。这种做法的优势是粒度可控——你可以只对「工具结果」这个角色的消息做压缩，把系统提示与用户指令原样保留；也可以按预算决定是否这一轮要压。TypeScript 侧形态几乎一致，可以接进 Vercel AI SDK、OpenAI Node SDK 或 Anthropic TS SDK。

from headroom import compress
from openai import OpenAI

client = OpenAI()
messages = [{"role": "user", "content": "分析这份结果"}]

# 在发往模型之前压缩一次
result = compress(messages, model="gpt-4o")
response = client.chat.completions.create(
    model="gpt-4o",
    messages=result.messages,
)
print(f"省下 {result.tokens_saved} tokens（压缩率 {result.compression_ratio:.0%}）")

# TypeScript 侧：同样的形态
# npm install headroom-ai
import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'claude-sonnet-4-5-20250929' });
console.log('省下 ' + result.tokensSaved + ' tokens');
// 之后把 result.messages 交给任意 LLM 客户端

# 走 LiteLLM 时，一个 callback 覆盖上百家供应商
import litellm
from headroom.integrations.litellm_callback import HeadroomCallback

litellm.callbacks = [HeadroomCallback()]

装成 MCP 服务之后，任何 MCP 客户端都能拿到三个工具：compress（压缩一段内容）、retrieve（把之前压掉的内容按标识符取回原文）、stats（看这一路压了多少、省了多少）。这条路线与前面几条并不冲突——包装与代理是「自动全量压缩」，MCP 是「按需手动压缩」，适合那种「大部分时间不需要、偶尔冒出一坨巨大数据块」的场景。三个工具要一起装，模型才知道压掉的东西还能取回来，否则它只会以为信息丢了。

# 安装 MCP 服务，随后照常启动你的客户端
headroom mcp install && claude

# 暴露的三个工具
# headroom_compress   压缩一段内容，返回一个可取回的句柄
# headroom_retrieve   按句柄取回原文（CCR 可逆压缩）
# headroom_stats      查看压缩量、节省量与成本估算

可逆性（官方叫 CCR）是这套方案里最值得强调的一点：压缩是激进的，但它会把原文存在本地缓存里，同时给模型一个检索工具，需要细节时按需取回原文——也就是说，压缩掉的并不是被扔掉的信息，而是「延迟加载」的信息。这也是它与朴素折叠、粗暴截断最本质的区别：后者一旦执行，模型再也拿不回那部分内容，而前者保留了可能性。

要不要上这套东西，取决于你的 payload 长什么样。官方用真实 MCP 输出格式构造的场景里，代码搜索一百条结果的压缩幅度约两成多，而 SRE 事故排查这种重复日志为主的任务能到五成以上，某些高度重复的 JSON 数组与日志行在基准脚本里能打掉九成；反过来，散文明文与本来就紧凑的输出压缩幅度很小，日常短对话几乎看不到变化。官方也很坦诚：压缩率随 payload 的重复程度走，别拿别人的 benchmark 当自己的收益，跑一条自家真实流量的统计才是决策依据。

# 用它自己的能力测你的真实流量，而不是看第三方数字
headroom savings        # 输出你自己链路上的实际节省
headroom dashboard      # 实时看板（需先起代理）
headroom perf           # 压缩耗时（官方口径：万 token 级 JSON 亚毫秒）

上线前还有两件事。其一是隐私开关：默认会有一个匿名遥测信标，上报压缩比、计数器、供应商与模型 ID、操作系统与架构这类聚合指标（官方声明不含提示词、回答、代码与文件路径），在意的话用下面任何一种方式关掉。其二是它自带的两个「越界」功能要不要开：跨 Agent 共享记忆会把同一份记忆 store 暴露给多个 Agent 并自动去重，失败学习会去翻过去的失败会话、提炼成修正规则写进 CLAUDE.local.md（默认，通常已被 gitignore）或其他 Agent 规则文件——这些都很诱人，但它们会改动你的 Agent 记忆文件，团队里使用时需要先约定由谁来维护那份文件。

# 关掉遥测（任一即可）
export HEADROOM_TELEMETRY=off
export HEADROOM_BEACON=off
export DO_NOT_TRACK=1
export HEADROOM_OFFLINE=1

# 失败学习：从历史会话里提炼修正写进规则文件
headroom learn          # 默认写 CLAUDE.local.md，可改 CLAUDE.md / AGENTS.md / GEMINI.md