Headroom上下文压缩指南

更新时间：2026 年 8 月适用版本：Headroom 0.34.x 重点平台：macOS 主要场景：Claude Code、OpenAI Codex、Cursor、MCP 和自建 AI Agent

在 Claude Code、Codex 等 AI 编程工具中，Token 消耗并不只来自用户输入的提示词。随着任务不断进行，模型还会反复接收：

项目目录和文件内容；
代码搜索结果；
Git Diff；
编译和测试日志；
API 返回的 JSON；
数据库查询结果；
MCP 工具说明；
之前的对话和工具调用结果。

这些内容往往包含大量重复信息。它们不仅增加 Token 消耗，还可能挤占模型的上下文窗口，使真正重要的信息变得不突出。

Headroom 的作用，就是在请求发送给大模型之前，对这些上下文进行整理和压缩。

一、Headroom 是什么

Headroom 是一个开源的 大模型上下文优化工具。

它可以部署在 Claude Code、Codex、自建 Agent 与上游模型服务之间，对请求中的日志、JSON、搜索结果、表格和其他工具输出进行压缩，然后再将优化后的请求发送给模型服务。

基本工作流程如下：

1
2
3
4
5
6
7
8
9
Claude Code / Codex / AI Agent
              │
              │ 原始对话、代码、日志和工具结果
              ▼
        Headroom 本地代理
              │
              │ 识别内容类型并压缩冗余信息
              ▼
    Anthropic / OpenAI / 其他模型服务

Headroom 不负责生成最终答案。

真正完成代码分析、代码修改和问题回答的，仍然是 Claude、GPT 或其他上游模型。Headroom 主要负责优化发送给模型的上下文。

它常见的接入方式包括：

接入方式	适用场景	是否需要修改代码
本地代理	Claude Code、Codex、Cursor 等客户端	通常不需要
Python SDK	自建 Python Agent 或大模型应用	需要少量代码
TypeScript SDK	Node.js、TypeScript 项目	需要少量代码
MCP Server	支持 MCP 的客户端或 Agent	需要配置 MCP

对于普通 Claude Code 和 Codex 用户，最适合的是本地代理模式。

二、为什么需要 Headroom

AI 编程工具通常会进行多轮工具调用。

例如，Claude Code 为了解决一个错误，可能执行以下过程：

1
2
3
4
5
6
7
8
查看项目目录
→ 搜索相关代码
→ 打开多个文件
→ 运行测试
→ 读取错误日志
→ 修改代码
→ 再次运行测试
→ 查看 Git Diff

每一次工具调用都会产生新的文本。

假设测试工具输出了 5000 行日志，但真正重要的内容可能只有：

一个失败的测试用例；
两条异常堆栈；
几个关键文件位置；
少量警告信息。

如果全部日志都继续进入后续上下文，就会产生大量无效 Token。

Headroom 会尝试将这类内容整理为更短的结构，例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
测试总数：128
通过：127
失败：1

失败用例：
tests/test_user.py::test_create_user

主要异常：
ValueError: email is required

相关位置：
src/services/user_service.py:84

这样模型仍然能够看到关键错误，但不需要反复接收数千行正常日志。

Headroom 对以下内容通常更有价值：

大型 JSON；
测试日志；
构建日志；
搜索结果；
数据库查询结果；
长表格；
大量工具调用输出；
持续时间较长的 Agent 会话。

对于只有一两句话的短对话，Headroom 的收益通常较低。

三、Headroom 的工作原理

Headroom 不会简单地按照固定长度截断文本。

它会先判断内容类型，再选择对应的压缩方法。

1. 内容识别

Headroom 可以识别多种常见内容：

JSON；
日志；
搜索结果；
Git Diff；
Markdown 表格；
CSV 和 TSV；
YAML、TOML、INI；
HTML；
普通文本；
源代码。

不同类型的数据具有不同的结构，因此不能使用完全相同的压缩方式。

例如：

1
2
3
4
5
6
7
JSON          → 保留字段结构、异常值和代表性记录
日志          → 保留错误、警告和异常堆栈
搜索结果      → 去除重复路径和重复匹配
表格          → 保留字段、统计特征和关键行
HTML          → 提取主要正文
普通文本      → 删除重复和低信息密度内容
源代码        → 采用较为保守的处理方式

2. JSON 压缩

