【工具】Headroom — AI Context Compression Proxy

概述

AI agent 上下文压缩代理。自动压缩 tool output 等上下文内容，节省 60–95% tokens。

安装

本机环境为 Debian（pip 通过 externally-managed 保护），使用 uv tool install：

bash

uv tool install "headroom-ai[proxy]"

二进制可执行文件在：~/.local/bin/headroom 实际 Python 路径：~/.local/share/uv/tools/headroom-ai/bin/python

[toc]

启动

基础启动

bash

headroom proxy --port 8787

自定义 API 上游

覆盖 Anthropic API 目标地址：

bash

headroom proxy --port 8787 --anthropic-api-url https://你的-api地址

注意 1：必须通过 --anthropic-api-url 参数设置，环境变量 ANTHROPIC_TARGET_API_URL 可能无效。

注意 2：部分上游需要客户端传递 x-api-key Header（proxy 的 ANTHROPIC_API_KEY 环境变量不会被自动转发），调用时需显式添加。

认证方式

方式	说明
ANTHROPIC_API_KEY 环境变量	部分上游接受，但 proxy 不会自动转发给上游，主要用于本地认证
x-api-key Header（推荐）	proxy 会透传到上游，兼容 Anthropic 规范
Authorization: Bearer	部分上游支持

开机自启

通过 ~/.config/systemd/user/headroom-proxy.service 管理（systemd 用户服务）：

bash

systemctl --user enable headroom-proxy
systemctl --user start headroom-proxy
systemctl --user status headroom-proxy
journalctl --user -u headroom-proxy -f -n 50

注意：headless 场景需执行 sudo loginctl enable-linger $USER 确保用户登出后仍持续运行。

状态查看

bash

headroom doctor

统计数据

bash

curl http://localhost:8787/stats | python3 -m json.tool | less

集成到 OpenClaw

已通过 ContextEngine 插件集成。完整配置见 _posts/AI大模型/OpenClaw/Headroom Context压缩引擎集成与优化数据.md。

关键配置项

json

{
  "plugins": {
    "slots": { "contextEngine": "headroom" },
    "entries": {
      "headroom": {
        "enabled": true,
        "config": {
          "proxyUrl": "http://127.0.0.1:8787",
          "proxyPort": 8787,
          "autoStart": false,
          "pythonPath": "~/.local/share/uv/tools/headroom-ai/bin/python"
        }
      }
    }
  }
}

❗ 插件只支持以下属性：enabled、proxyUrl、proxyPort、autoStart、pythonPath。不支持 startupTimeoutMs、gatewayProviderIds。 ❗ 如果 proxy 独立运行（推荐），设置 autoStart: false。

压缩效果

策略	典型场景	节省率
SmartCrusher	JSON 列表	80–90%
Kompress v2	长文本	50–70%
Log	日志行	80–90%

• 小负载（<500 tokens）跳过压缩
• 代码和 grep 结果不压缩（保证正确性）