Headroom 使用指南:从安装到实际省 token 的完整配置

你每天用 Claude Code 或 Cursor，token 账单上的大头不是你打的字，而是工具输出。一次 git log 返回几百行，一次 RAG 检索塞十几个文档块——这些全按原样发给 LLM。

Headroom 在 agent 和 LLM 之间插了一层压缩，把这类内容压到原来的 5-40%。下面拆解它的三种主要接入方式，每种都附上实际配置和踩坑点。

项目卡片

项目：Headroom^[1]
状态：v0.24.0 / 21,500+ stars / 日均更新，Python + Rust 双引擎
一句话判断：本地运行的 AI 上下文压缩层，支持 wrap/proxy/SDK/MCP 四种接入，60-95% token 节省且可逆

方式一：headroom wrap——一行命令接入

日常用 Claude Code、Codex、Cursor 或 Aider 的话，这是最省事的方式。一行命令，不用改配置文件：

pip install "headroom-ai[all]"
headroom wrap claude

这条命令做了四件事：启动本地代理（默认端口 8787）、配置上下文工具（默认用 RTK）、设置环境变量把 LLM 请求路由到代理、然后启动 Claude Code。

其他 agent 同理：

headroom wrap codex        # OpenAI Codex CLI
headroom wrap aider        # Aider
headroom wrap cursor       # Cursor（打印配置，粘贴到设置里）

几个实用参数：

--port 9999：指定代理端口
--no-context-tool：跳过 RTK 上下文工具
-- --model opus：两个 -- 之后是传给 agent 自身的参数

headroom wrap cursor 比较特殊——它不会直接启动 IDE，而是打印一段 OpenAI 兼容的配置，你需要手动粘贴到 Cursor 设置的 openai.baseURL 字段里。注意 Cursor 本身不支持 CLI 启动，所以 Headroom 只能走配置注入这条路。

方式二：proxy 模式——不改代码

agent 不在 wrap 支持列表里？或者你的应用直接调 OpenAI/Anthropic API？proxy 模式更合适。

headroom proxy --port 8787 --memory

启动后，把你的 LLM 请求指向本地代理即可：

# Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# 任何 OpenAI 兼容客户端
OPENAI_BASE_URL=http://localhost:8787/v1 python my_app.py

--memory 参数启用跨会话记忆，SQLite + HNSW 向量存储，不同 agent 之间共享。如果不需要这个功能，去掉就行。

proxy 模式对应用完全透明，你的代码不需要任何修改。内部走的是 ASGI 服务器，同时支持 Anthropic 原生格式和 OpenAI 兼容格式。Headroom 的 ContentRouter 会自动识别内容类型——JSON 走 SmartCrusher，代码走 CodeCompressor（基于 tree-sitter 的 AST 感知），纯文本走 Kompress-base 模型。

几个值得注意的配置：

headroom proxy --mode token --budget 10.00    # 限制日花费
headroom proxy --code-aware                      # 启用 AST 感知代码压缩
headroom proxy --learn                           # 从流量中学习失败模式

--mode token 按压缩 token 数优化，--mode cache 按缓存命中率优化（稳定前缀，帮助 provider KV cache 命中）。默认是 token 模式。

方式三：SDK 内嵌——精细控制

在自己的 Python 应用里调 LLM，SDK 给你最大控制力。

from headroom import compress

# 最简用法——三行代码
messages = [
    {"role": "user", "content": "分析这段日志"},
    {"role": "tool", "content": huge_log_output},
]
result = compress(messages, model="claude-sonnet-4-5-20250929")
# result.messages  → 压缩后的消息
# result.tokens_saved  → 节省的 token 数

配合 Anthropic SDK：

from anthropic import Anthropic
from headroom import compress

client = Anthropic()
compressed = compress(messages, model="claude-sonnet-4-5-20250929")
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    messages=compressed.messages,
)

compress() 的 CompressConfig 提供几个关键参数：

compress_user_messages：默认 False，编码 agent 场景保持默认即可；RAG 场景设为 True
target_ratio：Kompress 模型的保留比例，0.5 保守，0.2 激进，None 让模型自己决定
protect_recent：保留最近 N 轮不压缩，默认 4
min_tokens_to_compress：低于此阈值的消息跳过压缩，默认 250

针对日志和搜索结果的激进压缩：

result = compress(
    messages,
    model="gpt-4o",
    target_ratio=0.2,        # 只保留 20%
    protect_recent=0,        # 全部压缩
    compress_user_messages=True,
)

更多用法：MCP、learn 和可逆压缩

如果你用 Claude Code 订阅版（没有 API key），可以用 MCP 接入：

headroom mcp install

安装后 Headroom 注册为 Claude Code 的 MCP server，暴露 headroom_compress、headroom_retrieve、headroom_stats 三个工具。这里的 headroom_retrieve 是 CCR（Compress-Cache-Retrieve）机制的关键——压缩后的内容用 <<ccr:HASH>> 哈希标记代替原文，原文存在本地。LLM 需要时可以调 retrieve 拿回来，压缩是可逆的。

headroom learn --apply 是另一个有意思的功能：扫描当前项目的 agent 会话记录，用 LLM 分析失败模式（走错的路、漏装的模块、重复的尝试），把纠错建议自动写入 CLAUDE.md / AGENTS.md。默认 dry-run，加 --apply 才写入，建议先看看输出再决定。

怎么选接入方式

三种方式的取舍很简单：

日常用 Claude Code / Codex：headroom wrap，最省事
用自己的应用调 API：proxy 或 SDK，看你愿不愿意改代码
Claude Code 订阅用户：headroom mcp install，不需要 API key

我的建议：先装上跑一天，用 headroom perf 看实际 token 节省数据，再决定要不要长期用。压缩全程本地执行，数据不出你的机器。

这里会继续拆真实可用的开发者工具：少讲概念，多看入口、成本和坑点。你只需要判断一件事——它值不值得放进自己的工作流。

引用链接

[1]Headroom: https://github.com/chopratejas/headroom