大型 JSON 经常包含大量结构相同的数据。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
[
  {
    "id": 1,
    "status": "success",
    "duration": 102
  },
  {
    "id": 2,
    "status": "success",
    "duration": 105
  },
  {
    "id": 3,
    "status": "failed",
    "duration": 5230
  }
]

模型通常不需要逐条读取所有正常记录。

Headroom 会尽量保留：

字段结构；
数据总量；
常见值；
异常值；
错误记录；
首尾样本；
重要统计信息。

压缩后的结果可能更接近：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
记录总数：3

字段：
id、status、duration

状态统计：
success：2
failed：1

异常记录：
id=3
status=failed
duration=5230

如果原始 JSON 很短、无法解析，或者压缩结果反而更长，Headroom 通常会保留原始内容。

3. 日志压缩

对于日志内容，Headroom 更关注以下关键词和结构：

1
2
3
4
5
6
7
error
exception
failed
fatal
warning
critical
traceback

大量重复的正常日志，例如：

1
2
3
Task completed successfully
Task completed successfully
Task completed successfully

通常可以被合并。

错误堆栈、失败任务、异常文件和行号则需要保留。

4. 搜索结果压缩

在大型代码仓库中，一次搜索可能返回几百条结果。

其中经常存在：

同一文件的重复匹配；
大量低相关结果；
生成目录中的结果；
依赖目录中的结果；
重复上下文。

Headroom 会尽量减少重复内容，保留：

高相关匹配；
文件路径；
行号；
匹配位置附近的上下文；
可能影响当前任务的结果。

5. 代码处理

代码压缩需要非常谨慎。

模型读取代码通常是为了：

查找 Bug；
理解业务逻辑；
修改函数；
检查调用关系；
分析边界条件。

如果随意删除代码，可能影响模型判断。

因此，Headroom 对代码通常采用保守策略。尤其是以下内容，一般不适合激进压缩：

用户明确要求分析的代码；
正在修改的函数；
最近读取的文件；
异常堆栈对应的代码；
条件判断和错误处理逻辑。

在真实编程任务中，Headroom 的主要收益通常来自日志、JSON 和工具输出，而不是直接大幅压缩源代码。

6. 原始内容恢复

Headroom 支持将原始内容保存在本地缓存中。

其基本思路可以概括为：

1
2
3
压缩内容
→ 缓存原文
→ 需要时重新检索

当 Agent 发现压缩结果不够详细时，可以重新取回完整原文，或者只搜索原文中的特定内容。

这一机制适合：

超长测试日志；
大型 JSON；
数据库结果；
搜索结果；
文件列表；
大量工具输出。

四、安装 Headroom

macOS 上推荐使用 uv tool 安装 Headroom。

这种方式会为 Headroom 创建独立的 Python 环境，不会污染当前项目的虚拟环境。

1. 安装 uv 和 Python

使用 Homebrew：

1
brew install uv python@3.13

检查安装结果：

1
2
uv --version
python3.13 --version

2. 安装 Headroom

1
uv tool install --python 3.13 "headroom-ai[all]"

更新终端环境：

1
2
uv tool update-shell
exec zsh

检查 Headroom：

1
2
headroom --version
command -v headroom

正常情况下，命令路径通常类似：

1
/Users/你的用户名/.local/bin/headroom

3. 更新 Headroom

通过 uv tool 更新：

1
uv tool upgrade headroom-ai

如果升级过程中出现依赖问题，可以重新安装：

1
uv tool install --force --python 3.13 "headroom-ai[all]"

五、临时使用：headroom wrap

最简单的使用方式是通过 headroom wrap 启动客户端。

启动 Claude Code：

1
headroom wrap claude

启动 Codex：

1
headroom wrap codex

Headroom 会完成以下过程：

1
2
3
4
5
启动本地代理
→ 为目标客户端设置代理地址
→ 启动客户端
→ 请求经过 Headroom
→ 客户端退出后结束临时代理

这种方式适合：

第一次测试 Headroom；
偶尔使用；
不希望修改长期配置；
排查客户端兼容性；
临时比较启用前后的 Token 消耗。

它的缺点是每次启动都需要输入完整命令。

如果每天都使用 Claude Code 或 Codex，更适合将 Headroom 配置为后台常驻服务。

六、macOS 推荐方案：后台常驻运行

常驻模式可以让 Headroom 在后台持续运行。

配置完成后，可以直接使用：

1
claude

