1. 长会话下上下文膨胀的真实痛点长会话跑 Claude Code 的人大概率都遇到过这种场景一个重构任务从上午跑到下午中间穿插了几十次 Read、Grep、Bash上下文窗口从几万 token 一路涨到十几万然后你发现响应变慢、账单变贵甚至开始出现模型忘记前面说过什么的情况。这不是模型变笨了而是上下文里塞了太多已经消费过的工具输出——旧的文件片段、旧的日志、旧的搜索结果它们对当前推理已经没有增量价值却还在每一轮请求里被重新计费。Claude Code 对这件事的处理不是简单粗暴地满了就总结而是设计了一条按成本排序的兜底链路。这条链路里最不起眼、但调用频率最高的一层叫 Microcompact。它挂在每次 API 请求之前不调用 LLM只靠本地规则识别哪些旧的 tool_result 可以安全遗忘然后通过 cache_edits 这个协议级字段告诉服务端在缓存视图里把这些槽位挖空但别动本地历史也别打断 Prompt Cache 的前缀匹配。这套机制解决的核心矛盾是清理历史会改变 messages 前缀 hash导致 Prompt Cache 失效而 Prompt Cache 命中时 input token 只按原价 10% 计费。在半小时以上的长程任务里缓存命中能省下 80% 以上的 input 成本。所以 Claude Code 不能像普通客户端那样直接裁剪数组它必须让 Harness 和 API 配合在清理和保缓存之间找到一条协议级的通路。这篇文章从 Harness 视角拆三层 compact 机制重点放在 Microcompact 的触发时机、Prompt Cache 的命中条件、cache_edits 的增量改写策略并给出可复制的 settings 配置片段和 cache 命中率验证步骤。适合已经在用 Claude Code 做长程编码任务、想搞清楚 token 账单为什么忽高忽低的开发者。读完之后你能在本地复现压缩链路观察 token 变化并判断自己的工具输出设计是否适合长程 Agent 场景。2. TaoToken 前置接入 Claude Code 的 Harness 环境要复现 Microcompact 和 cache_edits 的行为第一步是让 Claude Code 能正常发请求并返回 usage 字段。这里我用 TaoToken 作为接入层它的 API 地址是 https://taotoken.net/api兼容 Anthropic 的 messages 协议返回体里带 cache_read_input_tokens 和 cache_creation_input_tokens这两个字段是后面验证缓存命中的关键。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新 Key复制出来。注意 Key 只在创建时完整显示一次后面再进列表只能看到前缀。拿到之后不要直接写进代码先放到环境变量里避免提交到 git。export TAOTOKEN_API_KEYsk-你的key echo $TAOTOKEN_API_KEY | head -c 8然后确认 Claude Code 的版本。Microcompact 和 cache_edits 是较新版本才有的行为老版本可能只有 fullcompact。用下面命令看版本号claude --version如果版本低于 1.0.30建议先升级。升级方式取决于你的安装渠道npm 全局安装的话npm install -g anthropic-ai/claude-code接下来是模型 ID。TaoToken 侧支持 Claude 系列模型长程任务建议用 claude-sonnet-4-5 或 claude-opus-4-1前者性价比更高后者在复杂重构任务上推理更稳。模型 ID 要写全不要用简写否则请求会返回 model not found。Base URL、API Key、Model ID 这三件套是后面所有配置的基础。Base URL 用 https://taotoken.net/api 注意不要带末尾斜杠也不要带 /v1Claude Code 会自己拼路径。如果你之前配过其他中转地址先把旧的清掉避免环境变量冲突。验证三件套是否生效最直接的方式是发一个最小请求curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: reply with ok}] } | head -c 400返回体里如果能看到 usage 字段说明接入层通了。记下这次返回的 input_tokens 数值后面做缓存对比时作为基线。如果返回 401检查 Key 是否复制完整如果返回 model not found检查模型 ID 拼写如果连接超时检查网络和 Base URL 是否写错。这一步看起来简单但它是后面所有验证的前提。Harness 层的压缩行为只有在请求真正打到服务端、并且返回 usage 明细时才能观察。所以先把接入跑通再往下拆 Microcompact。3. 可复制配置settings.json 与 cache_edits 参数Claude Code 的配置分两层一层是全局 settings控制模型、Base URL、Key另一层是项目级 settings控制 compact 相关行为。两层合并时项目级优先。下面这份配置可以直接复制路径是~/.claude/settings.jsonWindows 下是%USERPROFILE%\.claude\settings.json。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5 }, compact: { microcompact: { enabled: true, trigger_threshold: 8, keep_recent: 3, whitelist_tools: [ Bash, Read, Grep, Glob, WebFetch, WebSearch, FileEdit, FileWrite ], cold_start_idle_minutes: 60, clear_thinking_before_last_turn: true }, autocompact: { enabled: true, token_threshold: 120000, tool_call_threshold: 40 }, fullcompact: { enabled: true, circuit_breaker_failures: 3 } } }这份配置里几个参数值得单独说。trigger_threshold: 8表示当候选池里累积到 8 个可遗忘的 tool_result 时Microcompact 开始生成 cache_edits。这个值调小会让清理更激进缓存命中率可能下降调大则清理更保守上下文膨胀更快。keep_recent: 3是安全阀最近 3 条 tool_result 永远不碰因为模型下一轮很可能还要用。cold_start_idle_minutes: 60对应 Prompt Cache 的 5 分钟 TTLidle 超过 60 分钟后 cache 已经过期此时直接改写本地 messages 更划算。whitelist_tools是 Microcompact 的候选白名单。只有这八类工具的结果有资格进入遗忘候选池。自定义 MCP 工具默认不在里面因为 Harness 不知道它们有没有副作用、结果是否幂等。如果你自己写了 MCP 工具想让它参与 Microcompact需要显式加进白名单并且确保输出可重放或已落盘。项目级配置放在项目根目录的.claude/settings.json可以覆盖全局的 compact 参数。比如某个项目工具调用特别密集可以把trigger_threshold调到 5让清理更早介入{ compact: { microcompact: { trigger_threshold: 5, keep_recent: 2 } } }配置改完之后不用重启 Claude Code下一次请求就会读取新值。但要注意env里的 Base URL 和 Key 是启动时读取的改了要重启。compact 参数是每轮请求前读取的改了立即生效。如果你用的是 Codex 或 Cline 这类也支持 Anthropic 协议的客户端配置思路类似但字段名可能不同。Codex 的 auth.json 里放的是OPENAI_API_KEY和base_urlCline 的 MCP 配置里放的是apiProvider和apiKey。核心三件套不变Base URL 指向 https://taotoken.net/api Key 用刚才创建的Model ID 写全。4. 验证请求观察 cache_read 与 token 变化配置好之后下一步是验证 Microcompact 是否真的在跑以及 cache_edits 是否保住了缓存命中。最直接的方式是开 verbose 日志让 Claude Code 把每轮请求的 usage 打出来。claude --verbose 21 | tee claude-verbose.log然后在会话里跑一个会产生大量工具输出的任务比如让 Claude Code 读一个目录下的所有文件并做统计。跑几轮之后在日志里搜cache_read_input_tokens和cache_creation_input_tokens。正常情况下你会看到这样的模式第一轮 cache_creation 很高、cache_read 为 0第二轮开始 cache_read 涨上来、cache_creation 降下去当 Microcompact 触发后cache_read 会有一次小幅下降但不会归零。这个小幅下降但不归零就是 cache_edits 生效的特征。如果 cache_read 直接归零说明前缀 hash 被打断了Microcompact 没走 cache_edits 路径而是直接改了本地 messages。这时候要检查microcompact.enabled是否为 true以及当前 Claude Code 版本是否支持 cache_edits。更精确的验证方式是直接看请求体。Claude Code 在 verbose 模式下会把发往服务端的请求结构打出来搜cache_edits字段grep -A 20 cache_edits claude-verbose.log | head -60如果能看到类似下面的结构说明 Microcompact 正在生成 cache_edits{ cache_edits: [ { type: clear_tool_result, tool_use_id: toolu_01ABC..., reason: microcompact_age_threshold } ] }每个 cache_edits 条目对应一个被挖空的 tool_result 槽位。本地 messages 里这些内容还在但服务端构造模型输入时会忽略它们。你可以对比本地 messages 的 token 数和服务端返回的 input_tokens两者会有差值差值就是 cache_edits 挖掉的部分。再进一步可以写个小脚本统计每轮的缓存命中率python3 - EOF import re log open(claude-verbose.log).read() reads [int(x) for x in re.findall(rcache_read_input_tokens[\s:](\d), log)] creates [int(x) for x in re.findall(rcache_creation_input_tokens[\s:](\d), log)] for i, (r, c) in enumerate(zip(reads, creates)): total r c rate r / total * 100 if total else 0 print(fturn {i1}: cache_read{r} cache_create{c} hit_rate{rate:.1f}%) EOF跑长程任务时健康的曲线是 hit_rate 稳定在 70% 以上偶尔因为 Microcompact 触发掉几个百分点然后迅速回升。如果 hit_rate 持续低于 50%说明前缀频繁变化可能是 keep_recent 设得太小或者有工具输出在每轮都变比如带时间戳的日志。冷启动路径的验证方式不同。让会话 idle 超过 60 分钟然后发一条新消息观察本地 messages 是否被改写。verbose 日志里会看到cold_start_compact标记以及被替换成[Old tool result content cleared]的占位符。这时候 cache_read 会归零因为服务端 cache 已经过期下一次请求会重建缓存。5. 常见报错排查401、local proxy failed 与 OAuth接入和验证过程中最容易撞到几类报错这里逐个拆。401 Unauthorized。返回体通常是{type:error,error:{type:authentication_error,message:invalid x-api-key}}。原因有三个Key 复制不完整、Key 已删除、环境变量没生效。先确认echo $ANTHROPIC_API_KEY能打出完整 Key再确认 settings.json 里的 Key 和 api-keys 页面一致。如果用的是项目级配置检查项目根目录的.claude/settings.json是否覆盖了全局配置里的 Key。local proxy failed / connection refused。这个报错说明 Claude Code 尝试连本地代理但连不上。常见原因是之前配过HTTP_PROXY或HTTPS_PROXY环境变量指向了一个已经关掉的本地端口。清掉这些变量unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy然后确认ANTHROPIC_BASE_URL是 https://taotoken.net/api 没有多余路径。如果还是失败用 curl 直接测 Base URL 连通性排除网络层问题。reading choices of undefined。这个报错通常出现在用 OpenAI 兼容协议调 Anthropic 模型时返回体结构不匹配。Claude Code 走的是 Anthropic messages 协议返回体里是content数组不是choices。如果你在 Cline 或 Codex 里看到这个错检查 apiProvider 是否设成了 anthropic而不是 openai。Codex 的 auth.json 里要写apiProvider: anthropicCline 的 MCP 配置里要写apiProvider: anthropic。OAuth token expired / invalid_grant。这个报错说明客户端在尝试用 OAuth 流程拿 token但你的配置是 API Key 模式。检查 settings.json 里是否混入了oauth相关字段或者环境变量里是否有ANTHROPIC_OAUTH_TOKEN。清掉这些只保留ANTHROPIC_API_KEY。如果用的是 Claude Code 官方登录态先 logout 再用 API Key 模式登录。cache_edits not supported。如果 verbose 日志里看到这个警告说明当前模型或接入层不支持 cache_edits 字段。先确认模型 ID 是 claude-sonnet-4-5 或更新版本老模型可能不支持。再确认 Claude Code 版本低于 1.0.30 的版本没有这个能力。升级后重启会话。cache_read 持续为 0。如果每轮 cache_read 都是 0说明 Prompt Cache 完全没命中。检查三点一是 messages 里是否有每轮都变的内容比如动态时间戳、随机 ID二是 system prompt 是否稳定三是 cache_edits 是否过于激进把前缀打碎了。先把microcompact.enabled设为 false看 cache_read 是否恢复以此判断问题是否出在 Microcompact。排查时有个通用技巧把 verbose 日志按轮次切分对比相邻两轮的请求体差异。如果差异只在 cache_edits 字段说明前缀稳定如果差异出现在 messages 数组里说明本地历史被改了缓存必然失效。6. 语义一致 CTA把压缩链路跑在自己的任务里Microcompact 这套机制的价值不在于某一次请求省了多少 token而在于它让长程任务的上下文成本变得可预测。你可以在本地复现整条链路配好 settings.json开 verbose 日志跑一个多小时的重构任务观察 cache_read 的曲线。当你能看到 cache_edits 在每轮请求前悄悄挖掉旧工具结果、而 cache_read 依然稳定在 70% 以上时就说明 Harness 层的压缩逻辑真正跑通了。如果你想把这条链路接到自己的项目里先从 API Key 开始https://taotoken.net/api-keys 。拿到 Key 之后按第 3 节的 settings.json 配好三件套Base URL 用 https://taotoken.net/api Model ID 写 claude-sonnet-4-5。接入文档在 https://taotoken.net/doc 里面有完整的字段说明和错误码对照。验证模型行为是否正常可以用模型对话页面发几个长上下文请求观察 usage 字段的变化https://taotoken.net/chat 。如果你打算把 Claude Code 长期用在编码任务上Coding Plan 更适合持续跑https://taotoken.net/coding-plan 。配置过程中遇到 cache_edits 不生效或 cache_read 异常先回第 5 节对照报错大部分问题出在环境变量冲突或版本不匹配。最后留一个实用技巧如果你自己写 MCP 工具尽量让输出可重放或落盘这样才有资格进 Microcompact 白名单。工具输出越小、越幂等长程任务的上下文卫生就越好做。