#OpenClaw #Headroom #ClaudeCode #MCP #上下文压缩

接上篇 《OpenClaw 公网访问：FRP + nginx HTTPS 配置实录》，记录第四阶段：为 Claude Code 会话接入 Headroom 上下文压缩层，并实测不同内容类型下的 token 节省效果。

一、Headroom 是什么

headroomlabs-ai/headroom 是一个本地优先的上下文压缩中间层，工作原理：

1
2
3
4
5
6
7
8
9
10
Claude Code / OpenClaw / 任何 AI 代理
        │   tool outputs · logs · files · RAG 结果
        ▼
 ┌─────────────────────────────────────────────┐
 │  Headroom Proxy（本地运行，数据不出机器）     │
 │  ContentRouter → SmartCrusher / Kompress    │
 └─────────────────────────────────────────────┘
        │   压缩后的 prompt
        ▼
 Anthropic API（token 数更少，费用更低）

支持三种接入方式：

  • Library：from headroom import compress，Python 直接调用

  • Proxy：headroom proxy --port 8787，设置 ANTHROPIC_BASE_URL 零代码接入

  • MCP Server：headroom mcp install，集成到 Claude Code 工具列表

二、安装

headroom-ai 包含预编译的 Rust 核心（SmartCrusher），Python 3.13 下直接安装预编译 wheel，无需本地 Rust 工具链：

1
2
3
4
5
# 克隆仓库（可选，用于研究源码）
git clone https://github.com/headroomlabs-ai/headroom.git /Users/lin/code/Openclaw/headroom

# 安装 Python 包（加 --only-binary 强制用预编译 wheel，避免从源码编译 Rust）
pip install --only-binary :all: "headroom-ai[all]"

安装后版本：headroom-ai 0.28.0，Python 3.13。

坑：国内镜像源（阿里云）的 tree-sitter-language-pack 包不完整（33MB 只下载了 4.2MB）。解决：加 --only-binary :all: 改用预编译 wheel，或临时切换到官方 PyPI。

三、MCP Server 注册

1
headroom mcp install

输出：

1
2
3
Installing Headroom MCP server...
  claude: registered (restart the agent if it was already running)
  codex: registered (restart the agent if it was already running)

注册位置是 ~/.claude/.claude.json（不是 settings.json）：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "headroom": {
      "command": "/Users/lin/opt/anaconda3/bin/headroom",
      "args": ["mcp", "serve"]
    }
  }
}

重启 Claude Code 后，新会话中会出现三个 MCP 工具：

  • mcp__headroom__headroom_compress

  • mcp__headroom__headroom_retrieve

  • mcp__headroom__headroom_stats

四、启动代理

1
2
# 持久化后台运行
nohup headroom proxy --port 8787 > /tmp/headroom-proxy.log 2>&1 &

验证：

1
2
curl http://127.0.0.1:8787/health
# {"service":"headroom-proxy","status":"healthy","version":"0.28.0",...}

五、接入 Claude Code

重启 Claude Code 时指定代理地址：

1
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

所有 API 请求会经过 headroom 压缩后再转发到 Anthropic。

六、实测：各内容类型压缩效果

使用 headroom Python 库对不同内容类型进行精确测试，结果如下：

6.1 JSON 结构化输出（headroom 最擅长）

测试场景 原始 tokens 压缩后 节省
200 条 API 日志（单轮） 20,851 6,048 71%
5 轮 × 200 条日志（多轮） 129,010 47,757 63%
100 行结构化状态表 4,703 3,581 24%

对于结构化 JSON（如 docker 日志、API 响应、kubectl 输出），SmartCrusher 能有效识别重复结构并压缩。多轮对话积累越多，压缩效果越好（旧轮次进入压缩区间）。

6.2 代码文件读取（默认受保护，不压缩）

文件 Token 数 压缩后 说明
wrap.py (5855行) 53,668 53,668 受保护
content_router.py (3454行) 29,932 29,932 受保护
crusher.rs (1858行) 18,464 18,464 受保护
anthropic.py (3521行) 28,566 28,566 受保护
合计 130,630 130,630 0%