或者：

1
codex

不需要每次执行：

1
2
headroom wrap claude
headroom wrap codex

1. 安装为后台服务

只配置 Claude Code 和 Codex：

1
2
3
4
5
6
7
headroom install apply \
  --preset persistent-service \
  --runtime python \
  --scope provider \
  --providers manual \
  --target claude \
  --target codex

参数含义如下：

参数	含义
`--preset persistent-service`	使用后台常驻服务
`--runtime python`	使用本机 Python 运行代理
`--scope provider`	只修改目标客户端的配置
`--providers manual`	手动指定需要配置的客户端
`--target claude`	配置 Claude Code
`--target codex`	配置 Codex

使用 provider 作用域比全局修改 .zshrc 更安全。

Headroom 主要会处理以下客户端配置：

1
2
3
4
5
Claude Code：
~/.claude/settings.json

Codex：
~/.codex/config.toml

这样不会让 Git、npm、浏览器或其他程序自动经过 Headroom。

2. 查看运行状态

1
headroom install status

3. 检查健康接口

Headroom 默认监听：

1
http://127.0.0.1:8787

检查服务：

1
curl -s http://127.0.0.1:8787/health

为了更容易阅读：

1
2
curl -s http://127.0.0.1:8787/health \
  | python3 -m json.tool

4. 检查端口

1
lsof -nP -iTCP:8787 -sTCP:LISTEN

如果能够看到 Headroom 相关进程，说明代理已经运行。

5. 日常使用

之后直接执行：

1
claude

或者：

1
codex

请求会自动经过 Headroom。

七、后台服务管理

查看状态：

1
headroom install status

启动服务：

1
headroom install start

停止服务：

1
headroom install stop

重启服务：

1
headroom install restart

删除持久化配置：

1
headroom install remove

当 Claude Code 或 Codex 突然无法连接时，可以先执行：

1
headroom install restart

然后检查：

1
2
headroom install status
curl -s http://127.0.0.1:8787/health

八、直接运行 Headroom Proxy

除了使用 wrap 和后台服务，也可以单独启动 Headroom Proxy：

1
headroom proxy

默认监听：

1
http://127.0.0.1:8787

指定端口：

1
headroom proxy --port 8788

指定监听地址：

1
2
3
headroom proxy \
  --host 0.0.0.0 \
  --port 8787

除非已经配置身份认证、防火墙和访问控制，否则不要将 Headroom 直接暴露到公网。

手动连接 Claude Code

先启动代理：

1
headroom proxy

再打开另一个终端：

1
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

这个环境变量只对当前命令有效，不会永久修改系统配置。

手动连接 OpenAI 兼容客户端

1
OPENAI_BASE_URL=http://127.0.0.1:8787/v1 codex

当需要排查常驻配置时，这种临时方式非常有用。

如果临时方式能够正常运行，但直接执行 claude 或 codex 不能运行，通常说明问题出在客户端配置，而不是 Headroom 代理本身。

九、压缩 Profile

Headroom 可以通过 Profile 调整压缩策略。

常见 Profile 包括：

Profile	主要特点	适用场景
`coding`	更重视代码安全和缓存稳定	Claude Code、Codex
`balanced`	压缩强度适中	通用 Agent
`agent-90`	更激进地压缩工具输出	大型非代码任务
`general`	通用文本处理	普通对话和文本任务

使用 coding

1
2
HEADROOM_SAVINGS_PROFILE=coding \
headroom proxy

使用 balanced

1
2
HEADROOM_SAVINGS_PROFILE=balanced \
headroom proxy

使用 agent-90

1
2
HEADROOM_SAVINGS_PROFILE=agent-90 \
headroom proxy

对于 Claude Code 和 Codex，建议优先使用：

1
coding

因为编码任务更看重信息完整性。

agent-90 中的数字不能理解为所有请求都一定节省 90%。实际效果取决于内容类型、请求长度、工具输出和模型调用方式。

不建议仅仅为了获得更高的统计数字，就对代码任务启用激进压缩。

十、cache 模式与 token 模式

Headroom 还可以选择不同的优化方向。

1. cache 模式

1
headroom proxy --mode cache

该模式更重视多轮会话中的前缀稳定性。

Claude Code 和 Codex 每轮请求通常都会携带之前的上下文。如果历史内容频繁变化，上游模型的提示缓存可能无法命中。

