1. 从一次上下文爆掉说起Claude Code 的压缩与回退到底在做什么如果你用 Claude Code 写过稍大一点的项目大概率遇到过这种场景前面聊得好好的突然某次工具调用返回后模型开始失忆或者直接甩出一句 prompt too long。这不是模型变笨了而是上下文窗口被塞满了。Claude Code 作为本地 AI 编码工具处理这个问题的核心机制就是上下文模型的压缩compact与回退fallback。简单说压缩就是把几千条消息、几十万 token 的对话历史摘要成几百 token 的连贯总结同时尽量保留工具调用结果、代码变更、决策逻辑这些关键信息。回退则是在压缩请求本身都超长时渐进式截断最旧的轮次组保证压缩动作能完成而不是直接崩掉。这套机制适合谁适合所有在本地跑 Claude Code、用统一 Key/API 通道接入模型、并且希望长会话不中断的开发者。我试过在几个中型仓库里连续跑几小时编码任务压缩触发得相当频繁。理解它的配置骨架之后你能主动控制压缩时机、保留哪些文件状态、以及压缩后如何重建工具和计划上下文。这篇就围绕 Claude Code 源码里 compactConversation 这条链路交付可复制的 settings.json 与 config.toml 骨架并给出验证压缩触发与回退生效的具体动作。所有配置都跑在 TaoToken 统一 Key/API 通道下方便你核对。2. TaoToken 前置统一 Key 与 API 通道准备在动配置之前先把通道打通。Claude Code 需要一个能访问模型的 API 端点TaoToken 提供统一的 Key 和 API 通道省去你到处拼不同厂商地址的麻烦。你需要准备两样东西一个可用的 API Key以及确认 API 基地址。获取 Key 的入口在控制台的 API Keys 页面登录后新建一个 Key复制保存。注意 Key 只在创建时完整显示一次丢了就重新建。API 基地址统一用https://taotoken.net/api这个地址不带任何查询参数直接作为 base_url 使用。如果你还没决定用哪种接入方式可以先在模型对话页面验证 Key 是否可用确认能正常返回再进本地配置。对于长期编码和 Agent 场景Coding Plan 更适合因为它的额度模型和长会话压缩的调用频率更匹配。接入文档里有各客户端的完整参数说明配置前扫一眼能少踩很多坑。这里要强调一点TaoToken 是合规的统一 API 通道不是任何形式的灰色中转。你拿到的 Key 就是正常调用凭证配置时把它当作标准 OpenAI 兼容或 Anthropic 兼容端点来用即可。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层一层是应用级 settings.json控制压缩行为、文件恢复数量、自动压缩阈值另一层是模型接入的 config.toml控制 API 通道和模型参数。下面两份骨架可以直接抄改掉 Key 就能用。3.1 settings.json压缩与回退行为骨架{ autoCompact: { enabled: true, thresholdRatio: 0.85, maxPromptTooLongRetries: 3, suppressFollowUpQuestions: true }, compact: { postCompactMaxFilesToRestore: 5, restorePlanMode: true, restoreSkillAttachments: true, restoreDeferredTools: true, restoreMcpInstructions: true }, context: { maxContextTokens: 180000, reserveOutputTokens: 8000, truncateHeadOnRetry: true }, cache: { keepPrefixHashStable: true, enableCacheEdits: true } }逐项说明。autoCompact.enabled打开自动压缩对应源码里的 autoCompactIfNeeded。thresholdRatio是触发阈值0.85 表示上下文用到 85% 时启动压缩这个值别设太高否则压缩请求自己就容易超长。maxPromptTooLongRetries对应 MAX_PTL_RETRIES源码里默认 3 次超过就抛错保持 3 是稳妥值。suppressFollowUpQuestions在自动压缩时抑制用户确认避免打断编码流。compact段对应后压缩重建阶段。postCompactMaxFilesToRestore控制压缩后恢复多少个最近文件源码里是 POST_COMPACT_MAX_FILES_TO_RESTORE默认值不大设 5 比较平衡。后面几个 restore 开关分别对应计划模式、技能附件、延迟工具、MCP 指令的重建全开能保证压缩后状态完整。context段的truncateHeadOnRetry就是回退机制的核心开关打开后压缩请求遇到 prompt too long 会渐进式截断最旧的 API 轮次组。cache.keepPrefixHashStable对应 cacheSafeParams保持前缀哈希不变保护服务器端推理缓存。3.2 config.toml模型接入骨架[provider] name taotoken base_url https://taotoken.net/api api_key sk-你的Key api_style anthropic [model] name claude-sonnet-4-5 max_tokens 8192 temperature 0.2 [compact] prompt_template base custom_instructions 聚焦 TypeScript 代码变更记录踩过的坑和修复方式 [retry] max_attempts 3 backoff_ms 800api_style按你实际接入的模型类型选Anthropic 系模型用anthropicOpenAI 兼容的用openai。compact.prompt_template对应源码 prompt.ts 里的三个模板base是完整对话压缩partial是部分压缩partial_up_to是前缀压缩。日常用base就够。custom_instructions会拼进压缩提示词源码里那段example ## Compact Instructions就是干这个的你可以让它重点保留代码片段和错误修复记录。retry段和 settings.json 里的重试是两层config.toml 管网络层重试settings.json 管压缩逻辑层的 prompt too long 重试别混淆。4. 验证请求确认压缩触发与回退生效配置写完得验证它真的在工作。分三步先确认通道通再确认压缩被触发最后确认回退在超长时生效。4.1 验证 API 通道先用一个最小请求确认 Key 和地址没问题curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的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: 回复 OK 两个字母}] }返回里能看到content字段带OK就说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否多了斜杠或路径。4.2 验证压缩触发压缩触发的判断依据是上下文 token 数接近阈值。你可以在 Claude Code 里跑一个长会话故意让它读多个大文件观察日志里是否出现 compact 相关事件。更直接的办法是手动触发一次压缩对应源码里的/compact命令claude --print /compact执行后观察输出如果看到类似CompactionResult的摘要结构包含 Primary Request、Files and Code Sections、Errors and fixes 这些小节说明压缩引擎正常工作。摘要里应该保留你最近改过的文件名和关键代码片段这是验证关键信息保留是否到位的最直接方式。4.3 验证回退生效回退的验证稍微麻烦需要构造一个压缩请求自身超长的场景。你可以把thresholdRatio临时调到 0.98然后灌入超长上下文让压缩请求也超长。此时观察日志应该出现truncateHeadForPTLRetry相关的截断记录并且最终压缩仍然完成而不是直接抛ERROR_MESSAGE_PROMPT_TOO_LONG。如果重试 3 次后仍失败说明截断策略没生效检查truncateHeadOnRetry是否为 true以及maxPromptTooLongRetries是否被设成了 0。5. 本篇常见错排查配置过程中最容易踩的坑集中在几处逐个说。压缩后模型失忆多半是postCompactMaxFilesToRestore设得太小或者restorePlanMode、restoreSkillAttachments被关了。压缩后重建阶段会恢复文件附件、计划、技能、工具差异、代理列表、MCP 指令这六个维度任何一个关掉都可能导致状态缺失。建议全开只调文件恢复数量。压缩请求反复 prompt too long检查thresholdRatio是不是设太高。如果上下文用到 95% 才触发压缩压缩请求本身几乎必然超长。降到 0.8 到 0.85 之间给压缩请求留出余量。同时确认truncateHeadOnRetry为 true否则回退机制不工作。缓存命中率骤降压缩会重置缓存基线这是正常的源码里明确说 compactConversation 是大扫除会重置缓存。但如果你发现每次工具调用后缓存都失效那是cache_edits微压缩没开检查enableCacheEdits。微压缩负责日常维护完整压缩负责大扫除两者协同缺一不可。API 返回 400 且提示 model 不存在config.toml 里的model.name写错了。不同通道支持的模型名不一样去接入文档核对当前可用的模型标识别照抄旧文档里的名字。Key 泄露风险config.toml 里明文写 Key 是方便但别把这份文件提交到 Git。用环境变量替换或者把 config.toml 加进 .gitignore。TaoToken 控制台可以随时吊销旧 Key 重建发现泄露立刻处理。6. 把配置跑通之后压缩策略的长期维护配置跑通只是起点。长期用下来压缩策略需要根据你的项目特点微调。如果你的项目以读代码为主、改动少可以把postCompactMaxFilesToRestore调大让压缩后保留更多文件上下文。如果以频繁小改动为主重点开好enableCacheEdits让微压缩多干活减少完整压缩的触发频率。自定义压缩指令值得花时间打磨。源码里那段 BASE_COMPACT_PROMPT 要求摘要包含九个部分从 Primary Request 到 Optional Next Step。你可以在custom_instructions里追加自己的关注点比如所有数据库 schema 变更必须逐字段列出或者记录每次测试失败的具体断言。这些指令会拼进压缩提示词直接影响摘要质量。最后定期用/compact手动触发一次检查摘要是否还准确。自动压缩跑久了偶尔会出现摘要漂移手动触发能帮你及时发现。压缩与回退这套骨架配好了就是长会话的保险丝配不好就是失忆的源头。把上面两份配置抄下去改掉 Key跑一遍验证你就能在自己的本地编码工具里把这套机制用起来。