本地压缩上下文降低 Claude Code 成本

dev.to · AI#Claude Code#上下文压缩#成本优化

Editor brief · 编辑速览

Headroom 在请求发送至 Anthropic 前压缩日志、重复文件内容和工具输出，据称长会话可减少 15%—81% 的 token 用量。它支持零配置包装 Claude Code，并提供统计功能验证实际节省。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

Headroom 会在冗余上下文抵达 Anthropic API 之前进行压缩，在长会话中可将 token 用量降低 15%～81%。

使用 headroom wrap claude 即可零配置节省 token，再通过 headroom_stats 衡量实际效果。

问题所在：Claude Code 每一轮都会重新发送全部内容

Claude Code 在不同 API 调用之间是无状态的。你每发送一条消息，它都会将整个对话重新上传到 Anthropic，其中包括所有工具输出、读取的文件以及 MCP 元数据。在长会话中，这些重复发送的数据会占据 token 账单的大头。Prompt caching 能缓解这一问题（Anthropic 对稳定前缀提供约 90% 的缓存读取折扣），但工具结果和动态变化的 JSON payload 会不断破坏缓存，导致这些内容再次按全价计费。

Headroom 是一个运行在本地的中间件层，位于 Claude Code 与 Anthropic API 之间。它会拦截向外发送的 payload，并在数据离开你的机器之前，移除或压缩其中的冗余内容，例如日志、搜索结果转储和重复读取的文件。当前版本是 0.33.0（2026 年 7 月 29 日发布）。

这种压缩可以通过 CCR（Compress-Cache-Retrieve，压缩—缓存—检索）机制还原：Headroom 使用内容哈希将原始内容保存在本地，向模型提供更短的表示形式，并允许 Claude 在一小时的 TTL 内通过 headroom_retrieve 获取完整原文。因此，你并不会丢失信息，只是将其延后加载。

符合实际的节省幅度（别轻信宣传）

Headroom 的 README 声称，面向 coding agent 时整体可节省 15%～20%。一位独立实践者报告称，使用一个月后，实际节省幅度约为 26%。请将厂商提供的数据视为上限，并根据自己的工作负载进行测量。

如何将 Headroom 接入 Claude Code

Python 3.10+ 或 Node 18+

无需构建步骤（已为所有主流平台提供预构建 wheel）

你的 Anthropic API key 不会受到影响——Headroom 在 localhost 上运行

# Python
pip install "headroom-ai[all]"

# Node
npm install headroom-ai

验证：headroom --version 应输出 0.33.0。

让 Claude Code 流量经过 Headroom 的三种方式

方式 A——包装 Agent（无需修改代码）：

headroom wrap claude

Headroom 会将 Claude Code 作为子进程启动，并在进程内压缩每个 payload。如果你只想省 token，不想操心配置，这是最快的方式。

方式 B——透明本地代理：

headroom proxy --port 8787
# Then in your shell:
export ANTHROPIC_BASE_URL=http://localhost:8787
claude

所有流量都会经过 Headroom，无需修改源代码或配置。

方式 C——MCP server（按内容块控制）：

headroom mcp install

该方式会将 headroom_compress、headroom_retrieve 和 headroom_stats 暴露为工具。Claude 可以按需压缩特定内容块——控制粒度更高，但由 Claude 决定何时调用。

哪些内容会被压缩，哪些不会

ContentRouter 会自动检测内容块类型，并将其交给专用压缩器处理：

JSON 使用 SmartCrusher
源代码使用支持 AST 感知的 CodeCompressor（Python、JS/TS、Go、Rust、Java、C/C++）——需主动启用，默认关闭
叙述性文本使用 Kompress-v2-base（拥有 1.49 亿参数的抽取式模型）

Headroom 会跳过以下内容，不进行压缩：

少于约 300 个 token 的消息（处理开销高于节省量）
图片、grep/搜索结果和 system prompt

接入后可以尝试什么

先进行测量：调用 headroom_stats（MCP 工具），查看每轮的压缩率和累计 token 差值。

运行 headroom learn：它会离线分析失败案例，读取过去的 transcript，并将提炼出的结论写入 CLAUDE.md——对话过程中不会产生 token 成本。

调优 CacheAligner：通过配置让更多前缀保持稳定，在压缩之外进一步享受 Anthropic 约 90% 的缓存读取折扣。

共享语料库：如果你同时运行 Claude 和 Codex，Headroom 会对两个 Agent 之间重叠的上下文进行去重。

通过代理接入，启用 headroom_stats，完整运行一次真实会话，然后再判断 headroom learn 和 CacheAligner 调优是否值得投入配置成本。收益主要集中在耗时较长、频繁使用工具的会话中——如果你的会话都很短，可以跳过 Headroom。

最初发布于 gentic.news。

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。