cache 模式会尽量避免反复改写已经稳定的历史前缀。

适合：

长时间编码会话；
多轮工具调用；
Claude Code；
Codex；
重视响应速度和缓存命中的场景。

2. token 模式

1
headroom proxy --mode token

该模式更重视直接减少输入 Token。

适合：

大型 JSON；
长日志；
数据库结果；
RAG 检索结果；
批处理任务；
大量非代码工具输出。

对于普通编码任务，建议先使用默认配置，不必主动切换模式。

十一、配置上游网络代理

在部分网络环境中，Headroom 访问 Anthropic 或 OpenAI API 时还需要经过 HTTP 代理。

推荐使用 Headroom 自己的代理参数：

1
2
headroom proxy \
  --http-proxy http://127.0.0.1:7890

也可以使用环境变量：

1
2
export HEADROOM_HTTP_PROXY=http://127.0.0.1:7890
headroom proxy

不建议为了 Headroom 全局设置：

1
2
3
HTTP_PROXY
HTTPS_PROXY
ALL_PROXY

因为全局代理变量可能同时影响：

Git；
npm；
Python 包管理器；
测试命令；
本地工具；
Headroom 启动的子进程。

HEADROOM_HTTP_PROXY 只用于 Headroom 访问上游模型服务，影响范围更小。

十二、查看 Token 节省情况

Headroom 提供 Dashboard 和命令行统计。

1. 打开 Dashboard

1
headroom dashboard

不自动打开浏览器：

1
headroom dashboard --no-open

也可以直接访问：

1
http://127.0.0.1:8787/dashboard

Dashboard 通常可以查看：

请求数量；
原始 Token；
压缩后 Token；
节省的 Token；
压缩比例；
模型名称；
客户端来源；
请求延迟；
历史趋势。

2. 查看当前代理统计

1
curl http://127.0.0.1:8787/stats

3. 查看历史统计

1
curl http://127.0.0.1:8787/stats-history

4. 查看 Prometheus 指标

1
curl http://127.0.0.1:8787/metrics

5. 查看长期节省统计

1
headroom savings

输出 JSON：

1
headroom savings --json

查看最近 30 天：

1
headroom savings --days 30

清空统计：

1
headroom savings --reset

持久化统计和当前代理统计并不完全相同：

1
2
3
4
5
/stats
主要反映当前代理实例

headroom savings
主要反映跨启动、跨进程的长期记录

判断 Headroom 是否有效时，不应只看压缩比例。

还需要同时观察：

Claude Code 是否仍能正确完成任务；
是否遗漏关键日志；
修改代码是否准确；
响应延迟是否可以接受；
长会话是否更加稳定；
实际 Token 是否明显下降。

十三、使用 Headroom MCP

Headroom 可以作为 MCP Server，为支持 MCP 的客户端提供压缩和恢复工具。

1. 安装 MCP

1
headroom mcp install

2. 查看 MCP 状态

1
headroom mcp status

3. 启动 MCP Server

1
headroom mcp serve

4. 卸载 MCP

1
headroom mcp uninstall

Headroom MCP 主要提供以下能力：

1
2
3
4
5
6
7
8
headroom_compress
压缩指定内容

headroom_retrieve
恢复之前缓存的原始内容

headroom_stats
查看压缩统计

代理模式和 MCP 模式的区别如下：

方式	工作特点
Proxy	自动处理经过代理的请求
MCP	由 Agent 主动调用工具
Proxy + MCP	自动压缩，同时支持主动恢复原文

对于普通 Claude Code 和 Codex 用户，先使用 Proxy 即可。

只有在需要主动压缩某段内容、恢复原始数据或构建复杂 Agent 工作流时，再考虑启用 MCP。

十四、在 Python 中使用 Headroom

安装 Python SDK：

1
pip install "headroom-ai[all]"

基础示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from headroom import compress

messages = [
    {
        "role": "user",
        "content": "请分析下面的测试结果",
    },
    {
        "role": "user",
        "content": test_output,
    },
]

result = compress(
    messages,
    model="gpt-5",
)

print("原始 Token：", result.original_tokens)
print("节省 Token：", result.tokens_saved)
print("压缩比例：", result.compression_ratio)

optimized_messages = result.messages

将压缩结果传给 OpenAI SDK：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from openai import OpenAI
from headroom import compress

client = OpenAI()

