OpenClaw、Hermes、Claude Code、Codex省钱插件

上周有个朋友跟我说，他跑一个调试任务，单次对话花了将近七万 token，成本算下来快两块人民币。但问题是，他觉得 AI 的回答里有大量废话——日志原文、工具返回值、重复的上下文，塞满了整个上下文，真正有用的信息可能不到 10%。

最近 GitHub 上有个叫Headroom的项目突然涨到 45k star，它在数据进入 LLM 之前先压缩，号称能减少 60–95% 的 token，同时答案质量不变。

它干了什么

官方给的数据：一个实际的 debug 任务，原始 token 数 10,144，压缩后 1,260，同样找到了那个 FATAL 报错。

它支持三种接入方式，这个设计还挺聪明：

Library 模式：纯 Python 或 TypeScript，一行代码 compress(messages) 接进去，适合自己写 agent 的人。

Proxy 模式：在本地起一个代理 headroom proxy --port 8787，然后把你的 ANTHROPIC_BASE_URL 改成这个地址，代码零改动，任何语言都能用。

Wrap 模式：headroom wrap claude 直接接管 Claude Code 进程，最省事。

压缩逻辑

Headroom 不是简单地截断或者摘要，它有几套不同的压缩引擎，根据内容类型自动选择：

SmartCrusher 处理 JSON。AI agent 调用工具的返回值大多是 JSON，这个压缩器专门针对数组、嵌套对象、混合类型做结构化压缩。

CodeCompressor 处理代码，基于 AST。支持 Python、JavaScript、Go、Rust、Java、C++。AST-aware 的意思是它理解代码结构，不会把有意义的缩进、函数签名压掉。

Kompress-base 处理纯文本，这是他们自己训练的 HuggingFace 模型，在 agentic traces 上微调过，专门针对 agent 工作流场景。

CacheAligner 负责另一件事：稳定 prompt 前缀，让 Anthropic 和 OpenAI 的 KV 缓存真正命中。这个平时容易忽视，但对高频场景有实际的成本影响。

还有一个叫 CCR（可逆压缩） 的机制值得单独说。压缩后的内容，原始版本会缓存在本地。如果 LLM 觉得需要看完整内容，可以调用 headroom_retrieve 这个工具取回来。所以这不是有损压缩，是可逆的。

实测数据

项目里给了四个真实任务的对比：

精度方面，他们在 GSM8K（数学推理）上跑了对照，baseline 0.870，Headroom 0.870，分毫不差。TruthfulQA 反而从 0.530 涨到了 0.560。SQuAD v2（问答）压缩 19% 的情况下准确率 97%，BFCL（工具调用）压缩 32% 准确率同样 97%。

v0.27.0 带来了什么

这是今天（6月22日）刚出的版本，几个变化值得注意。

输出 token 压缩，这是本次最大的新功能。之前 Headroom 只压缩你发出去的 prompt，现在也开始干预 LLM 写回来的内容。在 Opus 级别模型上，输出 token 的成本是输入的 5 倍，而相当多的输出是废话：「好的，让我来分析一下……」开头、重复你刚给它的代码、常规步骤上不必要的深度思考。

开启方式：

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

它做两件事：一是在系统 prompt 末尾追加简洁性提示（这样不影响你自己的 prompt cache），二是 effort routing——如果当前 turn 只是工具调用后的 resume（比如读了个文件继续），就把模型的思考深度调低；遇到新问题或者报错则保持完整 effort。

还有一个自动学习功能 headroom learn --verbosity，它会读你历史 session，自动判断你偏好的简洁程度，然后应用到代理上。

headroom doctor，一个诊断命令，检查当前环境配置有没有问题，对新手很有用。

表格/Excel 压缩，新增了对 .xlsx 和 .xls 的支持，做数据分析的场景会用到。

Cortex Code（Snowflake）支持，新增了这个 agent 的兼容。

热更新，proxy 现在支持运行时热重载环境变量，改了配置不用重启代理，正在跑的 session 不中断。

遥测改为 opt-in，默认关闭，这个对本地优先部署来说是正确方向。

OpenClaw 2026.x 兼容性修复，wrap 插件导出方式更新为 {register} 对象格式。用 OpenClaw 的朋友注意一下，之前版本可能不工作。

和其他工具怎么比

市面上类似的工具有几个：RTK（只处理 CLI 命令输出）、lean-ctx（CLI + MCP，轻量级）、Compresr/Token Co.（托管 API，数据上传第三方），以及 OpenAI 自家的 Compaction（只压缩对话历史，provider 锁定，不可逆）。

Headroom 的定位是全覆盖：tools、RAG、日志、文件、history 都能处理，本地运行，支持可逆恢复，可以跨 Claude/Codex/Gemini 共享 memory。

不过 Headroom 用了自己训练的 Kompress-base 模型，冷启动时需要从 HuggingFace 下载，在国内可能需要提前配置镜像或者离线预置。SSL 检查网络环境也需要额外处理，README 里有说明。

快速使用

# 安装
pip install "headroom-ai[all]"
# 最快的方式：接管 Claude Code
headroom wrap claude
# 或者起代理，适配任何客户端
headroom proxy --port 8787

# 看一下节省了多少
headroom perf

给 OpenClaw、Codex、Hermes 用

看到这里，你大概会问：我不用 Claude Code，我用 OpenClaw 或者 Hermes，怎么接？

三个工具，情况各不一样，单独说。

