Headroom 是怎么给 Codex 省 Token 的：策略、效果与一次历史恢复记录

预计完整阅读时间：10-12 分钟

阅读对象与阅读路径

这篇文章主要面向下面几类读者：

正在使用 Codex、Claude Code、Cursor 等 AI Coding Agent，希望降低 token 消耗的人；
经常让 Agent 读代码、跑命令、分析日志、处理长上下文任务的人；
想了解 Headroom、LLMLingua、Caveman、LiteLLM 等 token 优化工具区别的人；
已经接入 Headroom，但遇到 Codex 历史对话、归档对话不可见问题的人。

如果你只关心不同问题，可以按下面路径阅读：

目标	推荐阅读路径	预计时间
快速了解 Headroom 是什么	第 1 章 → 第 2 章 → 第 10 章	3 分钟
判断 Headroom 是否适合 Codex	第 1 章 → 第 5 章 → 第 6 章 → 第 10 章	4 分钟
了解我的安装环境和实际节省效果	第 3 章 → 第 6 章	2 分钟
了解 Headroom 的压缩策略	第 2 章 → 第 4 章 → 第 5 章	5 分钟
对比同类工具怎么选	第 7 章 → 第 10 章	4 分钟
只看 Codex 历史对话恢复踩坑	第 8 章 → 第 9 章	4 分钟
准备自己接入 Headroom	第 3 章 → 第 9 章 → 第 11 章	5 分钟
完整阅读	第 1 章 → 第 11 章	10-12 分钟

如果你已经知道 Headroom 是什么，只想看我的实际经验，可以直接从第 3 章开始。

如果你已经遇到 Codex 历史对话不见的问题，可以直接跳到第 8 章和第 9 章。

前言

最近我在本地 Codex Desktop 里接入了 Headroom。它的作用是在请求真正发给模型之前，对上下文做压缩和整理，从而减少 token 消耗。

AI Agent 在真实使用时，token 消耗往往不是来自用户输入的一句话，而是来自上下文里的大量工具输出：代码搜索结果、终端日志、报错堆栈、文件内容、长对话历史、RAG 片段等。

Headroom 的价值就在这里：它不是替代模型，而是在模型前面加一层上下文压缩层，让模型收到更短、更聚焦的上下文。

1. 背景：为什么我需要 Headroom

我平时使用 Codex 比较多，尤其是在大型前端项目、微前端项目、日志排查和代码审查里。

这类任务有几个特点：

复制代码

上下文很长
工具调用很多
终端输出很多
代码搜索结果很多
对话轮次很多

比如 Codex 为了分析一个问题，可能会：

搜索多个文件；
读取大段源码；
跑测试或构建命令；
分析报错日志；
对比 git diff；
反复根据结果继续定位。

这些内容都会进入上下文。上下文越长，token 消耗越高，模型也越容易被噪音干扰。

所以我想找一个工具，在不改变 Codex 使用方式的前提下，自动压缩这些上下文。

这就是我尝试 Headroom 的原因。

2. Headroom 是什么

Headroom 可以理解为 AI Agent 和模型之间的一层上下文压缩代理。

它可以作为：

lua 复制代码

proxy
wrap
MCP server
Python / TypeScript 库

来使用。

它的核心目标是：

复制代码

在请求进入模型之前，先压缩上下文。

整体链路大概是：

复制代码

Codex / Agent
  ↓
工具输出、日志、文件内容、历史对话
  ↓
Headroom 压缩与整理
  ↓
更短的上下文
  ↓
LLM Provider

也就是说，Headroom 不是让模型更聪明，而是让模型少看无效内容。

3. 我的安装环境

这次我的本机环境如下：

objectivec 复制代码

系统：Windows 11
系统版本：10.0.26200
Python：3.14.3
Headroom CLI：0.28.0

运行 headroom doctor 后，状态大致如下：

python 复制代码

Headroom Doctor v0.28.0 · port 8787