messages = [
    {
        "role": "user",
        "content": "请分析下面的接口数据",
    },
    {
        "role": "user",
        "content": large_json_result,
    },
]

compressed = compress(
    messages,
    model="gpt-5",
)

response = client.chat.completions.create(
    model="gpt-5",
    messages=compressed.messages,
)

print(response.choices[0].message.content)

在生产环境中，建议同时记录：

1
2
3
4
5
6
原始 Token
压缩后 Token
压缩比例
请求延迟
模型回答质量
任务成功率

对于重要任务，还应保留未压缩请求作为对照。

十五、在 TypeScript 中使用 Headroom

安装：

1
npm install headroom-ai

TypeScript SDK 通常需要连接正在运行的 Headroom Proxy。

先启动代理：

1
headroom proxy

然后在项目中调用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import { compress } from "headroom-ai";

const messages = [
  {
    role: "user" as const,
    content: "请分析以下日志",
  },
  {
    role: "user" as const,
    content: largeLogOutput,
  },
];

const result = await compress(messages, {
  baseUrl: "http://127.0.0.1:8787",
  model: "gpt-5",
});

console.log(`Saved ${result.tokensSaved} tokens`);

const optimizedMessages = result.messages;

需要注意，npm 包主要提供 SDK。

以下命令通常来自 Python 安装的 Headroom CLI：

1
2
3
4
headroom proxy
headroom wrap
headroom install
headroom dashboard

因此，即使 TypeScript 项目使用 npm SDK，macOS 上仍可能需要单独安装 Python CLI。

十六、使用 Docker 部署

拉取镜像：

1
docker pull ghcr.io/headroomlabs-ai/headroom:latest

前台运行：

1
2
3
docker run --rm \
  -p 8787:8787 \
  ghcr.io/headroomlabs-ai/headroom:latest

后台运行：

1
2
3
4
5
docker run -d \
  --name headroom \
  --restart unless-stopped \
  -p 8787:8787 \
  ghcr.io/headroomlabs-ai/headroom:latest

检查服务：

1
curl http://127.0.0.1:8787/health

停止容器：

1
docker stop headroom

删除容器：

1
docker rm headroom

Docker 更适合以下场景：

Linux 服务器部署；
团队共享代理；
CI/CD 环境；
需要固定版本；
不希望直接安装 Python 依赖；
本机 Python 环境存在冲突。

如果只在个人 macOS 上使用 Claude Code 和 Codex，原生后台服务通常更方便。

十七、隐私与安全

Headroom 默认在本机运行，但经过 Headroom 优化后的请求仍然会发送给上游模型提供商。

完整链路是：

1
2
3
本地客户端
→ 本地 Headroom
→ Anthropic、OpenAI 或其他上游服务

因此，需要分别考虑两类安全问题。

1. Headroom 本地安全

建议：

默认只监听 127.0.0.1；
不直接暴露到公网；
不使用不必要的完整消息日志；
定期检查本地缓存和统计文件；
团队部署时增加身份认证；
使用防火墙限制访问来源。

2. 上游模型服务安全

即使使用 Headroom，最终请求仍会发送到模型提供商。

因此仍需关注：

API 服务商的数据使用政策；
企业数据保留规则；
源代码保密要求；
医疗、法律和财务数据合规；
API Key 管理；
团队权限控制。

Headroom 可以减少发送的数据量，但不能替代完整的数据安全和合规方案。

十八、常见问题排查

1. 找不到 headroom 命令

错误：

1
command not found: headroom

执行：

1
2
uv tool update-shell
exec zsh

检查：

1
2
command -v headroom
uv tool list

临时加入 PATH：

1
export PATH="$HOME/.local/bin:$PATH"

2. 8787 端口被占用

检查：

1
lsof -nP -iTCP:8787 -sTCP:LISTEN

换一个端口：

1
headroom proxy --port 8788

Claude Code 临时连接：

1
ANTHROPIC_BASE_URL=http://127.0.0.1:8788 claude

3. 后台服务无法启动

先查看状态：

1
headroom install status

然后重启：

1
headroom install restart

检查健康接口：

1
curl -s http://127.0.0.1:8787/health

如果仍然失败，可以先移除部署：

1
headroom install remove

然后重新安装：

1
2
3
4
5
6
7
headroom install apply \
  --preset persistent-service \
  --runtime python \
  --scope provider \
  --providers manual \
  --target claude \
  --target codex

