1. 长会话跑着跑着就卡住问题多半出在 Context Window如果你用 Claude Code 跑过半小时以上的任务大概率遇到过这种情况前面几轮还挺快工具调用一多响应开始变慢token 账单也悄悄涨上去。打开日志一看input_tokens每轮都在往上爬cache_read_input_tokens却时高时低。这不是模型变笨了而是 Context Window 被旧数据塞满了。Claude Code 在长会话里会不断产生tool_resultRead 返回的文件内容、Grep 的匹配列表、Bash 的构建日志、WebFetch 的网页正文。这些东西在产生的那一轮有用但几轮之后基本就是占地方。如果每轮都把它们原样发给模型Context Window 会迅速膨胀Prompt Cache 的前缀也会被不断打断。Claude Code 的应对方式不是等上下文爆掉再压缩而是在每次 API 请求发出之前做一轮轻量清理。这套机制分三层Microcompact、autocompact、fullcompact按成本从低到高兜底。其中 Microcompact 跑得最频繁也最容易被忽略。它靠cache_edits这个协议级字段在不改动本地 messages 的前提下把服务端缓存视图里的旧tool_result挖空从而既清理了上下文又保住了 Prompt Cache 的命中折扣。这篇就按工程视角拆开讲Microcompact 的触发条件是什么、Prompt Cache 命中策略怎么配合、cache_edits的编辑粒度怎么控制最后给出一份settings.json可复制配置骨架并演示怎么通过日志观察 cache 命中率和 token 节省。适合已经在用 Claude Code 跑长任务、想搞清楚上下文成本从哪来的开发者。2. 前置准备TaoToken 接入与 Claude Code 环境在拆配置之前先把接入层理清楚。Claude Code 本身是一个 CLI 工具它需要指向一个兼容 Anthropic API 的端点。我这边用的是 TaoToken 的接入方式官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。你需要先拿到一个 API Key。登录后进控制台在 API Keys 页面创建一个新 key复制出来备用。这个 key 后面会写进环境变量不要直接硬编码到配置文件里提交到仓库。# 设置环境变量建议写进 ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key设置完之后用claude --version确认 CLI 能正常启动。如果报连接错误先检查ANTHROPIC_BASE_URL有没有多余斜杠以及 key 有没有复制完整。关于模型选择Claude Code 默认会走 Sonnet 系列。如果你要跑长会话建议在配置里显式指定模型避免中途被切换到不支持的版本。TaoToken 的模型对话页面可以先用几轮短对话验证 key 是否可用确认没问题再进 Claude Code 跑长任务。3. 可复制配置settings.json 里的上下文压缩骨架Claude Code 的配置分两层全局配置在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.json。上下文压缩相关的字段主要放在全局配置里项目级可以覆盖部分行为。下面是一份可复制的配置骨架字段名按 Claude Code 的实际结构组织你可以直接粘进~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, CLAUDE_CODE_ENABLE_PROMPT_CACHE: 1, CLAUDE_CODE_MICROCOMPACT: 1, CLAUDE_CODE_MICROCOMPACT_KEEP_RECENT: 4, CLAUDE_CODE_MICROCOMPACT_MIN_AGE_TURNS: 3, CLAUDE_CODE_CACHE_EDITS: 1, CLAUDE_CODE_IDLE_COMPACT_MINUTES: 60 }, model: claude-sonnet-4-5, permissions: { allow: [ Read, Grep, Glob, Bash(git status), Bash(npm test) ] } }几个关键字段解释一下。CLAUDE_CODE_MICROCOMPACT控制是否启用 Microcompact 热路径默认开启显式写 1 是为了避免版本升级后被重置。CLAUDE_CODE_MICROCOMPACT_KEEP_RECENT是最近窗口保留条数设成 4 意味着最近 4 条tool_result不参与清理这是安全阀别设太小。CLAUDE_CODE_MICROCOMPACT_MIN_AGE_TURNS是年龄阈值工具结果至少经过 3 轮对话才进入候选池。CLAUDE_CODE_CACHE_EDITS控制是否用cache_edits协议字段做服务端缓存编辑。这个开关打开后热路径清理不会改写本地 messages前缀 hash 保持不变Prompt Cache 继续命中。CLAUDE_CODE_IDLE_COMPACT_MINUTES是冷启动阈值默认 60 分钟超过这个 idle 时间后 cache 已经过期Claude Code 会直接改写本地 messages 做瘦身。注意CLAUDE_CODE_ENABLE_PROMPT_CACHE必须为 1否则cache_edits没有意义因为服务端根本没有可编辑的 cache 条目。配置改完后重启 Claude Code 会话生效。如果你在项目里跑建议把项目级.claude/settings.json里的model和permissions单独维护全局配置只管接入和压缩策略。4. 验证请求从日志观察 cache 命中率与 token 节省配置写完不算完得能看到实际效果。Claude Code 在--verbose模式下会打印每轮请求的 token 统计包括input_tokens、cache_creation_input_tokens、cache_read_input_tokens。这三个值的变化就是判断 Microcompact 是否生效的直接证据。先跑一个会产生大量工具调用的任务比如让 Claude Code 读几个文件再改代码claude --verbose 读取 src 目录下所有 ts 文件统计每个文件的函数数量然后生成一份报告任务跑起来后观察日志里的 token 行。正常情况下你会看到这样的模式[usage] input_tokens1240 cache_creation_input_tokens8600 cache_read_input_tokens0 [usage] input_tokens380 cache_creation_input_tokens0 cache_read_input_tokens9200 [usage] input_tokens410 cache_creation_input_tokens0 cache_read_input_tokens9100 [usage] input_tokens395 cache_creation_input_tokens0 cache_read_input_tokens8800第一轮cache_creation是建立缓存后面几轮cache_read稳定在 9000 左右说明前缀被命中了。注意第三、四轮cache_read略微下降从 9200 掉到 8800这就是cache_edits生效的信号服务端确实少读了一部分旧tool_result但前缀结构没变所以没有触发cache_creation重建。如果你看到cache_read突然掉到 0 并且cache_creation重新出现说明前缀被打断了。常见原因是本地 messages 被改写或者cache_edits字段没被正确附带。这时候检查CLAUDE_CODE_CACHE_EDITS是否为 1以及请求体里有没有cache_edits块。想更精确地量化节省可以在任务结束后统计总 token# 从 verbose 日志里提取 token 行做汇总 grep \[usage\] claude-session.log | \ awk -F[ ] {inp$3; cr$5; cw$7} END {print input:, inp, cache_read:, cr, cache_write:, cw}对比开启 Microcompact 前后两次相同任务的汇总值cache_read占比越高、input_tokens越低说明压缩链路越有效。实测下来长会话里cache_read能稳定占总 input 的 80% 以上input 成本能压到原来的两成左右。5. 本篇常见错排查5.1 cache_read 一直为 0Prompt Cache 完全没命中先确认CLAUDE_CODE_ENABLE_PROMPT_CACHE是 1。然后检查请求里 messages 的顺序是否稳定如果你在每轮请求前手动往 messages 头部插了内容前缀 hash 必然变化。另外确认 API 端点没有做请求体重写某些中间层会重新序列化 JSON导致字段顺序变化这也会打断前缀匹配。5.2 cache_edits 报字段不支持cache_edits是较新的协议字段如果你的接入端点版本较旧可能不认识这个字段。表现是请求返回 400 或者字段被忽略。解决办法是确认 TaoToken 的 API 端点走的是最新版本接入文档里有版本说明。如果确实不支持先关掉CLAUDE_CODE_CACHE_EDITS退回到冷启动本地改写模式虽然会打断 cache但至少不会报错。5.3 最近窗口设太小导致语义断裂CLAUDE_CODE_MICROCOMPACT_KEEP_RECENT设成 1 或 2 的时候模型可能刚 Read 完文件下一轮就要基于文件内容改代码结果tool_result被清掉了模型只能重新读一遍。这不会报错但会浪费一轮工具调用。建议保持 4 以上具体看你的任务里工具调用的密集程度。5.4 冷启动后 thinking block 被清导致推理不连续冷启动路径会清掉最近一轮之前的历史 thinking。如果你在 extended thinking 模式下跑长任务发现模型突然忘了之前的推理结论可能是 thinking 被清得太早。这时候可以调大CLAUDE_CODE_IDLE_COMPACT_MINUTES或者在接受 cache 重建成本的前提下手动控制会话节奏避免长时间 idle。5.5 sub-agent 和 main thread 缓存状态冲突如果你在任务里 fork 了 sub-agent注意cache_edits只在 main thread 发起。sub-agent 自己跑的时候不会参与清理调度它的工具结果会原样保留到 fan-in 回主线。如果你发现 sub-agent 返回后主线 cache 命中率下降这是正常的因为 fan-in 会引入新的 messages 内容。等主线下一轮 Microcompact 跑完cache 会重新稳定。6. 把压缩链路跑通之后下一步做什么配置和验证都跑通之后你手里就有了一条可观测的上下文压缩链路Microcompact 在热路径上每轮清理旧tool_resultcache_edits保住 Prompt Cache 前缀冷启动路径在 cache 过期后做本地瘦身。这套机制的核心不是压得多狠而是把不同成本的手段放在正确的位置。如果你要长期跑编码任务或者 Agent 工作流建议把settings.json里的压缩参数固化下来然后通过 Coding Plan 页面管理多个项目的配置模板避免每个项目重复调参。接入文档里有完整的字段说明和版本兼容性列表遇到字段不生效的情况可以先对照排查。验证模型行为的时候模型对话页面可以快速起几轮短会话观察cache_read和input_tokens的比例是否符合预期。API Keys 页面则用来管理不同项目用的 key方便按项目统计 token 消耗。把这几块串起来长会话的上下文成本就能从黑盒变成可观测、可调优的工程问题。