Claude API 用量翻 4 倍：Headroom MCP 省錢實戰指南（2026-06-04）

在真实仓库上跑 Claude Code 的獨立開發者都懂：每次 grep、测试日志、MCP 工具回传都会回到上下文——而 Anthropic 按进出 Token 計費。Headroom（Apache 2.0，截至 2026 年中 GitHub 1 萬+ Star）在请求模型前于本地压缩 工具输出、日志、文件与 RAG 片段，公开 workload 显示 少 60–95% Token，README 演示中在日志里找 FATAL 可从 10,144 → 1,260 Token 且声称答案一致。

本文是 headroom wrap claude 與 MCP 服務 的真實帳單數學 + 安裝指南——不是取代 Claude 的炒作，而是別再為已看過的 stderr 巨塊付全價。

為何 Claude Code 在工程倉庫上燒預算

Claude Code 的長處——像工程師一樣讀倉庫——也是計費表：

• 工具输出膨胀 — 大单体上 bash、搜索、MCP 单次可达 1 万–8 万 Token。
• 重複上下文 — 未壓縮時舊工具塊留在執行緒裡；45 分鐘重構會疊加費用。
• MCP 氾濫 — 每個服務加 JSON；三個囉嗦工具可讓單輪輸入 Token 翻倍。

若還在選工具鏈，可看 Codex CLI 對比 Claude Code 與 2026 Agent 框架橫評——本文假定你已選 Claude Code，只想把毛利找回來。

架構 — Headroom 插在哪

Claude Code (or Cursor / Codex via wrap) │ tool calls · logs · file reads ▼ ┌──────────────────────────────────────┐ │ Headroom (local — Python 3.10+) │ │ CacheAligner → ContentRouter → CCR │ │ SmartCrusher (JSON) │ │ CodeCompressor (AST) │ │ Kompress-base (text) │ │ MCP: compress · retrieve · stats │ └──────────────────────────────────────┘ │ compressed context + retrieve tool ▼ Anthropic API (Claude)

• CCR（可逆） — 原文本地存储；模型可 headroom_retrieve 取回逐字内容。
• MCP 模式 — 向任意 MCP 客户端暴露 headroom_compress、headroom_retrieve、headroom_stats。
• 代理模式 — headroom proxy --port 8787，OpenAI 兼容客户端零改代码。

官方文档：headroom-docs.vercel.app · 源码：github.com/chopratejas/headroom。

帳單對比矩陣 — 公開 workload 對比「裸奔 Claude Code」

用 Headroom 公開的前後表做規劃數字——不保證你的倉庫。乘以你的模型 $/MTok 得美元。

示意月度數學（假設）

假設 Sonnet 檔約 $3/MTok 輸入（以 Anthropic 當前頁為準——費率會變）：

標題裡 4 倍用量 指：美元預算不變 時，約 75% 平均節省 ≈ 同樣花費下 約 4 倍輪次——不是無限額度。

情境 A — headroom wrap claude（最快路徑）

适合：终端里日常 Claude Code（Mac/Linux）；不必改 MCP.json。

# Python 3.10+ required pip install "headroom-ai[all]" # One-command wrap (starts compression + optional memory) headroom wrap claude # After a session, inspect savings headroom perf

变化： Headroom 在 API 调用前拦截工具输出与上下文。Claude Code 交互不变；用 wrap 启动而非裸 claude。

若 X 则 Y： 若 已在租用 Mac 上用 obra Superpowers，则 在同一主机装 Headroom——技能路径见 obra Superpowers 安装；Headroom 正交（压缩 vs 流程）。

场景 B — Claude Code + 自定义工具的 MCP 服务

适合：精心配置 MCP 服务、要把 compress/retrieve 当一等工具的团队。

pip install "headroom-ai[mcp]" # Install MCP config for supported clients headroom mcp install

Claude Code MCP 配置（常见模式——以当前文档为准）：

{ "mcpServers": { "headroom": { "command": "headroom", "args": ["mcp", "serve"] } } }

获得的 MCP 工具：

若 X 则 Y： 若 MCP 返回巨大 JSON（浏览器、DB），则 先经 Headroom 再让 Claude 总结——否则 raw JSON 读两遍都要钱。

场景 C — 混合技术栈代理

headroom proxy --port 8787 # Point OpenAI-compatible clients at http://127.0.0.1:8787

与 Claude Code 并行跑 Codex、Aider 或脚本 且要一层压缩时用。

分步跑通 — 第一個有效小時

1. 安装 — pip install "headroom-ai[all]"（或 pipx install --python python3.13 "headroom-ai[all]"）。
2. 基线 — 无 Headroom 跑一轮 Claude Code；headroom perf 不可用——记下 Anthropic 控制台该小时输入 Token。
3. 启用 wrap — headroom wrap claude；相同任务（同仓库、类似提示）。
4. 对比 — headroom perf + 控制台差值；搜索/日志重的任务收益最大。
5. 启用 MCP（可选）— headroom mcp install；给最吵的 MCP 工作流加压缩。
6. 设预期 — 探索型任务可能只有 ~47% 而非 92%；按此预算。
7. CCR 演练 — 让 Claude headroom_retrieve 已知被截断的日志行；验证可逆。
8. 何时跳过 — 沙箱 CI 无本地 Python；在租用 Mac构建机上用 proxy，别只绑笔记本。

排錯

headroom wrap claude 无法启动 Claude Code

现象： command not found: claude 或 wrap 内 PATH 错误。
修复： 先装 Claude Code CLI；wrap 前同 shell 里 which claude 可用。

小文件节省接近 0%

现象： headroom perf 几乎无压缩。
修复： Headroom 擅长大 JSON/日志；小改动拉不动均值。用大仓库 rg 或 CI 日志测。

压缩后模型「漏」细节

现象： 压缩日志引错行。
修复： 用 headroom_retrieve（CCR）取原文；收紧提示（「编辑 442 行前 retrieve 原文」）。

Claude Code 里 MCP headroom 报红

现象： MCP 连接失败 / spawn 错误。
修复： 终端手动 headroom mcp serve 看 stderr；确认 Python 3.10+ 与 headroom-ai[mcp]。

推薦路徑

常見問題

延伸閱讀

• Codex CLI 對比 Claude Code M4 基準
• obra Superpowers 安裝指南
• 2026 AI Agent 框架橫評