4. Headroom 正常运行，但没有节省 Token

先确认请求是否经过 Headroom：

1
curl http://127.0.0.1:8787/stats

常见原因包括：

对话太短；
没有工具调用；
输入内容本身很少；
主要内容都是源代码；
工具结果已经足够精简；
当前内容低于压缩阈值；
客户端没有正确指向 Headroom。

可以使用以下内容进行测试：

大型测试日志；
数百条 JSON；
长搜索结果；
数据库查询结果；
多轮代码分析任务。

5. 响应变慢

压缩本身也需要计算资源。

如果启用了较复杂的文本压缩，首次加载可能出现额外延迟。

可以关闭较重的压缩模块：

1
headroom proxy --disable-kompress

也可以恢复默认 coding Profile，避免使用过于激进的配置。

评估时应同时比较：

1
2
3
4
Token 节省
响应延迟
回答质量
任务完成率

6. Claude Code 或 Codex 无法连接

先确认 Headroom 服务：

1
curl http://127.0.0.1:8787/health

再使用临时环境变量测试：

1
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

或者：

1
OPENAI_BASE_URL=http://127.0.0.1:8787/v1 codex

如果临时方式可以正常运行，说明 Headroom 服务正常，问题更可能出在客户端持久化配置。

此时可以重新应用配置：

1
headroom install remove

然后重新安装常驻服务。

十九、清理旧配置并重新安装

如果以前多次使用过：

1
2
3
4
headroom wrap claude
headroom wrap codex
headroom mcp install
headroom install apply

建议先完整撤销，再重新安装。

顺序很重要：先让 Headroom 恢复配置，再卸载程序。

1. 停止后台服务

1
headroom install stop 2>/dev/null || true

2. 删除持久化部署

1
headroom install remove 2>/dev/null || true

3. 撤销客户端集成

1
2
headroom unwrap claude 2>/dev/null || true
headroom unwrap codex 2>/dev/null || true

4. 删除 MCP 配置

1
headroom mcp uninstall 2>/dev/null || true

5. 卸载 Headroom

1
2
uv tool uninstall headroom-ai
hash -r

6. 备份旧数据

1
2
3
mv ~/.headroom \
  ~/.headroom.backup.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

确认不需要旧数据时，可以删除：

1
rm -rf ~/.headroom

不要直接删除：

1
2
~/.claude
~/.codex

因为这些目录还包含 Claude Code 和 Codex 自身的配置和历史。

7. 重新安装

1
2
3
uv tool install --python 3.13 "headroom-ai[all]"
uv tool update-shell
exec zsh

检查：

1
headroom --version

8. 重新配置后台服务

1
2
3
4
5
6
7
headroom install apply \
  --preset persistent-service \
  --runtime python \
  --scope provider \
  --providers manual \
  --target claude \
  --target codex

二十、完整卸载 Headroom

停止并移除后台服务：

1
2
headroom install stop 2>/dev/null || true
headroom install remove 2>/dev/null || true

撤销客户端集成：

1
2
headroom unwrap claude 2>/dev/null || true
headroom unwrap codex 2>/dev/null || true

卸载 MCP：

1
headroom mcp uninstall 2>/dev/null || true

卸载程序：

1
uv tool uninstall headroom-ai

可选：删除本地数据：

1
rm -rf ~/.headroom

最后检查：

1
2
command -v headroom
lsof -nP -iTCP:8787 -sTCP:LISTEN

如果两条命令都没有显示 Headroom 相关结果，说明清理基本完成。

二十一、macOS 推荐配置

对于每天使用 Claude Code 和 Codex 的用户，可以直接采用下面这套配置。

安装依赖

1
brew install uv python@3.13

安装 Headroom

1
2
3
4
5
6
uv tool install \
  --python 3.13 \
  "headroom-ai[all]"

uv tool update-shell
exec zsh

安装后台服务

1
2
3
4
5
6
7
headroom install apply \
  --preset persistent-service \
  --runtime python \
  --scope provider \
  --providers manual \
  --target claude \
  --target codex

验证服务

1
headroom install status

1
2
curl -s http://127.0.0.1:8787/health \
  | python3 -m json.tool

日常使用

1
claude

或者：

1
codex

查看统计

1
headroom dashboard

1
headroom savings

服务异常时

1
headroom install restart

临时停止

1
headroom install stop

恢复运行

