最近两周我一直在折腾一件事把 Claude Code 和 opencode 的 API 请求都改道到本地的 Headroom 代理上让它先压缩一遍对话历史再发往模型服务端。起因很实际——前阵子接手一个不算小的代码库一次连续几小时的重构会话结束后我看了一眼后台账单那个 token 总量确实让我心里一沉。其实代码生成代理本身很省心真正的问题在于它会把整段对话史一次又一次地原样搬运给模型任务越做越大单轮请求的 tokens 就越滚越夸张。这篇文章就围绕 Headroom 这个本地上下文压缩代理展开我会从长会话为什么费 tokens 的底层逻辑讲起拆解它的压缩机制再分别给出 Claude Code 和 opencode 的完整接入步骤、实测数据以及我踩过的几个坑。如果你也在用这类编码代理做长时间、大范围的重构任务尤其是对 token 账单开始敏感的时候这篇内容应该能帮你省下一笔实实在在的开支同时把延迟体感稳住。1. 长会话烧钱的核心机制每次请求都在重新看一遍历史1.1 无状态 API 下的消息搬运逻辑很多人刚使用这类编码代理时会有一个朴素的想法AI 应该记得我们之前聊过什么。实际上大模型 API 是无状态的——模型本身不保存任何会话记忆它能记得的唯一方式就是客户端在每次请求里把对话历史以 messages 数组的形式完整地再发送一遍。你的每一条指令、它的每一段回答、每一次工具运行返回的文件内容全都打包在请求里。这就带来一个很直白的成本公式连续对话越久历史消息越多每一轮新请求的输入 tokens 就越重。以代码任务为例我那个项目做到中后期时会话日志显示的上下文长度经常超过 10 万个 token。10 万 token 是什么概念按主流模型的价格粗算一次请求光是输入就要花掉一笔不小的费用而一次重构会话动辄几十上百轮请求每一轮都是这个量级。所以问题的本质不是我让 AI 干太多活而是每一轮干活时它都要把前面所有聊过的内容重新付一次费。1.2 代码任务里哪些消息最占体积既然要省钱就得先弄清楚钱花在哪。我统计过自己几个代码会话的消息构成跟很多人直觉不同真正占大头的往往不是用户和助手之间的对话文字而是工具运行产生的结构化输出。文件读取结果让 AI 看某个文件时工具会把整个文件内容塞进 messages。一个几百行的源码文件就是几千 token几个文件加起来立刻破万。日志与命令输出跑测试、执行构建、查看报错时终端输出会整段进入上下文。一个不长的报错堆栈往往就有 1000~3000 token而一些日志框架打印出的调试信息动辄上万。diff 片段生成修改后很多代理会把 diff 或整个更新后的文件重新放回对话确认它理解了改动。这个体积也不小。这些结构性内容有一个特点它们对当前决策有短期价值但对整段历史而言很多是冗余的。比如前 10 轮勘测文件时的完整内容到第 40 轮真正写代码时早已不重要了。而代理每次还是会原样带上这就给了压缩很大的操作空间。1.3 为什么压缩要在请求发出之前做针对这个问题其实有几种不同的省钱思路。第一种是改 prompt让模型少说话、少分析这个能控制生成端的 tokens但对输入端的搬运费几乎无效——因为历史消息该多长还是多长。第二种是依赖模型服务端自带的上下文管理能力让服务方在超长上下文中自动做某种程度的裁剪或汇总。但这有两点不好把控一是它的处理对你完全黑盒你不知道什么时候被截掉了什么二是它通常是在上下文已经撑到某个较大阈值之后才动手前面该花的钱已经花了。第三种就是 Headroom 这类本地代理的思路在请求真正离开你机器之前先由本地程序把 messages 数组打开按你定义的规则做压缩然后把瘦身后的请求转发给上游。换句话说压缩决策完全由本地规则掌控你可以自定义保护哪些内容、压缩哪些内容、用什么方式压。代理还能顺便打印处理前后的 token 数每一笔账都能看到这是我比较喜欢它的原因。2. Headroom 的压缩机制拆解截断、摘要与结构保留2.1 三个层次的压缩策略Headroom 不是说把历史砍掉三分之一这么简单粗暴。我实际用下来它的压缩是分层次的每个层面解决不同类型消息的冗余问题。第一层是丢弃策略。适合处理那些已经彻底失去价值的内容比如早期轮次里的普通寒暄、重复确认、被后续消息覆盖的中间状态。举一个例子会话第七轮用户让 AI 列出项目的目录结构AI 回了一段文字这个信息在第二十轮之后基本没有任何用处整条删除毫无影响。第二层是摘要策略。这是压缩的主力。Headroom 会把较早的、但可能还有部分参考价值的对话轮次调用一个轻量模型比如更小更便宜的模型或者本地跑的小模型生成一段简洁摘要然后用这段几十到几百 token 的摘要替换原本可能上万 token 的完整消息。摘要保留的是当时的意图、关键结论、已确认的约束丢掉的是中间的论证过程和大段代码输出。第三层是结构精缩。它专门处理那些包含大段结构化文本的消息比如工具返回的完整文件内容、冗长 stdout。这类消息不宜整个删除但可以把日志块按行裁剪只保留首尾和包含错误关键字的段落。2.2 关于哪些上下文必须保留的判断规则我一开始最担心的是压缩会不会把模型真正需要的信息压掉实际配置下来Headroom 的默认规则和我的直觉比较吻合它遵循的是近期完整保留、早期轻重处理的优先级逻辑。必须原样保留的部分我总结下来是这四类系统提示词的核心段落整个会话运行时的基础规则这个不能动。最新一条用户消息这是当前任务最直接的指令无论如何都要完整保留。最近若干轮的完整消息默认通常 3~5 轮这些是当前推理的直接上下文工具调用和工具结果在近几轮里的对应关系也在这里压坏会导致行为错乱。用户显式钉住的规则比如你在会话里说之后所有方案都要遵守 A 约束这类全局约束如果被摘要含糊化后面很容易跑偏。可压缩的部分则是更早轮次的完整原文、过大且不再被引用的日志输出、已经被后续文件版本覆盖的旧文件内容。这类内容的价值曲线是快速衰减的——离当前越远价值越低压缩越安全。2.3 每次请求的压缩流水线Headroom 处理一次请求的完整流程理解它有助于你配置更合理。我调试时观察到的默认处理顺序大致是这样的请求进入本地代理代理解析出 messages 数组统计每个消息的角色、类型和 token 估算值。判断整组消息的总体积是否超过你设定的压缩阈值比如 80k tokens低于阈值就直接放行。超过阈值后从最早的轮次开始向前扫描先应用丢弃策略再对剩余消息应用摘要策略最后对超大工具输出做行级裁剪。压缩完成后重新计算 token 数将瘦身后的请求转发到上游同时把处理前后的 token 数字写入日志。上游返回的流式响应原样透传代理不做额外干预。关键点在第三步它只从早期往中期处理最近几轮永远保持完整。所以它的逻辑本质是确保模型对当前工作状态有完整的近期记忆对早期历史只有概要级认知这跟人类接手一个旧项目时的信息处理方式很像。3. 给 Claude Code 接入 Headroom 的每一步3.1 准备本地代理服务Headroom 是以本地独立服务的方式运行的。我是在 GitHub 上找到这个项目之后直接拉代码编译的好在项目没有太多依赖构建过程很顺利。如果你不想编译也可以直接用发布页的预编译二进制。启动前置条件其实只有一个你原本就有的模型服务API Key。代理本身不负责鉴权它只是转发所以这个 key 会继续用在转发请求上。我把整个部署过程整理成了以下四步每一步都是亲测可行的克隆项目到本地目录进入项目根目录执行构建命令生成headroom可执行文件。在同目录下创建headroom.yaml配置文件里面写明上游 API 地址、要使用的轻量摘要模型标识、压缩阈值和保留轮数等参数。执行启动命令让代理监听本地端口。此时代理服务就位正常情况下终端会打印出监听地址接下来在另一个终端用请求验证服务状态。一个最小可用的配置文件大概长这样upstream: https://api.anthropic.com summary_model: light-model-id # 用于生成历史摘要的轻量模型 compress_threshold: 80_000 # 总上下文超过 80k 才触发压缩 keep_recent_rounds: 5 # 保留最近 5 轮完整消息 listen: 127.0.0.1:3000启动命令也很简单就是一个服务启动指令headroom serve --config headroom.yaml启动后我在另一个终端跑了一次健康检查确认端口已在监听。代理正常响应之后下面就可以让 Claude Code 改道了。3.2 设置环境变量并验证生效Claude Code 支持通过环境变量来指定 API 端点这也是它接入代理类工具的标准做法。我们要做的是把默认端点改成指向本地 Headroom。在启动 Claude Code 之前在当前 shell 里导出两个关键环境变量export ANTHROPIC_BASE_URLhttp://localhost:3000 export ANTHROPIC_API_KEY你的原版key这里有个容易忽略的点ANTHROPIC_BASE_URL改到本地之后ANTHROPIC_API_KEY仍然保留原值但 Headroom 转发时会带着它去上游做鉴权。如果你只在代理配置文件里写了上游地址而没转发 key请求会直接在上游被拒。改完之后怎么确认生效我的方法非常朴素在 Claude Code 里随便问一句你现在请求的 API 地址是什么风格的然后把代理日志打开能看到有请求进来并看到 Headroom 打印的转发记录这就说明环境变量已经起效。更直接的判断方式是看代理终端的轮询输出——里面有每一个进站请求的处理状态。3.3 从代理日志确认压缩生效我真正感到踏实的那一刻是看到代理日志里出现了 before / after 的 token 对比。比如一次原本携带约 110k tokens 的请求经过处理后变成约 62k日志清晰打印了压缩前后的数字和压缩率。这意味着从那轮起转发到上游的计算量已经肉眼可见地下降。你不需要专门去看账单也能判断压缩在生效只需要关注日志里的这个数字走势。如果你发现日志没有这些字段检查一下配置文件里的日志级别把它调成 verbose 或 debug 模式细节就会出来。这一步非常重要因为没有这些数字你根本无法量化工具到底给你省了多少调参就是在盲调。4. opencode 接入路径配置差异与踩点4.1 在 opencode 里指定本地端点opencode 是我最近几个月开始用的另一个编码代理它的配置思路跟 Claude Code 不太一样不是纯环境变量驱动而是通过配置文件来声明 provider 和模型。我在 opencode 里接入 Headroom 的做法是在它的配置文件里新增一个虚拟的 provider把 baseURL 指到本地http://localhost:3000然后指定模型 ID。这样 opencode 的所有请求都会发往 Headroom由代理压缩后再转发给上游模型服务。配置的关键点在于provider 名称可以随便起但模型 ID 必须和上游模型实际使用的标识完全一致否则代理转发时上游会因为模型名不认识而直接报错。我第一次就栽在这个上面后面踩坑部分会详细说。4.2 与 Claude Code 接入的差异对比两个工具接同一个代理体验上有几个明显的不一样。我整理成一张表方便你对照排查问题对比项Claude Code 接入方式opencode 接入方式端点配置环境变量ANTHROPIC_BASE_URL配置文件中的 provider baseURL鉴权方式沿用ANTHROPIC_API_KEY在 provider 配置里单独声明 key 字段模型指定默认跟随端点协议较透明必须显式写模型 ID写错就报错日志可见性代理日志可直接看到请求代理日志 opencode 自身日志双端核对工具调用消息压缩后暂未发现结构性问题对 tool_use 消息的顺序更敏感压缩档位要更保守从稳定性的角度来说opencode 走本地代理时对消息顺序更加敏感。原因我推测跟它的 tool_use/tool_result 配对校验逻辑有关如果代理把早期工具调用消息摘要掉而后续某条消息还在引用那个工具编号就可能导致关联失败。后面踩坑部分我会专门展开这个问题和应对办法。5. 实测结果Token 省了多少延迟和正确性发生了什么5.1 三个任务场景的实测数据只看机制难免纸上谈兵我把 Headroom 接好之后分三个任务场景各跑了一周左右记录的都是真实会话数据。这里先说明一点我的配置是压缩阈值 80k、保留最近 5 轮完整消息这个偏保守的档位是我在稳定性优先时期的选择。任务类型会话时长平均单轮输入 tokens压缩前平均单轮输入 tokens压缩后整体估算节省长会话调试排查一个偶发崩溃3 小时96k38k约 58%多文件重构拆分模块并迁移逻辑2.5 小时104k60k约 42%新项目脚手架搭建40 分钟42k31k约 25%三个场景差异很明显。新项目因为会话短、历史薄压缩空间本来就不大而长会话调试场景里因为有一大堆早期运行的日志输出和大量试错记录压缩比例最高。多文件重构中间因为需要持续参考多个文件内容很多近期上下文不能压所以最终节省比例落在中间水平。5.2 延迟体感与摘要开销很多人会担心做摘要本身也要调用一次模型会不会反而拖慢速度实测来看摘要的生成任务很轻通常只需要 0.3 到 1.2 秒就完成这段开销发生在请求发出之前。但省下几十 k tokens 之后上游模型的 prefill 时间明显缩短——因为要处理的输入变少了首字返回的等待时间反而下降。我自己的体感是整体首字延迟基本持平部分超大上下文请求甚至感觉变快了一点。这个小幅度的延迟增加远没有想象中碍事尤其是在动辄几十万 tokens 的会话场景里哪怕为了压缩多等 1 秒后续整轮请求模型处理都会轻快很多。5.3 正确性观察与补救方法压缩最大的风险永远是信息丢失。我观察到的现象是模型对近期任务执行的理解几乎不受影响但在极少数情况下会表现出对早期指令的模糊记忆——不是完全忘掉而是执行时细节有所偏差。比如会话开始时的某个全局约束压缩后模型仍然知道有这条规则但具体到某个边界值必须怎么处理这类细节时出现过一次偏差。我的补救办法很简单把那些无论如何都不能丢的约束在最新一条消息里再强调一遍。或者在配置里利用规则钉住特定关键词让代理碰到包含这些词的早期消息时跳过压缩。这两个方法结合下来正确性偏差在我的场景里降到了可以忽略的程度。6. 踩坑清单三个让我浪费时间的真实问题6.1 工具调用消息被压坏导致工具行为错乱这是我最先遇到、也最难排查的问题。现象是接入 Headroom 后某次改造任务进行到中段Claude Code 突然开始反复请求同一个工具或者声称收到了格式不对的工具结果。后来我把代理日志和原始请求抓出来对比发现问题出在压缩策略把某个早期轮次的 tool_use 消息摘要掉了但对应轮次的 tool_result 因为某种规则被保留了下来导致后面的模型拿到结果却找不到发起调用的记录上下文对不上。解决办法是在配置文件里设定规则凡是包含 tool_use 或 tool_result 的轮次必须整轮保留不得单独压缩其中单条消息。同时把保留轮数从 3 提到 5给工具调用留出更宽裕的完整空间。从那之后这个现象再没出现过。6.2 SSE 流式格式被代理改写后报错第二个坑出现在流式响应上。第一次接入时代理对上游返回的 SSEServer-Sent Events数据做了一些规范化处理结果 Claude Code 端直接抛了流解析错误表现为响应写到一半突然中断或者界面卡住不输出。原因不复杂这些编码代理对 SSE 事件的类型、字段顺序有严格预期任何中间层的改写都可能破坏这个契约。解决方式是在 Headroom 配置里把流式响应设为纯透传模式保证事件字节流原样到达客户端。这个坑提醒我代理的职责应该严格限定在请求出去之前的压缩响应路径能不碰就不碰。6.3 API key 环境变量混淆导致上游拒绝第三个坑纯属配置粗心。我在环境变量里同时配置了给 Claude Code 用的 key又在 Headroom 的配置里另设了一个 key 字段结果上游一直返回鉴权错误。那个下午我一度以为是代理解析问题最后检查才发现Headroom 读取的 key 优先级和我预想的不一样两处配置不一致转发时用了空值或错误值。这里分享一个经验两边的鉴权信息始终保持完全一致并且在代理日志里确认转发时带上的 key 前缀是否正确。大多数服务端的 key 都有明确前缀或格式特征日志里肉眼看一下就能确认。这类问题通常不是配置复杂而是多处的值没有同步。6.4 快速自查表结合上面几个坑我整理了一份快速自查清单接入遇到问题可以逐条过一遍代理服务是否启动成功健康检查是否返回正常。客户端的环境变量或 provider 配置是否指向了正确的本地端口。鉴权 key 是否在客户端和代理配置里保持一致。日志里能否看到请求进入代理以及 before/after tokens 数据。若出现工具行为异常检查是否压到了 tool_use/tool_result 消息。若出现流式中断检查代理是否对响应做过任何改写切换到纯透传模式。7. 调优建议不同任务应该怎么选压缩策略7.1 三个实用档位的配置参考跑了一段时间之后我把自己的调参经验归纳成三个档位供你按任务类型参考。保守档压缩阈值调高如 120k保留轮数调多如 8 轮摘要仅针对最早 30% 的轮次。适合代码审查、多文件重构这类对上下文完整性要求很高的任务稳定第一节省其次。均衡档阈值 80k保留 5 轮老轮次统一摘要。适合日常开发、Bug 排查这类会话是我主力使用的配置。激进档阈值 50k保留 3 轮对超大工具输出做行级裁剪。适合长会话调试、重复试错较多的场景省得最多但需要你养成关键约束随手重述的习惯。三个档位的本质区别在于你更信任模型对近期上下文的利用能力还是更需要它从历史里挖掘信息的宽度。没有绝对正确的答案只有跟任务匹配的选择。7.2 针对代码任务的几条实战心得最后分享几个我在调优过程中沉淀下来的实际体会。第一摘要模型的选择会影响压缩质量。一开始我用默认的轻量模型做摘要发现它偶尔会把关键约束概括得过于笼统。后来换成了质量更高一档的模型摘要质量上来之后后续对话走偏的概率明显下降。摘要模型的开销确实多了一点但换来的是更可靠的上下文值。第二定期把长会话拆分成短会话。即使是带压缩代理我也建议超过三个小时的连续任务停下来开一个新会话来继续。压缩能降低历史搬运的成本但不能消除所有累积问题。新会话配合一个写清约束的初始提示效果往往比硬撑一个超长会话更好。第三日志数据是调参的唯一依据。刚开始我全凭感觉调阈值后来认真记录每轮会话的 before/after tokens 数据才能确定哪些配置真正有效。如果你跑了一周代理却完全没看过日志数据那基本等于白接。把日志存下来隔几天翻一翻你会看到哪些任务的压缩率最低那就是你下一个优化的方向。我自己目前的配置是均衡档加保守的摘要模型选项同时把工具消息保护规则开着。接进 Claude Code 和 opencode 之后日常开发几乎感受不到代理的存在——它就像在请求出口处多装了一道不起眼的闸门安静地帮我省掉了相当一部分重复搬运的费用。如果你现在也被越来越贵的对话账单困扰不妨从一个小项目开始接一个代理、调一天参数用数据说话你会清楚看到上下文压缩带来的实际收益。