Headroom 中文使用教程：本地上下文压缩与 Claude Code/Codex/Cursor 接入

headroomlabs-ai/headroom 是一个本地的 AI Agent 上下文压缩层：坐在你的 Agent 和 LLM 之间，把 Agent 读到的工具输出、日志、RAG chunk、文件、对话历史压缩之后再喂给模型。官方公开数据显示，在真实 Agent trace 上能节省 21–57% token，且压缩是可逆的（CCR 机制——LLM 需要原文时可以按需取回）。本教程基于 Headroom 官方 README 与文档站，手把手覆盖安装与四种集成形态。

第 1 步前置条件

• Python 3.10+ 配合 pip —— 用 pip 安装路径需要；或
• Node.js 18+ 配合 npm —— 用 TypeScript / Node 包需要；或
• Docker —— 用容器路径需要。
• 一个想包装的 AI 编程 Agent（可选但推荐）：Claude Code、Codex、Cursor、Aider 或 GitHub Copilot CLI。Headroom 也可以作为库或代理纯本地用，没有 Agent 也能跑。

第 2 步安装 Headroom

方式 A — pip（Python，推荐）

pip install "headroom-ai[all]"

[all] extra 拉全部组件。如果想按需安装，可用更细的 extra：[proxy]、[mcp]、[ml]（即 Kompress-base 模型）、[code]、[memory]、[relevance]、[image]、[agno]、[langchain]、[evals]。

用 pipx 的话，建议显式指定 Python 解释器：

pipx install --python python3.13 "headroom-ai[all]"

方式 B — npm（TypeScript / Node）

npm install headroom-ai

方式 C — Docker

拉镜像后启动代理容器（把端口 8787 映射到宿主机）：

docker pull ghcr.io/headroomlabs-ai/headroom:latest
docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest

第 3 步选模式：wrap / proxy / library / MCP

Headroom 提供四种集成形态。按你现有使用习惯选择即可，也可以混用多种。

方式 A — Agent wrap（一行命令，最省事）

一条命令包装目标 Agent，Headroom 自动起代理 + 设环境变量 + 拉起 Agent：

headroom wrap claude     # Claude Code
headroom wrap codex      # Codex
headroom wrap opencode   # OpenCode
headroom wrap copilot    # GitHub Copilot CLI
headroom wrap cursor     # Cursor（打印配置）
headroom wrap aider      # Aider

官方兼容矩阵还列出 Grok、Cline、Continue、Goose、OpenHands、OpenClaw、Mistral Vibe、Oh My Pi、Kimi CLI 和 ZCode。具体工具支持项会随版本变化；不在列表里的 OpenAI 兼容客户端可以走 proxy。

方式 B — Proxy（语言无关，零代码改动）

如果你用的工具不在 wrap 列表里，可以让 Headroom 起本地代理，工具直接指向它：

headroom proxy --port 8787

任何 OpenAI 兼容的 API 客户端只要把 base URL 改成 http://localhost:8787 就能走压缩流程，效果与 headroom wrap 等价。

方式 C — Library（在你自己的代码里内联调用）

想从程序里直接控制压缩，调 compress(messages)。Python：

from headroom import compress
compressed = compress(messages, model="gpt-4o")

TypeScript / Node —— 注意：JS SDK 把压缩任务委托给本地代理，所以要先把代理跑起来，客户端再连上：

headroom proxy --port 8787

import { compress } from "headroom-ai";
const compressed = await compress(messages, {
  model: "gpt-4o",
  baseUrl: "http://localhost:8787",
});

README 的集成表里还列了对 Anthropic / OpenAI SDK、Vercel AI SDK、LiteLLM 回调、LangChain、Agno、Strands、ASGI app 的适配胶水。

方式 D — MCP server（暴露给 Claude Desktop 等 MCP 客户端）

headroom mcp install

把 Headroom 的三个工具（headroom_compress、headroom_retrieve、headroom_stats）注册到任意 MCP 客户端。

