本手册涵盖从零开始安装 Headroom，并使其与 Claude Code 配合使用第三方 API（以智谱为例）的全过程，特别标注了所有踩坑点，助你一次成功。

📖 Headroom 项目简介

这是什么？

Headroom 是一个专为 AI 编程助手（如 Claude Code）设计的智能上下文压缩层。它在你发送请求给大模型之前，自动对提示词、文件内容、工具输出、日志等上下文进行无损/可逆压缩，从而显著减少 Token 消耗，降低 API 费用，且不影响回答质量。

核心特性

特性	说明
🗜️ 智能压缩	针对 JSON、代码、普通文本采用不同压缩策略（如 AST 压缩），平均节省 60%~95% 的输入 Token
🔒 数据本地化	所有压缩处理在本地完成，原始数据缓存在 ~/.headroom/，不上传云端
🔄 可逆查询	压缩是“可逆”的，若压缩后信息不足，AI 可主动调用工具取回原文，不影响准确性
🔌 零侵入接入	支持代理模式，无需修改 Claude Code 代码，一行命令即可 wrap
📊 实时统计	提供 HTTP 接口查看压缩率、节省 Token 数，效果看得见
🌐 模型无关	支持任意兼容 Anthropic API 格式的第三方服务（如智谱、DeepSeek、Together AI 等）

📌 前置条件

• 已有 Conda 环境（Miniconda/Anaconda）

• 已安装 Claude Code CLI，且能正常使用（你已通过 settings.json 配置了智谱 API）

• 网络正常（需要从 PyPI 下载包，建议使用清华源）

🚧 踩坑点总览（提前预警）

坑点	现象	解决方案
Python 版本不兼容	litellm 需要 Rust 编译，报错 error: subprocess-exited-with-error	必须使用 Python 3.11，避免 3.13
litellm 新版本无预编译包	安装 headroom-ai[proxy] 时卡在 Preparing metadata	手动安装 litellm==1.86.2，再安装 Headroom
ANTHROPIC_BASE_URL 冲突	启动后 401 Invalid bearer token	用环境变量覆盖，不修改 settings.json
Headroom 服务在后台才能生效	其他终端无法自动走代理	需手动设置 ANTHROPIC_BASE_URL 或使用启动脚本
模型切换后 Headroom 不识别	/model 切换后压缩统计不更新	创建 models.json，列出所有模型及上下文长度

🛠️ 步骤一：创建 Conda 环境并安装 Headroom

1.1 创建 Python 3.11 环境（务必）

踩坑：Python 3.13 会导致 litellm 编译失败。

conda create -n headroom-ai python=3.11 -y
conda activate headroom-ai

1.2 使用一条命令安装 Headroom（推荐）

pip install --no-cache-dir --only-binary :all: -i https://pypi.tuna.tsinghua.edu.cn/simple "headroom-ai[proxy]"

• --only-binary :all: 强制使用预编译包，避免源码编译。

• 如果此命令报错（极少数情况），可使用备用方案：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple litellm==1.86.2

pip install --no-deps -i https://pypi.tuna.tsinghua.edu.cn/simple "headroom-ai[proxy]"

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tiktoken pydantic httpx click

1.3 验证安装

headroom --version

正常输出如 0.32.1。

📁 步骤二：配置 Headroom 模型映射

Headroom 需要知道每个模型的上下文窗口才能准确压缩和统计。
在 C:\Users\xxx\.headroom\ 目录下（若无则手动创建）新建 models.json，内容示例（根据你的实际模型调整）：

json

{
  "glm-4.5-air": 128000,
  "glm-4.7": 128000,
  "glm-5.2[1M]": 1000000,
  "glm-4.5": 128000,
  "glm-4-plus": 128000,
  "glm-5": 1000000
}

模型名称需与 Claude Code 中 /model 切换时使用的名称完全一致。

可以把ccswitch里面的配置，或者claudecode自己设置的复制给deepseek让他帮你生成

🚀 步骤三：创建一键启动脚本

在桌面（或任意位置）新建 start_headroom.bat，内容如下：

@echo off
set ANTHROPIC_BASE_URL=http://127.0.0.1:8787
set ANTHROPIC_TARGET_API_URL=https://open.bigmodel.cn/api/anthropic
headroom wrap claude
pause

• ANTHROPIC_BASE_URL：指向 Headroom 本地代理。

• ANTHROPIC_TARGET_API_URL：你的第三方 API 地址（智谱），与 settings.json 中一致。

注意：不要修改 settings.json 中的 ANTHROPIC_BASE_URL，通过环境变量覆盖即可。

✅ 步骤四：启动并验证

4.1 启动 Headroom

双击 start_headroom.bat，或者命令./start_headroom.bat终端会显示：

Proxy ready on http://127.0.0.1:8787
Launching Claude Code...

同时 Claude Code 自动打开。

4.2 测试对话

在 Claude Code 中随便提问，确保正常回复，无 401 错误。

4.3 查看压缩统计

新开一个 PowerShell 窗口，执行：

bash

curl http://localhost:8787/stats

返回 JSON 中 "api_requests" 应 >0，表示请求已通过 Headroom。

🎉 最终成果

• ✅ Headroom 成功运行，压缩 API 输入 Token，节省费用。

• ✅ 原有 Claude Code 配置完全未改动，随时可回退直连。

• ✅ 模型切换灵活，只需维护 models.json。

• ✅ 一键启动，双击脚本即可。

若同时安装 Caveman 插件，可实现“输入+输出”双重压缩，进一步节省 Token。祝使用愉快！