Claude Code CLI 对话压缩系统：compactConversation 生命周期管理实战

1. 长会话为什么会“越聊越卡”compactConversation 触发的上下文窗口压缩全流程如果你用 Claude Code CLI 写过稍大一点的项目大概率遇到过这种场景一开始对话很顺读文件、改代码、跑测试来回几十轮之后突然某次请求直接报prompt_too_long或者响应变得又慢又贵甚至模型开始“忘记”前面说过的需求。这不是模型变笨了而是上下文窗口被塞满了。Claude Code CLI 的对话压缩系统Compact就是专门解决这个问题的。它能在上下文逼近模型窗口上限之前把整段历史对话交给另一个 Claude 实例提炼成一份结构化摘要再用摘要替换掉原始消息从而释放大量 token 空间同时保留关键的工作上下文。核心执行函数就是compactConversation()它管理着一次压缩从触发到清理的完整生命周期。这套机制适合谁适合所有用 Claude Code CLI 做长期编码任务、Agent 编排、多轮调试的开发者。尤其是那些一次会话要跑几小时、涉及大量文件读写和工具调用的场景。理解 compactConversation 的生命周期你就能主动控制压缩时机、调整保留策略而不是被动等它报错。我试过在一个中型重构任务里连续对话 80 多轮中途触发了两次自动压缩如果没有这套机制会话早就断了。下面我把触发条件、配置骨架、手动验证和常见报错都拆开讲你可以直接跟着操作。2. 接入前的准备TaoToken 前置配置与 Claude Code CLI 环境在深入压缩配置之前先要把 Claude Code CLI 的模型接入跑通。这里我用 TaoToken 作为接入层它的 API 地址是https://taotoken.net/api官网是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。你需要先在控制台创建一个 API Key然后把它写进 Claude Code 的环境变量或配置文件。Claude Code CLI 读取配置的优先级大致是环境变量 项目级.claude/settings.json 用户级~/.claude/settings.json。压缩相关的阈值和保留策略主要写在 settings.json 里。如果你用的是 Cline MCP 或 Codex 这类工具配置思路类似但字段名不同后面我会给出对照。先确认你的 CLI 版本支持压缩配置。运行claude --version建议使用较新的版本。然后设置基础接入信息最直接的方式是环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你更习惯写配置文件可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }注意 Base URL 后面不要多加/v1Claude Code CLI 会自己拼接路径。Key 的权限建议只开模型调用不要给管理权限。配置完成后用claude -p hello做一次最小验证能正常返回就说明接入层通了。这一步看起来简单但很多压缩相关的报错其实根源在接入没配好。比如 401 错误、local proxy failed往往不是压缩逻辑的问题而是 Key 或 Base URL 写错了。所以先把这一层跑通再往下调压缩参数。3. 可复制配置settings.json 中压缩阈值与保留策略骨架Claude Code CLI 的压缩行为由几个关键参数控制。你可以在~/.claude/settings.json或项目级.claude/settings.json里写入下面这份骨架。这份配置的核心是控制“什么时候触发压缩”和“压缩后保留多少内容”。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 }, compact: { autoCompact: true, thresholdPercent: 0.85, reservedBufferTokens: 13000, maxRetries: 3, keepRecentMessages: 5, restoreRecentFiles: true, maxFilesToRestore: 5, maxTokensPerFile: 5000, postCompactTokenBudget: 50000, microCompact: { enabled: true, gapThresholdMinutes: 60, keepRecent: 5 }, sessionMemoryCompact: { enabled: true, minTokens: 10000, minTextBlockMessages: 5, maxTokens: 40000 } } }逐项说明一下。thresholdPercent: 0.85表示当上下文占用达到模型窗口的 85% 时触发自动压缩。reservedBufferTokens: 13000是给压缩本身的 API 调用预留的空间因为压缩也要消耗 token。maxRetries: 3对应MAX_PTL_RETRIES当压缩请求本身遇到prompt_too_long时会从最老的消息组开始丢弃并重试最多 3 次。keepRecentMessages: 5控制压缩后保留的最近消息数量这些消息不进入摘要原样保留。restoreRecentFiles和后面几个参数控制压缩后文件附件的恢复策略最多恢复 5 个最近访问的文件每个文件最多 5000 token总预算 50000 token。microCompact是微压缩配置它不调用额外模型只清理冗余的工具调用结果。gapThresholdMinutes: 60对应 prompt cache 的 TTL超过 60 分钟 cache 失效后旧的工具结果就没有保留价值了。sessionMemoryCompact是更轻量的会话记忆压缩优先级高于完整压缩minTokens和maxTokens控制压缩后的 token 范围。如果你用的是 Cline MCP配置字段会放在 MCP server 的启动参数里核心三件套是 Base URL、Key、Model ID。Codex 的auth.json则长这样{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-6 }Model ID 要和你实际使用的模型一致写错了会报model not found。配置改完后重启 CLI 生效。4. 验证请求手动触发一次压缩并观察 token 占用变化配置写好后最直接的验证方式是在会话里手动触发压缩。Claude Code CLI 提供了/compact命令它会优先尝试会话记忆压缩失败后降级到完整压缩。先开一个会话随便读几个文件、跑几条命令让上下文涨起来。然后输入/compact你会看到类似✻ Conversation compacted的边界标记以及压缩前后的 token 数对比。如果想看更详细的数据可以在会话里问模型当前上下文占用或者查看 CLI 的日志输出。手动触发后重点观察三个指标preCompactTokenCount压缩前、postCompactTokenCount摘要生成消耗、truePostCompactTokenCount实际压缩后消息估算大小。理想情况下truePostCompactTokenCount应该明显小于preCompactTokenCount。如果两者接近说明摘要本身太长或附件太大压缩没有真正释放空间。还有一个关键健康指标叫willRetriggerNextTurn。如果它为 true意味着压缩后 token 数仍然超过阈值下一轮会立即再次触发压缩。这通常说明你的thresholdPercent设得太高或者keepRecentMessages保留得太多。可以适当降低阈值或减少保留消息数。你也可以用脚本模拟一次压缩请求观察 API 返回的 usage 字段curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-6, max_tokens: 1024, messages: [{role: user, content: 总结一下我们刚才的对话}] } | jq .usage返回里的input_tokens和output_tokens能帮你判断当前上下文规模。压缩后重新请求对比input_tokens是否下降。实测下来一次成功的完整压缩通常能把上下文压到原来的 20% 到 40%具体取决于摘要质量和附件大小。5. 常见报错排查401、local proxy failed、reading choices、OAuth压缩过程中最容易遇到的几类报错我逐个拆解。401 Unauthorized最常见的原因是 API Key 写错或过期。检查ANTHROPIC_API_KEY是否和 TaoToken 控制台里的一致注意不要有多余空格。如果你用的是项目级配置确认它没有被用户级配置覆盖。另外Base URL 写成https://taotoken.net/api/带尾斜杠有时也会导致鉴权失败去掉尾斜杠再试。local proxy failed这个报错通常出现在你本地有代理层或端口转发时。Claude Code CLI 会尝试连接你配置的 Base URL如果本地网络环境有拦截就会报这个。排查方法是先用curl直接请求https://taotoken.net/api/v1/messages确认网络层通不通。如果 curl 通而 CLI 不通检查 CLI 的代理环境变量是否冲突。reading choices 报错这个通常出现在响应解析阶段说明返回的 JSON 结构不符合预期。常见原因是 Model ID 写错或者请求被中间层改写。确认你的 Model ID 是 TaoToken 支持的模型名比如claude-sonnet-4-6。如果用的是 Cline MCP检查 MCP server 的配置里 Model ID 是否和 Base URL 匹配。OAuth 相关报错如果你之前用过 OAuth 方式登录环境变量里可能残留了旧的 token导致和 API Key 冲突。清理掉ANTHROPIC_AUTH_TOKEN之类的变量只保留ANTHROPIC_API_KEY。Codex 的auth.json里如果同时有 OAuth 字段和 api_key 字段也可能冲突建议只保留 api_key。还有一个压缩特有的报错prompt_too_long在压缩请求本身出现。这时候truncateHeadForPTLRetry会介入从最老的消息组开始丢弃最多重试 3 次。如果 3 次都失败说明你的单条消息太大比如一次粘贴了超大文件。解决办法是减少单次输入体积或者调低maxTokensPerFile。排查时建议打开 CLI 的详细日志观察tengu_compact事件里的字段。compactionCacheReadTokens和compactionCacheCreationTokens能告诉你 cache 命中情况如果 cache 命中率低压缩成本会偏高。6. 把压缩生命周期管起来从自动触发到记忆重载的完整闭环理解 compactConversation 的生命周期最终是为了让你能主动管理上下文而不是被动等它爆掉。完整流程可以概括为token 超过阈值 →shouldAutoCompact判断 → 优先尝试会话记忆压缩 → 失败则走compactConversation六阶段 → 生成摘要替换历史 → 重置记忆缓存 → 下轮对话重载 MEMORY.md。几个设计决策值得记住。自动压缩预留 13K buffer是给压缩本身的 API 调用留空间。电路断路器允许 3 次失败防止无法恢复的上下文每轮浪费 API。cache-sharing 优先路径复用 prompt cache接近零额外开销。9 节结构化摘要保留续接工作所需的全部信息其中第 6 节保留所有用户消息原文作为意图溯源的锚点。analysis块在注入上下文前被剥离思考过程不占空间。压缩后重置记忆缓存使后台写入的新记忆立即生效。如果你想进一步优化可以调整thresholdPercent和keepRecentMessages的平衡。阈值太低会频繁压缩增加 API 调用阈值太高则容易触发willRetriggerNextTurn。保留消息太多会挤占压缩收益太少则可能丢失最近的工作细节。我的经验是阈值设在 0.8 到 0.85 之间保留最近 5 到 8 条消息对大多数编码会话比较合适。对于长期编码和 Agent 任务建议开启 Coding Plan它能配合压缩机制更好地管理长会话成本。如果你只是想验证模型行为可以用模型对话快速测试。接入和排障过程中遇到问题接入文档里有更详细的字段说明。把压缩配置写进 settings.json跑一次手动/compact观察 token 变化你就能掌握这套生命周期管理的核心。