proxy       pass   running at http://127.0.0.1:8787
version     pass   proxy matches installed v0.28.0
codex       pass   routed (C:\Users\<用户名>.codex\config.toml)
shell env   pass   routed via ANTHROPIC_BASE_URL
savings     pass   9,371,594 tokens / $44.61 saved lifetime
budget      warn   no budget configured

说明 Headroom 已经成功接入 Codex 请求链路，并且 proxy 正在本机 8787 端口运行。

4. Headroom 的压缩策略

Headroom 不是简单粗暴地截断上下文。它更像是根据不同内容类型选择不同压缩策略。

4.1 普通文本压缩

普通文本包括：

复制代码

README
需求说明
长对话历史
普通文档
RAG 检索片段

这类内容的特点是信息密度不均匀。很多段落只是解释、铺垫或重复表达，真正重要的是：

复制代码

主题
目标
约束
结论
关键事实

Headroom 会尽量保留这些信息，压缩掉低价值表达。

4.2 代码与结构化内容压缩

代码不能像普通文本一样随便摘要。

如果把代码压缩得太狠，很容易丢掉：

复制代码

变量名
函数名
调用关系
错误位置
导入关系
配置项

对 Codex 来说，分析代码时最重要的往往不是完整文件，而是：

复制代码

文件路径
函数名
类名
关键调用链
错误行附近内容
相关配置

Headroom 的代码类压缩更偏向保留结构信息，而不是单纯生成自然语言摘要。

4.3 JSON / 配置类内容压缩

工具输出、接口响应、配置文件经常是 JSON 或类似结构化数据。

例如：

go 复制代码

API 响应
package.json
配置文件
工具调用结果
结构化日志

这类内容如果原样传给模型，token 消耗很高。但如果压成普通自然语言，又可能丢失字段结构。

所以这类压缩重点是：

复制代码

保留结构
保留关键字段
去掉重复对象
去掉无关字段

4.4 日志和终端输出压缩

日志是最容易浪费 token 的内容之一。

一次构建失败、测试失败或服务启动，可能输出几百上千行。但真正重要的通常是：

复制代码

错误类型
异常堆栈
失败命令
关键 warning
首次出错位置
重复错误归并

Headroom 对这类内容的价值很明显：它可以减少大量重复日志，让模型更快看到核心错误。

4.5 可恢复压缩

Headroom 的一个重要思路是，压缩后的上下文变短，但原始内容不一定完全丢弃。

可以理解为：

复制代码

默认给模型压缩版
需要细节时再取原文

这种方式比一次性把所有原始内容塞进模型更经济。

4.6 代理层统计与预算控制

Headroom 作为 proxy 运行时，还可以统计 token savings，也可以配置 budget。

我当前看到的统计是：

bash 复制代码

9,371,594 tokens / $44.61 saved lifetime

同时它也提示：

perl 复制代码

budget warn: no budget configured

说明它不仅能做上下文压缩，也能作为请求链路上的成本观察层。

5. 为什么它适合 Codex

Codex 的典型任务天然适合上下文压缩。

因为 Codex 经常需要：

复制代码

搜索代码
读取文件
运行测试
分析构建日志
对比 diff
跨多个文件追踪问题
长时间多轮调试

这些操作都会产生大量上下文。

Codex 最大的问题不是不会分析，而是经常需要把大量工具输出塞给模型。Headroom 的价值就在于减少这些上下文里的噪音和重复内容。

对我来说，它最适合这些场景：

复制代码

大型前端项目排错
微前端问题分析
终端日志分析
代码审查
长时间多轮调试
历史上下文较长的任务

6. 实际效果

从当前 Headroom 的统计来看，我已经累计节省：

bash 复制代码

9,371,594 tokens
约 $44.61

这个数字不是理论估算，而是 Headroom proxy 统计出来的实际结果。

当然，节省效果和任务类型有关。

如果只是短问短答，收益不会特别明显。