OpenClaw：有专属插件，接入最完整

OpenClaw 在官方兼容矩阵里，Headroom 专门为它写了一个 ContextEngine 插件，接管 OpenClaw 的上下文组装逻辑，在 assemble() 阶段直接压缩，不需要在外面套代理。

安装两步：

pip install "headroom-ai[proxy]"
openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw

--dangerously-force-unsafe-install 这个参数看起来吓人，实际原因很简单：OpenClaw 默认不允许插件启动子进程，而 Headroom 插件会在检测不到运行中的代理时自动起一个。这个 flag 是在告诉 OpenClaw「我知道这个插件会启动进程，我允许」。如果你已经自己管理 Headroom 代理，这个行为不影响你，但安装时还是必须带这个参数。

安装完之后，在 OpenClaw 的配置文件里指定 contextEngine：

{
  "plugins": {
    "entries": {
      "headroom": {
        "enabled": true,
        "config": {
          "proxyUrl": "http://127.0.0.1:8787"
        }
      }
    },
    "slots": {
      "contextEngine": "headroom"
    }
  }
}

proxyUrl 是可选的，默认就是 127.0.0.1:8787。如果你想连接远端代理（比如跑在别的机器上的 Headroom），填这里。

一个需要注意的地方：v0.27.0 修复了 OpenClaw 2026.x 的兼容性问题，插件导出格式从旧版变成了 {register} 对象。如果你之前装过旧版并且发现不工作，更新 headroom-ai 到最新就行。

也可以直接用 wrap 命令，它会自动完成安装和配置：

headroom wrap openclaw

Codex：一行命令，和 Claude 共享记忆

Codex 是官方支持的，比 OpenClaw 更简单：

headroom wrap codex

这个命令会起 Headroom 代理，然后接管 Codex CLI 的进程。如果加上 --memory 参数，Codex 和 Claude Code 会共用同一个跨 agent 记忆库——也就是说你在 Claude Code 里解决的问题，Codex 那边也能查到历史。

headroom wrap codex --memory

v0.27.0 里还有几个 Codex 相关的修复：OAuth 图片请求路由、Codex 的 RTK shell 指引全局化、Responses endpoint 的 client 标识。如果你之前在 Codex 里遇到奇怪的行为，更新之后试试。

Hermes：代理模式可以用，但有个坑

Hermes 不在官方兼容矩阵里，没有 headroom wrap hermes。但 Hermes 走的是 OpenAI-compatible API，所以代理模式从技术上是通的：

# 先起 Headroom 代理
headroom proxy --port 8787
# 在 Hermes 的 config.yaml 里，把 API endpoint 指向代理
# 具体字段取决于你配置的 provider（OpenAI、Anthropic 等）

问题在于 CCR——Headroom 压缩之后会在工具调用结果里留下类似 [142 items compressed ... hash=a3f9c2] 这样的标记，意思是「原始内容我压缩存起来了，需要的话用这个 hash 来取」。Claude Code 可以通过 headroom_retrieve MCP 工具来取回，但 Hermes 没有这个工具，所以这些标记对它来说就是看不懂的黑盒——会导致它重跑命令或者乱猜。

GitHub 上有人提了这个 issue（#796），同时贴出了一个能用的 Hermes 插件，大概 90 行，放在 ~/.hermes/plugins/headroom_retrieve/ 里，通过 /v1/retrieve 接口把原始内容取回来。核心逻辑是：

# ~/.hermes/plugins/headroom_retrieve/__init__.py
import httpx
from tools.registry import tool_error, tool_result
_PROXY_URL = "http://127.0.0.1:8787"
def _handle_headroom_retrieve(args: dict, **kw) -> str:
    hash_key = str(args.get("hash") or "").strip()
    payload = {"hash": hash_key}
    if query := str(args.get("query") or "").strip():
        payload["query"] = query
    try:
        resp = httpx.post(f"{_PROXY_URL}/v1/retrieve", json=payload, timeout=15)
    except httpx.HTTPError as exc:
        return tool_error(f"headroom proxy unreachable ({type(exc).__name__})")
    if resp.status_code == 404:
        return tool_error("Content expired, re-run the original command")
    data = resp.json()
    return tool_result({"original_content": data.get("original_content", "")})

def register(ctx) -> None:
    ctx.register_tool(
        name="headroom_retrieve",
        toolset="headroom",
        schema=HEADROOM_RETRIEVE_SCHEMA,
        handler=_handle_headroom_retrieve,
    )

然后在 Hermes 的 config.yaml 里启用这个工具集：

toolsets:
  - headroom
plugins:
  enabled:
    - headroom_retrieve

还有一个细节：Headroom 的 CCR 默认 TTL 是 300 秒，对于单次工具调用够用，但如果 Hermes 在多轮对话里需要回溯早期压缩的内容，可能已经过期了。可以通过环境变量延长：

export HEADROOM_CCR_TTL_OVERRIDE=3600  # 改成 1 小时

（这个环境变量目前不是官方 API，是社区 workaround，以后可能有正式的 env 支持。）

这个 issue 目前是 closed 状态，但并不意味着官方已经合并——原因不明，可能是作者关了或者社区决定等进一步需求。Hermes 官方仓库也有对应的 issue（#39691）讨论集成 headroom-ai，目前处于提案阶段，可以关注。简单说：Hermes + Headroom 现阶段能跑，但需要手动加这个插件，不是开箱即用。

Github：headroomlabs-ai/headroom