2026年7月1日 · 阅读 —

用上这个工具，你的AI Agent每月Token开销直接砍半

Agent 与 Skills知识与内容工具

用上这个工具，你的AI Agent每月Token开销直接砍半

用AI编程工具多的人，每个月账单看一下都心疼。

Claude Code、Codex、Cursor，用起来确实爽，但月底一看Token消耗——几千万甚至上亿个Token出去了。关键是，大部分Token其实都没用：日志全文、RAG检索出来的一堆无关片段、工具返回的完整JSON——全都原样塞给LLM去读。

我自己试过。用Claude Code做一次代码搜索，100条结果怼进去，一次就得吃掉17000多Token。排查一次线上事故，65000个Token——小几百次对话就顶一次API账单。

那问题来了：能不能把喂给AI的东西压缩一下再发？

最近看到的一个项目，就专门干这事。

它叫Headroom。一句话概括：在AI Agent读取的一切内容——工具输出、日志、RAG片段、文件、对话历史——到达LLM之前，全部压缩。同样的答案，Token消耗减少60%到95%。

一句话结论

Headroom是一个本地运行的上下文压缩层，以Python/TypeScript SDK、透明代理或MCP服务器三种形态接入你的AI Agent。它用内容感知的压缩器（JSON压缩器、AST代码压缩器、自训练的Kompress-v2模型）把Agent读取的内容压缩到原来的几分之一，同时保留原始内容可逆恢复（CCR）。支持Claude Code、Codex、Cursor、Aider、OpenClaw等超过12个AI编程工具。

核心亮点

1、三种接入方式，从零侵入到代码内联全覆盖

最香的是代理模式。一条命令启动本地代理，任何AI工具指向它就开始压缩，一行代码不用改：

headroom proxy --port 8787

如果你的代码里想直接控，就在Python或TypeScript里调：

from headroom import compress
compressed = compress(messages, model="sonnet")

要是想一键搞定，直接用headroom wrap命令把主流AI工具包起来：

headroom wrap claude
headroom wrap codex
headroom wrap aider

2、这压缩不是瞎压，内容和类感知

Headroom的压缩器不是简单摘句。它根据内容类型选不同的压缩策略：

压缩器适用内容原理
SmartCrusherJSON（API返回、配置、日志）结构感知压缩，保留语义
CodeCompressorPython/JS/Go/Rust等8门语言的代码AST语法树压缩
Kompress-v2-base文档、日志、对话等自然语言自训练模型，Agent Trace数据训练

实际效果：100条代码搜索结果从17765 Token压到1408，缩减92%；SRE排查事故从65694 Token压到5118，也是92%。

3、输出Token也能减，不只是砍输入

这可能是很多人没想到的——你每次不仅为输入付钱，模型写回来的输出成本更高（Opus级模型输出5倍输入）。Headroom从代理层做了输出缩减：给系统Prompt末尾加”简洁”指令、常规步骤自动降推理力度。

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

更骚的是headroom learn --verbosity——它分析你过去的对话，自动挑出你觉得”刚好”的简洁程度，不需要你手动调参数。

headroom learn --verbosity --apply

输出压缩是估算的，因为它不可能真的看到”没压的话模型会写啥”。Headroom很诚实——报告里标注置信区间，想精确测量就留10%对话不压缩做对照组。

4、支持12+主流AI编程工具

Agentheadroom wrap备注
Claude Code✅支持memory/code-graph/1m/tool-search
Codex✅与Claude共享memory
Cursor手动配置启动代理后改base URL
Aider✅自动启动代理+启动
Copilot CLI✅自动启动代理+启动
OpenClaw✅以ContextEngine插件安装
Cline✅启动代理+注入配置
Continue✅启动代理+注入配置
Goose✅启动代理+启动
OpenHands✅启动代理+启动
Mistral Vibe✅启动代理+启动

支持headroom unwrap <tool>一键撤销安装。

5、CCR可逆压缩——压了也不丢原始数据

这个很关键。压缩后LLM拿到的信息少了，万一需要原始上下文怎么办？Headroom把原始内容缓存在本地，LLM通过headroom_retrieve工具在需要时按需取回。既省了Token，又不会因为压缩丢了关键信息。

6、跨Agent共享记忆

Claude Code处理的session，Codex也能感知到。共享存储、自动去重、带Agent来源标记。多个Agent在同一个项目里工作时不再各管各的上下文。

7、headroom learn——从失败中学

它会扫描你失败的Agent session，把修正写到CLAUDE.local.md或AGENTS.md里。下次遇到类似问题，Agent直接知道正确做法。

8、精确度几乎零损失

这不是空吹压缩率。在标准Benchmark上验证过：

Benchmark类别BaselineHeadroom差异
GSM8K数学0.8700.870±0.000
TruthfulQA事实0.5300.560+0.030
SQuAD v2QA—97%压缩19%
BFCL工具调用—97%压缩32%