这是设计如此，不是 bug。 headroom 将 Read/Glob 工具的输出放入保护区间（router:excluded:tool），确保代码上下文的完整性，避免压缩导致编码错误。

6.3 git log / find 文本输出（效果有限）

Python 库对纯文本格式的 bash 输出压缩有限（≈0%）。Proxy 模式下 Rust 核心的 Kompress-v2-base 模型可能有更好的处理效果，但需要在真实代理会话中验证。

6.4 总结

1
2
3
4
5
6
headroom 压缩效果 = f(内容类型)

JSON / 结构化数据  →  50~71% token 节省 ✅
重复结构（多轮）   →  累积效果，越长越省 ✅
代码文件读取       →  0%（设计保护）❌
纯文本 bash 输出   →  Python 库无效，Proxy/Kompress 可能有效 ⚠️

七、基准测试工具

在 /Users/lin/code/Openclaw/headroom-benchmark/ 创建了三个测试文件：

task.md

5 阶段 × 10 步骤的测试任务，覆盖 headroom 仓库内最大的源文件和多种 bash 命令，用于在两个 Claude Code 会话中执行相同任务做对比。

capture_stats.sh

1
2
3
# 测试前后各运行一次，记录 proxy 统计快照
./capture_stats.sh proxy_before
./capture_stats.sh proxy_after

输出 JSON 到 results/ 目录，记录 original_tokens_total 和 compressed_tokens_total。

compare.py

1
2
3
4
5
python3 compare.py \
  --baseline-tokens 85000 \
  --proxy-before "results/proxy_before_*.json" \
  --proxy-after  "results/proxy_after_*.json" \
  --cost-per-mtok 3.0

输出格式：

1
2
3
4
5
6
7
8
══════════════════════════════════════════════════════════════
  Headroom Token 压缩对比报告
══════════════════════════════════════════════════════════════
  无代理（基线）token 数       : 85,000
  有代理（实际发送）token 数   : 24,972
  节省比例                     : 70.6%
  节省费用                     : $0.00181
══════════════════════════════════════════════════════════════

八、两会话对比实验步骤

会话 A（无代理，baseline）

1
claude

进入后：输入 /cost 记录初始值 → 执行 task.md 任务 → 再次 /cost 记录结束值，差值 = baseline token 消耗。

会话 B（有代理）

1
2
3
4
5
6
7
8
# 先确认 proxy 在线
curl -sf http://127.0.0.1:8787/health | python3 -m json.tool | grep status

# 取基准快照
cd /Users/lin/code/Openclaw/headroom-benchmark && ./capture_stats.sh proxy_before

# 启动代理会话
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

执行相同 task.md 任务后：

1
2
3
4
5
./capture_stats.sh proxy_after
python3 compare.py \
  --baseline-tokens <会话A的差值> \
  --proxy-before "results/proxy_before_*.json" \
  --proxy-after  "results/proxy_after_*.json"

九、注意事项

  1. 代理不持久：nohup headroom proxy 进程在系统重启后消失。如需持久化：

    1
    headroom install apply   # 作为系统服务安装

  2. MCP 生效需重启：headroom mcp install 注册后，需要重启 Claude Code 才能看到 MCP 工具。

  3. 压缩对象是 tool output，不是对话本身：headroom 压缩的是工具调用返回的内容（文件内容、bash 输出等），Claude 的思考过程和对话内容不压缩。

  4. 适合场景：运维类任务（docker、kubectl、日志分析）效果最好；纯代码开发（Read 文件为主）几乎无效果。

十、相关资源

  • 仓库：/Users/lin/code/Openclaw/headroom/

  • 基准测试：/Users/lin/code/Openclaw/headroom-benchmark/

  • proxy 日志：/tmp/headroom-proxy.log

  • MCP 注册配置：~/.claude/.claude.json

  • headroom 文档：https://headroom-docs.vercel.app/docs

延伸阅读