第 4 步GitHub Copilot CLI 订阅模式接入

Headroom 也能把 GitHub Copilot CLI 订阅模式（不用 BYOK 而是走订阅）的流量路由到本地代理：

headroom wrap copilot --subscription -- --model gpt-4o

包装器会解析对应账户的 Copilot API 端点（启动时打印 COPILOT_PROVIDER_API_URL=...），把 OpenAI 兼容的 Copilot CLI 请求先过 Headroom 再转发到 GitHub Copilot 托管 API。

第 5 步验证压缩效果

看 Headroom 对你的负载有没有用：

headroom perf

命令会在代表性的 Agent trace 上打印压缩前后 token 数。Headroom 官方公开 benchmark（用 python -m headroom.evals suite --tier 1 可复现）：

• SRE 事故调试：节省 57%；代码搜索：节省 21%
• 代码库探索：节省 42%
• GitHub issue triage：节省 30%
• 精度无损：GSM8K 0.870 vs 0.870、TruthfulQA +0.030、SQuAD v2 / BFCL 维持原始水平

实际节省比例取决于内容类型和你用的上游 LLM，上述只是项目公布的平均值，不是每种负载的保证。

常用 CLI 命令与额外能力

• headroom wrap <agent> —— 一键包装 Claude Code / Codex / Cursor / Aider / Copilot / OpenClaw
• headroom proxy --port 8787 —— 启动本地 OpenAI 兼容代理
• headroom perf —— 在代表性 workload 上量化压缩比
• headroom mcp install —— 在 MCP 客户端注册 Headroom 工具
• headroom learn —— 默认 dry-run：扫历史失败会话并打印建议修订；加 --apply 才真正写入 CLAUDE.md / AGENTS.md / GEMINI.md
• python -m headroom.evals suite --tier 1 —— 本机复现官方公开 benchmark

常见问题

Headroom 是什么？

Headroom 是一个本地的 AI Agent 上下文压缩层，由 headroomlabs-ai/headroom 开源（Apache-2.0）。它坐在 Agent 与 LLM 之间，把 Agent 读到的工具输出、日志、RAG chunk、文件、对话历史压缩之后再发给模型。官方 proof table 在四类固定场景中报告 21–57% 的节省；这不是所有工作负载的保证。压缩是可逆的（CCR），LLM 需要原文时可以按需取回。

Headroom 怎么安装？

三选一：pip install "headroom-ai[all]"（Python，3.10+）；npm install headroom-ai（TypeScript SDK，不提供 CLI）；或 docker pull ghcr.io/headroomlabs-ai/headroom:latest && docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest。

支持哪些编程 Agent？

官方兼容矩阵覆盖 Claude Code、Codex、OpenCode、Copilot CLI、Cursor、Aider、Cline、Continue、Goose、OpenHands、OpenClaw 等。任何 OpenAI 兼容客户端也可以走 headroom proxy。

怎么和 GitHub Copilot 一起用？

headroom wrap copilot --subscription -- --model gpt-4o——把 Copilot CLI 的 OpenAI 兼容请求经本地代理压缩后再转发到 GitHub 托管 Copilot API。

能省多少 token？

官方 proof table 的四类固定场景分别是代码搜索 21%、SRE 事故调试 57%、代码库探索 42%、GitHub issue triage 30%。官方 README 同时说明短对话、低重复和已经很紧凑的文本节省很少。建议跑 headroom perf 看你自己的 trace 实际效果。

Headroom 是本地运行吗？

压缩器、代理、MCP server、CCR 原文存储都在你的机器上跑。只有压缩后的 prompt 才会发给你配置的上游 LLM 提供商，所以提供商看到的请求与你直接调用它时一样（只是体积小很多）。

完整文档在哪里？

本教程覆盖安装与四种集成形态。架构、CCR 内部原理、Kompress-base 模型卡、各 provider 的细节请看官方源：github.com/headroomlabs-ai/headroom 与 docs.headroomlabs.ai。