Headroom：AI 代理上下文压缩神器，节省 60-95% Token 消耗

小新软件平替发表于2026-06-23

Headroom 是什么？ Headroom 是一款本地运行的 AI 代理上下文压缩层，通过智能压缩算法将发送给大语言模型的 token 数量减少 60-95%，同时保持回答准确性。它支持 Python/TypeScript 库、代理模式和一键包装多种主流 AI 编程助手，是 AI 开发者节省 API 成本的利器。

关键数据：

🌟 GitHub Stars: 51,000+（仓库链接）
📦 当前版本：v0.27.0
⚖️ 许可证：Apache-2.0
🧠 核心特性：SmartCrusher（JSON 压缩）——智能压缩 JSON 格式的工具输出和 API 响应
🔧 核心特性：CodeCompressor（AST 压缩）——语法树感知的代码压缩，支持 Python/JS/Go/Rust/Java/C++
📦 核心特性：Kompress-base（文本压缩）——基于 HuggingFace 训练的专用压缩模型
🔄 核心特性：CCR（可逆压缩）——原始内容本地缓存，需要时可恢复
🌐 核心特性：跨代理内存——Claude、Codex、Gemini 等多代理共享上下文记忆

你是否遇到过这样的情况：使用 Claude Code、Cursor 或其他 AI 编程助手时，API 账单突然暴涨？或者发现 AI 的响应变慢了，因为上下文窗口被大量日志、工具输出和历史对话填满？

这就是 Headroom 要解决的问题。它是一个本地运行的上下文压缩层，能够在 AI 代理读取内容之前进行智能压缩，让你在不牺牲回答质量的前提下，大幅降低 token 消耗和 API 成本。

前提条件

在开始使用 Headroom 之前，你需要准备：

Python 3.10+
一个 AI API 密钥（如 Anthropic、OpenAI 等）
基本的命令行操作知识

概述

本文将带你从零开始使用 Headroom，包括：

安装和配置 Headroom
三种使用模式：库、代理、一键包装
实际性能测试和效果验证
高级功能：可逆压缩和跨代理内存

详细步骤

第一步：安装 Headroom

Headroom 提供多种安装方式，选择最适合你的：

Python 用户：

1	pip install "headroom-ai[all]"

Node.js/TypeScript 用户：

1	npm install headroom-ai

Docker 用户：

1	docker pull ghcr.io/chopratejas/headroom:latest

💡 提示：[all] 安装所有可选功能。如果你只需要特定功能，可以安装对应的额外包：[proxy]、[mcp]、[ml]、[code]、[memory] 等。

第二步：选择使用模式

Headroom 提供三种使用模式，适合不同的场景：

模式一：库模式（推荐开发者使用）

在你的 Python 或 TypeScript 代码中直接使用：

from headroom import compress

# 压缩消息
compressed = compress(messages, model="claude-sonnet-4-20250514")

import { compress } from 'headroom-ai';

// 压缩消息
const compressed = await compress(messages, { model: 'claude-sonnet-4-20250514' });

模式二：代理模式（零代码修改）

启动一个本地代理，所有请求自动压缩：

1	headroom proxy --port 8787

然后将你的 AI 工具指向这个代理地址即可。

模式三：一键包装模式（最简单）

直接包装你正在使用的 AI 编程助手：

headroom wrap claude    # 包装 Claude Code
headroom wrap codex     # 包装 Codex
headroom wrap aider     # 包装 Aider
headroom wrap copilot   # 包装 Copilot CLI

💡 提示：一键包装模式会自动配置代理并启动你的 AI 工具，无需手动设置。对于 Cursor，需要手动配置代理设置。

第三步：验证压缩效果

运行性能测试，查看压缩效果：

1	headroom perf

这将运行一系列测试，展示 Headroom 的压缩能力。

第四步：使用可逆压缩（CCR）

Headroom 的独特功能是 可逆压缩（CCR），原始内容会被缓存，需要时可以恢复：

from headroom import compress, retrieve

# 压缩
compressed = compress(messages)

# 如果 LLM 需要原始内容，可以通过工具调用 retrieve
# LLM 会自动判断是否需要恢复原始内容

第五步：启用跨代理内存

如果你使用多个 AI 代理（如 Claude 和 Codex），可以启用跨代理内存共享：

# 启用内存功能
headroom wrap claude --memory

# Codex 会自动共享 Claude 的内存
headroom wrap codex --memory

常见问题（FAQ）

Q: Headroom 会降低 AI 的回答质量吗？
A: 不会。Headroom 的压缩算法经过精心设计，在标准基准测试中保持了原始准确率。例如在 GSM8K 数学测试中，压缩前后准确率完全一致（0.870）。

Q: Headroom 需要联网吗？
A: 不需要。Headroom 完全在本地运行，你的数据不会发送到任何外部服务器。唯一的网络请求是下载压缩模型（首次使用时）。

Q: 支持哪些 AI 模型/代理？
A: Headroom 支持所有主流 AI 代理，包括 Claude Code、Cursor、Codex、Aider、Copilot CLI 等。任何 OpenAI 兼容的客户端都可以通过代理模式使用。

Q: 压缩后的 token 数量能减少多少？
A: 根据不同的工作负载，可以减少 60-95% 的 token。例如代码搜索任务可以节省 92%，SRE 事件调试可以节省 92%。

Q: 如何查看节省了多少 token？
A: 运行 headroom perf 可以查看详细的性能数据。对于输出 token 节省，可以使用 headroom output-savings 查看估算值。

Q: Headroom 和 RTK 有什么区别？
A: RTK 主要压缩 CLI 命令输出，而 Headroom 压缩所有上下文（工具输出、RAG 结果、日志、文件、对话历史）。Headroom 内部也集成了 RTK 作为 shell 输出重写工具。

Q: Headroom 支持 Docker 部署吗？
A: 支持。可以使用 docker pull ghcr.io/chopratejas/headroom:latest 拉取镜像，适合服务器环境或 CI/CD 流程。

Q: 输出 token 也能节省吗？
A: 可以。Headroom 支持输出 token 减少，通过 verbosity steering 和 effort routing 减少模型”写回来”的冗余内容，设置 HEADROOM_OUTPUT_SHAPER=1 即可启用。

集成到 LangChain

如果你使用 LangChain，可以轻松集成：

from headroom.integrations import HeadroomChatModel
from langchain_anthropic import ChatAnthropic

llm = HeadroomChatModel(ChatAnthropic(model="claude-sonnet-4-20250514"))
response = llm.invoke("你的问题")