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/headroomHeadroom 是一个运行在本地、为 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 项常规检查 若干条件检查检查项验证什么典型异常proxy代理进程是否存活并响应/livez不可达 → 提示headroom proxy启动version运行中的代理版本是否与已安装包一致版本漂移 → 提示重启代理claudeClaude Code 的ANTHROPIC_BASE_URL是否指向本地代理端口未路由 → 提示headroom wrap claudecodex~/.codex/config.toml是否有 Headroom provider 且端口一致端口不匹配 / 缺鉴权配置shell env当前 shell 的环境变量是否指向代理未设置 → 该 shell 直连上游、绕过压缩savings是否有真实的省钱流水累计 token 美元no tokens saved yet 说明还没流量过代理budget是否配置了支出预算未配置 → 支出无上限它还会追加条件检查比如Claude Desktop 会话绕过代理Desktop 会强制覆盖ANTHROPIC_BASE_URL、崩溃的 wrap 会话留下的僵尸路由、Ollama 与 Headroom 抢占同一环境变量的冲突等——每一项失败都附带一条可直接执行的修复提示。退出码可直接用于脚本和 CI0— 全部通过 ✅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 天。报告里最值钱的几块内容总览请求数、压缩前后 token 对比、总节省 token 与百分比按模型拆分每个模型省了多少 token、按 list price 折算约省多少钱例如claude-…: 12 reqs, 1,43,100 tokens saved (57%), ~$X.XX at list price并细分消息压缩与工具 schema 延迟两部分缓存分析cache read / write、命中率还会对比前 5 次与后 5 次请求判断缓存是在趋于稳定还是早期轮次命中率差——压缩决策可能在反复横跳优化开销压缩本身引入的平均 / p50 / p95 / p99 延迟——确认省 token 的同时没有拖慢响应变换效率各压缩器SmartCrusher、CodeCompressor 等平均压缩率与使用次数内容路由统计被压缩 / 排除 / 跳过 / 未变化的内容块占比。常用姿势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 钳掉后假装没发生。三步验证清单从装上了到确认真的在省钱按顺序做完这三步你就拥有了完整证据链headroom doctor→ 退出码 0。重点看savings行它显示累计节省 N token / $X.XX来源代理 /stats并标注最后一次请求发生在多久前——这是流量真的在走压缩管线的直接证据。headroom perf --hours 24。确认总览区Tokens saved非零且按模型拆分里你实际在用的模型有数字。如果doctor全绿但perf没有记录说明有流量但没被压缩检查路由检查项给出的提示。headroom dashboard需代理在跑。实时仪表盘给出压缩节省金额、token 节省率、压缩质量被删 token 中判定为废物的比例与开销四项卡片适合开着一个窗口边干活边观察。常见警告速查doctor / perf 提示含义一句话处理proxy: not reachable代理没起headroom proxy --port 8787version drift代理跑着旧代码重启代理即可routed to port X, but doctor probed 8787端口不一致headroom doctor --port Xno tokens saved yet代理健康但没流量走一次真实请求stale ANTHROPIC_BASE_URL from crashed wrap崩溃残留的路由headroom unwrap claude清理! Early turns have poor cache hits缓存前缀不稳关注 perf 的缓存趋势段小结装 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考