1
headroom install start

完全撤销

1
headroom install remove

二十二、使用建议

Headroom 更适合以下情况：

经常使用 Claude Code 或 Codex；
使用按 Token 计费的 API；
工具会产生大量日志和 JSON；
需要处理大型代码仓库；
使用较多 MCP 工具；
经常进行长时间 Agent 会话；
上下文窗口容易快速增长；
希望统计长期 Token 消耗。

以下情况收益可能不明显：

主要进行短对话；
很少调用工具；
输入内容本身很短；
任务主要是阅读少量代码；
不使用按 Token 计费的接口；
对额外延迟非常敏感。

建议采用以下评估过程：

1
2
3
4
5
先使用默认 coding Profile
→ 完成几个真实开发任务
→ 查看 Dashboard 和 savings
→ 比较回答质量和响应延迟
→ 再决定是否调整压缩策略

不要仅根据一次短对话判断效果，也不要只追求更高的压缩比例。

真正需要关注的是：

模型能否准确理解任务；
代码修改是否正确；
重要错误是否被保留；
长会话是否更加稳定；
实际 Token 是否下降；
延迟是否在可接受范围内。

总结

Headroom 是一个位于 AI 客户端与上游模型服务之间的上下文优化层。

它的主要工作流程是：

1
2
3
4
5
6
识别内容类型
→ 压缩重复和低价值信息
→ 保留错误、异常和关键数据
→ 将优化后的请求发送给模型
→ 在需要时恢复原始内容
→ 记录 Token 和成本统计

对于 macOS 上长期使用 Claude Code 和 Codex 的用户，推荐将 Headroom 配置为后台服务：

1
2
3
4
5
6
7
headroom install apply \
  --preset persistent-service \
  --runtime python \
  --scope provider \
  --providers manual \
  --target claude \
  --target codex

完成配置后，可以继续按照原来的方式使用：

1
claude

或者：

1
codex

Headroom 会在后台自动处理请求，不再需要每次执行 headroom wrap。

一、Headroom 是什么#

二、为什么需要 Headroom#

三、Headroom 的工作原理#

1. 内容识别#

2. JSON 压缩#

3. 日志压缩#

4. 搜索结果压缩#

5. 代码处理#

6. 原始内容恢复#

四、安装 Headroom#

1. 安装 uv 和 Python#

2. 安装 Headroom#

3. 更新 Headroom#

五、临时使用：headroom wrap#

六、macOS 推荐方案：后台常驻运行#

1. 安装为后台服务#

2. 查看运行状态#

3. 检查健康接口#

4. 检查端口#

5. 日常使用#

七、后台服务管理#

八、直接运行 Headroom Proxy#

手动连接 Claude Code#

手动连接 OpenAI 兼容客户端#

九、压缩 Profile#

使用 coding#

使用 balanced#

使用 agent-90#

十、cache 模式与 token 模式#

1. cache 模式#

2. token 模式#

十一、配置上游网络代理#

十二、查看 Token 节省情况#

1. 打开 Dashboard#

2. 查看当前代理统计#

3. 查看历史统计#

4. 查看 Prometheus 指标#

5. 查看长期节省统计#

十三、使用 Headroom MCP#

1. 安装 MCP#

2. 查看 MCP 状态#

3. 启动 MCP Server#

4. 卸载 MCP#

十四、在 Python 中使用 Headroom#

十五、在 TypeScript 中使用 Headroom#

十六、使用 Docker 部署#

十七、隐私与安全#

1. Headroom 本地安全#

2. 上游模型服务安全#

十八、常见问题排查#

1. 找不到 headroom 命令#

2. 8787 端口被占用#

3. 后台服务无法启动#

4. Headroom 正常运行，但没有节省 Token#

5. 响应变慢#

6. Claude Code 或 Codex 无法连接#

十九、清理旧配置并重新安装#

1. 停止后台服务#

2. 删除持久化部署#

3. 撤销客户端集成#

4. 删除 MCP 配置#

5. 卸载 Headroom#

6. 备份旧数据#

7. 重新安装#

8. 重新配置后台服务#

二十、完整卸载 Headroom#

二十一、macOS 推荐配置#

安装依赖#

安装 Headroom#

安装后台服务#

验证服务#

日常使用#

查看统计#

服务异常时#

临时停止#

恢复运行#

完全撤销#

二十二、使用建议#

总结#