Headroom验证省钱实战：headroom doctor与perf命令确认压缩真正生效

Headroom验证省钱实战：headroom doctor与perf命令确认压缩真正生效

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom

Headroom 是一个运行在本地、为 LLM 编码代理做上下文压缩的开源工具（Library、Proxy、MCP Server 三种形态）：它在你把工具输出、日志、文件、RAG 片段发给大模型之前先把它们压一遍，JSON 类数据可省 60–95% token，编码代理场景平均省 15–20%，答案质量不变。而本文聚焦一个新手最容易忽略的环节——验证：装完 Headroom 之后，如何用headroom doctor和headroom perf两条命令，亲手确认压缩管线真的在工作、token 真的在变少。

为什么装完一定要验证？Headroom 的失败是"静默"的

这是headroom doctor源码（headroom/cli/doctor.py）开头写得最清楚的一点：

Headroom 的失败模式是静默的：当客户端没有经过代理路由（或代理跑着旧版本代码）时，一切都"看起来正常"——只是你不再省 token 了。

换句话说，代理没起来、ANTHROPIC_BASE_URL没指到本地端口、代理进程是升级前的旧代码……这些情况下你的 Claude Code / Codex 照样能用，账单照样增长，但压缩一分钱都没省。没有任何报错，唯一的区别就是"省钱停了"。

所以验证的意义在于：把"我觉得它在省"变成"我有证据它在省"。Headroom 为此提供了完整的证据链：

headroom wrap claude # 1. 把编码代理接到本地代理（8787 端口） headroom doctor # 2. 体检：路由、版本、省钱流水是否健康 headroom perf # 3. 审计：从日志算出省了多少 token、省在哪 headroom dashboard # 4. （可选）实时仪表盘看压缩与缓存

一键体检：headroom doctor 检查项全解读

headroom doctor把散落在各处的状态交叉核对一遍——这些东西单独看都没人帮你拼起来。它的实现位于 headroom/cli/doctor.py，核心是 8 项常规检查 + 若干条件检查：

它还会追加条件检查，比如：Claude Desktop 会话绕过代理（Desktop 会强制覆盖ANTHROPIC_BASE_URL）、崩溃的 wrap 会话留下的"僵尸路由"、Ollama 与 Headroom 抢占同一环境变量的冲突等——每一项失败都附带一条可直接执行的修复提示。

退出码可直接用于脚本和 CI：

• 0— 全部通过 ✅
• 1— 只有警告（能用，但接线不完美）
• 2— 至少一项失败（代理挂了 / 部署挂了）

headroom doctor # 默认检查 8787 端口 headroom doctor --port 8790 # 自定义端口（也可用 HEADROOM_PORT） headroom doctor --json # 机器可读输出，方便接入告警

性能审计：headroom perf 从日志算出"真金白银"

doctor回答"接线对不对"，headroom perf回答"到底省了多少、省在哪"。实现见 headroom/cli/perf.py 与 headroom/perf/analyzer.py：它解析~/.headroom/logs/proxy.log里的 PERF / 路由 / 变换记录，生成一份人话报告，默认看最近 7 天。

报告里最值钱的几块内容：

1. 总览：请求数、压缩前后 token 对比、总节省 token 与百分比；
2. 按模型拆分：每个模型省了多少 token、按 list price 折算约省多少钱（例如claude-…: 12 reqs, 1,43,100 tokens saved (57%), ~$X.XX at list price），并细分"消息压缩"与"工具 schema 延迟"两部分；
3. 缓存分析：cache read / write、命中率，还会对比前 5 次与后 5 次请求，判断缓存是在趋于稳定还是"早期轮次命中率差——压缩决策可能在反复横跳"；
4. 优化开销：压缩本身引入的平均 / p50 / p95 / p99 延迟——确认省 token 的同时没有拖慢响应；
5. 变换效率：各压缩器（SmartCrusher、CodeCompressor 等）平均压缩率与使用次数；
6. 内容路由统计：被压缩 / 排除 / 跳过 / 未变化的内容块占比。

常用姿势：

headroom perf # 最近 7 天 headroom perf --hours 24 # 只看最近 24 小时 headroom perf --raw # 逐条原始 PERF 记录 headroom perf --format json # 聚合报告转 JSON headroom perf --format csv > today.csv # 按模型拆分的 CSV，方便做趋势表

💡headroom perf的按模型拆分行是诚实口径：若某轮压缩反而让请求变大了（如 CCR 主动展开、记忆注入），膨胀量会单列inflated，而不是被 0 钳掉后假装没发生。

三步验证清单：从"装上了"到"确认真的在省钱"

按顺序做完这三步，你就拥有了完整证据链：

1. headroom doctor→ 退出码 0。重点看savings行：它显示"累计节省 N token / $X.XX（来源：代理 /stats）"，并标注最后一次请求发生在多久前——这是"流量真的在走压缩管线"的直接证据。
2. headroom perf --hours 24。确认总览区Tokens saved非零，且按模型拆分里你实际在用的模型有数字。如果doctor全绿但perf没有记录，说明有流量但没被压缩，检查路由检查项给出的提示。
3. headroom dashboard（需代理在跑）。实时仪表盘给出压缩节省金额、token 节省率、压缩质量（被删 token 中判定为废物的比例）与开销四项卡片，适合开着一个窗口边干活边观察。

常见警告速查

小结

• 装 Headroom 只完成一半，验证才是另一半——它的失败不报错，只会悄悄停止省钱；
• headroom doctor交叉核对代理、客户端路由、版本、省钱流水，退出码 0/1/2 可直接接入脚本；
• headroom perf从日志算出分模型的 token 节省、缓存命中率与压缩开销，支持--json/--csv导出做长期跟踪；
• 两者都源自 README.md 中"Verify setup and see the savings"一节推荐的验证流程，源码分别在 headroom/cli/doctor.py 与 headroom/cli/perf.py，想深挖检查逻辑时可以直接阅读。

跑完这两条命令，"Headroom 在给我省钱"就从一句信仰变成了一个可复现的数字。

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom