Headroom (headroomlabs-ai/headroom) — 调研与接入方案

项目概览

Headroom 是一个 LLM 上下文压缩层，在 AI Agent 的请求到达大模型之前，对工具输出、日志、文件内容等进行智能压缩。

核心能力

能力 说明
内容压缩 检测内容类型（代码/JSON/文本），选择合适的压缩器，减少 60-95% token
可逆压缩 (CCR) 原始内容本地缓存，LLM 需要时可恢复
跨 Agent 记忆 共享存储，自动去重
输出 token 缩减 减少模型回复中的冗余内容
学习机制 从失败会话中提取模式自动写入配置

工作模式

Headroom 提供四种接入方式：

1. Library 模式

代码中直接调用 compress() 函数，适合开发者集成。

2. Proxy 模式（推荐）

启动本地代理服务器，设置环境变量即可让任何兼容 OpenAI/Anthropic 的客户端使用，零代码改造。

1
2
3
headroom proxy --port 8787
export ANTHROPIC_BASE_URL=http://localhost:8787
export OPENAI_BASE_URL=http://localhost:8787/v1

3. Agent Wrap 模式

一行命令包装现有 Agent，自动配置路由：

1
2
3
headroom wrap claude      # Claude Code
headroom wrap openclaw    # OpenClaw
headroom wrap codex       # Codex

4. MCP Server 模式

提供 headroom_compress、headroom_retrieve、headroom_stats 等 MCP 工具。

与 OpenClaw 的兼容性

项目官方 README 明确列出 OpenClaw 在支持列表中，headroom wrap openclaw 会安装为 ContextEngine 插件。

支持的 Agent 还包括：Claude Code、Codex、Cursor、Aider、Copilot CLI、OpenCode、Cline、Continue、Goose、OpenHands 等。

当前安装状态（本地服务器）

  • 位置：/opt/headroom-venv/bin/headroom

  • 版本：v0.28.0

  • 安装模式：headroom-ai[proxy,mcp]（轻量版，不含 PyTorch 等重 ML 依赖）

  • 状态：未启动 proxy，处于调研阶段

接入流程规划

第一阶段：安装与测试 ✅

  • headroom doctor 健康检查通过

第二阶段：A/B 对比测试 🔄

第三阶段：正式接入（评估后决定）

  • headroom wrap openclaw 持久化集成

Token 用量对比方案

要客观衡量 Headroom 的效果，需要在启用前后分别记录数据。

基准数据采集

启用前需记录：

  • AI 服务商 API 控制台的每日输入/输出 token 数

  • 日均 API 调用次数及费用

  • 当前会话的 token 消耗

启用后可通过 Headroom 的 --log-file 功能自动记录每条请求的压缩情况。

衡量指标

指标 获取方式
token 压缩率 Headroom dashboard (压缩前/后对比)
输入 token 节省 API 控制台前后对比
费用节省 按 token 单价计算
延迟影响 proxy log 中的处理耗时
回答质量 主观判断是否丢失关键信息

注意事项

  • --mode cache：偏向缓存命中率，压缩较温和

  • --mode token：偏向激进压缩

  • 使用低价模型时（如 DeepSeek），压缩的经济收益较小，主要价值在于减少 context window 占用

  • Headroom 对有大量工具调用和文件读取的场景效果最明显

优劣势分析

优势

  • 本地运行，数据不出机器

  • 多种接入方式，灵活适配不同场景

  • 可逆压缩保证关键信息不丢失

  • 社区活跃，迭代快

劣势

  • 依赖较多（约 80+ 个包）

  • 对现有工作流有侵入性

  • 每次请求增加 50-200ms 处理延迟

  • 需要持续维护版本兼容

适合场景

  • 长对话会话

  • 大型文件读取（代码库、日志）

  • 大量 RAG 检索结果

  • 跨 Agent 记忆共享

不适合场景

  • 短对话

  • 实时性要求极高的场景

  • 使用低成本模型时经济收益有限