AI Agent 上下文压缩层，让 Codex 省 90% token
⭐ 开源免费Headroom 是一个面向 AI Agent 的「上下文压缩层」，在 GitHub 上已收获约 29K Star，采用 Apache-2.0 协议完全开源免费。它会在工具输出、日志、RAG 检索结果、文件、对话历史等内容送进大模型之前先做压缩，号称能减少 60~95% 的 token，而答案几乎不变。
它有三种用法：库（在 Python / TypeScript 里直接调用 compress()）、代理（headroom proxy，零改代码、任意语言可用）、MCP 服务。最实用的是一行命令给编程 Agent 套壳：headroom wrap codex / headroom wrap claude。配合 OpenAI 兼容接口，还能把 Codex 的请求转发到 DeepSeek、通义千问、Kimi 等国产大模型，既省 token 又能换更便宜的模型。所有处理都在本地完成，数据不出本机，压缩还可逆——原文会缓存，需要时让模型调用 headroom_retrieve 取回。
pip install "headroom-ai[all]"
npm install headroom-ai
需要 Python 3.10 及以上。Python 用户执行 pip install "headroom-ai[all]" 安装全部功能；Node / TypeScript 用户执行 npm install headroom-ai。也可以用 Docker 镜像运行（镜像地址见文末折叠的「相关链接」）。
一行命令即可：headroom wrap codex。Headroom 会自动识别上下文类型、选择合适的压缩算法（JSON、代码、长文本），在请求发给大模型前先压缩，全程本地运行。想看实际省了多少，执行 headroom perf 查看节省数据。
启动代理 headroom proxy --port 8787，它对外是 OpenAI 兼容接口。把 Codex / 客户端的 base_url 指向本地代理，并在代理配置里把上游换成 DeepSeek、通义千问、Kimi 等国产大模型的 OpenAI 兼容地址（填好对应 API Key），即可在压缩 token 的同时用上更便宜的国产模型。
官方在 GSM8K、TruthfulQA、SQuAD、BFCL 等标准基准上做了评测，准确率基本持平甚至略升（如 TruthfulQA +0.03）。它压的是冗余 token，不是关键信息，所以「同样的答案、零头的 token」。
不用。headroom proxy 是 drop-in 代理，任何语言、任何 OpenAI 兼容客户端把请求地址指过来即可；也可以用 headroom wrap codex/claude/cursor 一行命令套壳。只有想内联调用时才用 compress() 库。
Headroom 在本地运行，压缩过程数据不出本机；压缩可逆，原文会缓存、需要时取回。因为代理对外是 OpenAI 兼容接口，所以只要上游模型提供 OpenAI 兼容地址，DeepSeek、通义千问、Kimi 等国产大模型都能接入。
这通常是公司 SSL 拦截导致的。可先安装 Rust 工具链再装，或直接用预编译 wheel：pip install --only-binary headroom-ai headroom-ai，避开本地编译。