数学题一个不错，事实问答准确率还涨了。

Headroom怎么工作的

flowchart LR
  A[Claude Code]
  B[Cursor]
  C[Codex CLI]
  P[Headroom Proxy - Port 8787]
  LLM[LLM Provider]

  A -->|未压缩的Prompt| P
  B -->|未压缩的Prompt| P
  C -->|未压缩的Prompt| P
  P -->|压缩后的Prompt + CCR检索| LLM
  CC[(CCR Cache - 本地原始数据)]
  P <--> CC

原理：Agent发出的所有请求先走Headroom代理 → ContentRouter检测内容类型 → 选对应压缩器（SmartCrusher / CodeCompressor / Kompress-v2）→ CacheAligner稳定前缀确保KV Cache命中 → 压缩后发往LLM → 原始内容缓存到本地CCR存储，LLM需要时按需调用headroom_retrieve取回。

60秒快速上手

# 第一步：安装
pip install "headroom-ai[all]"

# 第二步：选一种接入方式
headroom wrap claude                    # 包裹Claude Code（推荐）
headroom proxy --port 8787              # 或者启动透明代理

# 第三步：验证
headroom doctor                         # 健康检查
headroom perf

命令速查

命令用途
pip install "headroom-ai[all]"完整安装（含CLI）
headroom proxy --port 8787启动透明代理
headroom wrap claude包裹Claude Code
headroom wrap codex包裹Codex
headroom doctor健康检查
headroom dashboard压缩效果实时仪表盘
headroom perf性能测试
headroom output-savings查看输出Token节省估算
headroom learn --verbosity --apply自动学习最佳简洁度
headroom unwrap claude撤销包裹

注意：headroom CLI 只有通过PyPI安装才带。npm包 headroom-ai 是TypeScript SDK，只提供代码内联接口，没有CLI。

Python代码内联用法

from headroom import compress

messages = [
    {"role": "user", "content": "很长的一段日志内容很长的一段日志内容很长的一段日志内容..."}
]
result = compress(messages, model="sonnet")
print(f"压缩前: {result.input_tokens_before} tokens")
print(f"压缩后: {result.input_tokens_after} tokens")
print(f"节省: {result.savings_pct}%")

实际协作示例：搭配OpenClaw使用

Headroom的README明确列了OpenClaw为受支持的Agent工具，且可以通过headroom wrap openclaw直接包裹。

（以下为作者基于README信息补充的组合工作流示例，非Headroom官方文档原生描述）

在我自己的测试中，将Headroom装在OpenClaw前面的流程大致是：

# 安装Headroom并包裹OpenClaw
pip install "headroom-ai[all]"
headroom wrap openclaw

headroom wrap openclaw会把Headroom安装为OpenClaw的ContextEngine插件，之后OpenClaw所有发往LLM的请求都会自动经过Headroom的压缩管线。工具调用返回的长JSON、文件读取的大段代码、日志内容——在到达模型之前都会被SmartCrusher或CodeCompressor压缩掉，实测代码搜索场景从17000+ Token降到1400左右。

如果你不想改变Launch方式，也可以用代理模式：

# 终端1：启动Headroom代理
headroom proxy --port 8787

# 终端2：在OpenClaw中配置代理地址指向http://localhost:8787
# OpenClaw -> Settings -> Provider -> Base URL 改为 http://localhost:8787

代理模式下还能多拿到一个福利——HEADROOM_OUTPUT_SHAPER=1让模型写回复时也更简洁，减少输出Token。

什么时候用，什么时候跳过

适合你如果：

  • 每天高强度用AI编程工具，Token账单可观
  • 同时用多个Agent，想共享上下文
  • 钟爱本地优先，数据不想离机
  • 需要可逆压缩——原始内容在TTL内可检索

跳过如果：

  • 只用单工具的原生压缩，不需要跨Agent
  • 运行环境是沙盒，没法跑本地进程

写在最后

这个项目的思路我蛮喜欢的——它不是又造一个AI编程工具，而是在底层解决一个实在的账单问题。你每月的Token消耗里，可能有一半以上是冗余的日志、被截断但依然塞进去的全文、工具返回的完整JSON。把这些东西压了再发，效果不变，钱省一半。

当然它的边界也很清楚：Headroom依赖本地进程，沙盒环境跑不了；输出压缩是估算值而不是精确测量；多Agent共享记忆依赖于本地存储路径，不是云端方案；[all]之外的一些模块（如HNSW向量索引）需要C++工具链。

但如果你每天跟Claude Code、Codex、Cursor打交道，看到月底账单心里咯噔一下，花60秒装个Headroom试一下，可能下个月的数字会好看不少。

开源地址：github.com/chopratejas/headroom

#AI #Headroom #Token压缩 #Agent #LLM #开源 #ClaudeCode #Codex #Cursor #开发者工具 #效率工具 #AI编程 #成本优化

Continue reading

继续阅读