如果是长任务、代码搜索、日志分析、多轮调试，收益就会更明显。

7. 和同类型工具的对比

Headroom 不是唯一做 token 优化的工具。同类方案大致可以分成几类：

复制代码

Agent 上下文压缩
Prompt / 文本压缩
输出风格压缩
RAG 检索压缩
模型代理和成本网关
模型侧缓存

对比表

工具/方案	主要作用	更适合的场景	和 Headroom 的区别
Headroom	Agent 上下文压缩、proxy、wrap、MCP、成本统计	Codex、Claude Code、Cursor 这类长任务 Agent	更偏完整 Agent 请求链路，在模型请求前自动压缩上下文
Caveman	让模型用更极简的表达方式，减少输出 token	减少助手回复废话、压缩说明文档、压缩长期记忆	更偏输出风格或文本层压缩，通常不负责代理请求链路
LLMLingua / LLMLingua-2	Prompt compression	单次长 prompt 压缩、自研应用内集成	更像压缩算法或库，需要自己接入工作流
LangChain Contextual Compression	RAG 检索结果压缩	知识库问答、文档检索	主要压缩 retriever 返回的文档，不是完整 Agent 上下文
OpenAI Prompt Caching	缓存重复 prompt 前缀，降低重复输入成本和延迟	固定系统提示词、重复上下文、多轮相似请求	不压缩内容，依赖重复前缀命中缓存
LiteLLM Proxy	多模型代理、路由、成本统计、预算控制	团队模型网关、多模型统一入口	更偏模型网关和成本治理，不负责语义压缩

Headroom vs Caveman

Caveman 这类思路的核心是：让模型少说废话。

正常回答里经常会有很多"胶水词"，例如：

复制代码

当然可以
我们可以看到
这个问题的本质是
因此可以得出

Caveman 风格会让输出更短、更密集，例如：

javascript 复制代码

问题：provider 不一致
原因：旧线程 openai，新线程 headroom
修复：改 state_5.sqlite + JSONL meta

它的优势是：

复制代码

减少输出 token
回复更短
信息密度更高
多轮任务里历史上下文更小

但它和 Headroom 的切入点不一样：

复制代码

Caveman：让模型少说废话
Headroom：让模型少接收无效上下文

也就是说：

Caveman 更偏输出风格压缩；
Headroom 更偏输入上下文压缩；
Caveman 通常靠 prompt 或 skill 约束模型表达；
Headroom 运行在请求链路上，可以做 proxy、统计 savings、路由 Codex。

两者可以组合使用：

复制代码

Codex
  ↓
Caveman：减少 Agent 输出废话
  ↓
Headroom：压缩进入模型的上下文
  ↓
LLM Provider

不过 Caveman 也有风险：如果压缩太狠，可能影响可读性，甚至丢掉条件、边界和安全说明。所以它适合技术密集型输出，不太适合不可逆操作、安全确认、复杂决策说明。

Headroom vs LLMLingua

LLMLingua 是更典型的 prompt compression 工具。

简单说：

复制代码

LLMLingua：我有一段 prompt，要压缩它
Headroom：我有一个 Agent，希望它整个上下文链路自动压缩

如果你在写自己的应用，LLMLingua 作为库接入会更自然。

如果你已经在用 Codex、Claude Code、Cursor，Headroom 这种 proxy/wrap 方式更贴近使用场景。

Headroom vs LangChain Contextual Compression

LangChain Contextual Compression 主要处理 RAG 检索结果。

它解决的是：

复制代码

检索出来的文档太长、太多、太杂

Headroom 处理的是更宽泛的 Agent 上下文：

复制代码

日志
文件
工具输出
搜索结果
历史消息
RAG 片段

所以如果你做的是知识库问答，LangChain contextual compression 很合适。

如果你优化的是 Codex 这类 Coding Agent 的整体上下文，Headroom 更贴近。

Headroom vs Prompt Caching

Prompt Caching 不是压缩，而是缓存重复前缀。

它适合：

复制代码

系统提示词很长
前半段上下文稳定
多次请求重复结构明显

Headroom 不要求上下文重复。它处理的是每次请求中新产生的大量内容，比如日志、搜索结果、文件片段。

可以理解为：

复制代码

Prompt Caching：重复内容便宜点
Headroom：非重复内容少传点

Headroom vs LiteLLM

LiteLLM Proxy 更像多模型网关，重点是：

复制代码

模型路由
统一 API
成本统计
预算控制
团队用量管理

Headroom 的重点是：

复制代码

减少传给模型的上下文本身

两者可以互补：

复制代码

Agent
  ↓
Headroom 压缩上下文
  ↓
LiteLLM 做模型路由和预算
  ↓
模型服务

小结

如果按使用目标来选：

css 复制代码

想让 Codex / Claude Code 这类 Agent 自动少传上下文：Headroom
想让模型少说废话、减少输出 token：Caveman
想压缩单段 prompt：LLMLingua
想压缩 RAG 检索结果：LangChain Contextual Compression
想复用重复 prompt 前缀：Prompt Caching
想做多模型网关和预算治理：LiteLLM

我这次选择 Headroom，主要原因是我的目标不是单独压缩某一段 prompt，也不是只想让模型回复短一点，而是希望 Codex 在读代码、跑命令、看日志、长对话时，整个请求链路都能自动减少上下文开销。

8. 简略踩坑记录：Codex 历史对话不可见

接入 Headroom 后，我遇到过一次 Codex Desktop 历史对话不可见的问题。

现象是：

复制代码

Codex Desktop 只显示少量新对话
旧历史找不到
部分已归档历史也找不到

最终确认数据没有丢，主要是几个本地状态不一致。

9. 接入建议

如果你也准备在 Codex Desktop 里接入 Headroom，建议先备份：

makefile 复制代码

C:\Users<用户名>.codex\state_5.sqlite
C:\Users<用户名>.codex\session_index.jsonl
C:\Users<用户名>.codex\sessions
C:\Users<用户名>.codex\archived_sessions

接入后先运行：

复制代码

headroom doctor

重点确认：

复制代码

proxy 是否运行
Codex 是否 routed
版本是否匹配
是否产生 savings
budget 是否需要配置

如果历史对话暂时看不到，不要先删 .codex。

优先检查：

复制代码

model_provider
session_index.jsonl
archived_sessions
cwd

10. 总结

Headroom 对 Codex 这类 AI Coding Agent 的价值，主要不在于让模型变聪明，而在于让模型少看无效上下文。

它通过代理层压缩工具输出、日志、文件内容、历史对话和结构化数据，减少 token 浪费。

我的实际使用结果是：

bash 复制代码

Headroom 版本：0.28.0
Codex routed：成功
累计节省：9,371,594 tokens
约节省：$44.61

如果你的使用场景是短问短答，Headroom 的收益可能不明显。

但如果你经常用 Codex 做长任务、排查问题、读代码、看日志，它的价值会更明显。

整体来说，Headroom 值得在 Codex 这类重上下文场景里尝试。只是接入前最好备份 .codex，避免历史索引、provider 或归档状态变化时误以为数据丢失。

11. 参考链接

ruby 复制代码

Headroom:
https://github.com/headroomlabs-ai/headroom

Headroom 官网:
https://headroomlabs.ai/

LLMLingua:
https://github.com/microsoft/LLMLingua

LangChain Contextual Compression:
https://python.langchain.com/docs/how_to/contextual_compression/

OpenAI Prompt Caching:
https://platform.openai.com/docs/guides/prompt-caching

LiteLLM:
https://docs.litellm.ai/

Caveman:
https://github.com/juliusbrussee/caveman

Caveman Compression:
https://github.com/wilpel/caveman-compression

我的 Headroom 历史恢复 Skill:
https://github.com/GrayJS/headroom-history-recovery-skill