如果你用 Claude Code 开着一个很长的会话，离开快一小时再回来，可能会看到一行提示：Compacted while idle, before the prompt cache expired。这就是 Claude Code 新加的 Idle Compaction（空闲自动压缩）：会话空闲约 54 分钟、上下文达到 20 万 Token 时，它会在 1 小时 prompt cache 过期前，先把对话压缩成摘要。你回来发下一条消息时，只需要重新处理摘要，不用把整段历史重算一遍。
这个功能对订阅用户最有用。用 API Key 或第三方 API（包括 AICodeWith）的用户，默认缓存只有 5 分钟，基本触发不到它，除非把缓存时长改成 1 小时。下面讲清楚它怎么工作、怎么关、怎么改阈值，以及第三方 API 用户该怎么设置。
一句话看懂
| 问题 | 答案 |
|---|---|
| 是什么 | 空闲的长会话在缓存过期前自动压缩成摘要 |
| 什么时候触发 | 交互式终端会话、处于 1 小时缓存、上下文 ≥ 200,000 Token、空闲约 54 分钟且电脑未休眠 |
| 回来时看到什么 | Compacted while idle, before the prompt cache expired |
| 怎么关 | settings.json 里设 "idleCompaction": false，或设环境变量 DISABLE_AUTO_COMPACT=1 |
| 怎么改阈值 | 环境变量 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS，默认 200000，最低 100000 |
| 版本 | 更新日志在 2.1.299 加入该功能；相关配置项需要 v2.1.290 或更高 |
你会注意到什么
Anthropic 的 Lydia Hallie 在 X 上介绍：Claude Code 现在会在 prompt cache 过期（约 1 小时）前压缩长时间空闲的会话，之后回来只需重新处理摘要，而不是整段对话，从而节省用量（原帖）。
SemiAnalysis 也发帖指出，该功能随 Claude Code 2.1.299 发布：上下文至少 200k 的会话空闲约 54 分钟后会自动压缩（原帖）。
所以表现很简单：离开前会话很长，回来后对话历史变成了一段摘要，界面上多了上面那行提示。
它是怎么工作的
Claude Code 每轮都会把完整上下文重新发给模型。prompt cache 让没变的前缀按较低的缓存价计费，不用每次都全价处理。但缓存有存活时间（TTL），超时没请求就过期，下一轮只能把整段历史当作未缓存输入重新处理，这就是“离开一小时回来第一条消息很贵、很慢”的原因（官方 prompt caching 文档）。
Idle Compaction 抓住的是过期前的这个时间窗口：
- 你最后一次请求后，会话空闲约 54 分钟；
- 这时 1 小时缓存还没过期，Claude Code 发起压缩，生成摘要的请求可以读缓存，比冷启动便宜；
- 你回来发下一条消息时，发送的是摘要，而不是全部历史。
官方文档列出的触发条件需要同时满足：交互式终端会话；会话处于 1 小时缓存 TTL；Claude Code 能从 Anthropic 获取功能开关（feature flags）；上下文达到阈值（默认 200,000）；空闲约 54 分钟，且这时电脑处于唤醒状态（settings 文档：idleCompaction）。
谁真正受益：订阅 vs API
关键在缓存时长。官方文档给出的默认值：
| 请求类型 | Claude 订阅（套餐额度内） | 用量额度、API Key 或云厂商 |
|---|---|---|
| 主对话 | 1 小时 | 5 分钟 |
| 其他请求（子 Agent、压缩等） | 5 分钟（少数服务端控制的辅助请求为 1 小时） | 5 分钟 |
来源：Which TTL each request gets
- 订阅用户：主对话默认就是 1 小时缓存，Idle Compaction 直接生效。
- API Key 和第三方 API 用户：主对话默认只有 5 分钟缓存。5 分钟后缓存已经过期，等不到第 54 分钟，所以默认基本没有收益。
要让它对 API 用户生效，需要把主对话缓存改成 1 小时：在 settings.json 里设 "promptCacheTtl": "1h"，或者设环境变量 CLAUDE_CODE_PROMPT_CACHE_TTL=1h（需要 v2.1.242 或更高）。注意 1 小时缓存的写入单价比 5 分钟更高，如果你的工作很少空闲超过 5 分钟，延长缓存反而可能多花钱。
通过 ANTHROPIC_BASE_URL 走网关时，官方文档说明 1 小时缓存的部分请求信息放在 anthropic-beta 请求头里，需要网关原样转发这个头。
账算一下：重算 20 万上下文 vs 重算一段摘要
以下按公开标价估算，只看数量级。单价取 AICodeWith 模型页 2026 年 10 月 15 日 14:13 显示的 Claude Sonnet 5.5 输入价 ¥2.736 / 百万 Tokens（人民币），按普通输入单价计算，不含输出和缓存写入差价：
| 情况 | 需要重新处理的输入 | 估算费用（人民币） |
|---|---|---|
| 缓存过期后重算完整上下文 | 200,000 Tokens | 约 ¥0.55 |
| 压缩后只处理摘要 | 约 5,000 Tokens | 约 ¥0.014 |
两者差了大约 40 倍。单次看金额不大，但一天里多次离开、回来，长会话越多，差距越明显。
先检查版本
claude --version
官方更新日志在 2.1.299 加入了空闲压缩，同时写明 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 和 "idleCompaction": false 都需要 v2.1.290 或更高（Claude Code CHANGELOG）。版本太旧就运行：
claude update
官方文档还提到：更新后的第一个会话里，依赖功能开关的功能可能暂时不出现，下一个会话才会生效。
怎么关闭，怎么改阈值
关闭：settings.json
在 ~/.claude/settings.json（或项目的 settings 文件）里加：
{
"idleCompaction": false
}
关闭：环境变量
export DISABLE_AUTO_COMPACT=1
DISABLE_AUTO_COMPACT 会同时关掉接近上下文上限时的自动压缩和空闲压缩，手动 /compact 仍然可用。只想关空闲压缩、保留自动压缩，就用上面的 idleCompaction。
修改阈值
用 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 设定触发压缩的上下文大小。默认 200000，填正整数，低于 100000 的值会被抬到 100000。写在 settings.json 的 env 里：
{
"env": {
"CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
}
}
什么时候该关掉它
压缩就是用摘要替代原始对话，细节会丢。下面这些情况建议关掉，或者离开前自己处理：
- 复杂调试进行到一半：报错原文、试过的方案、排除过的假设，摘要里可能只剩一句话；
- 需要精确引用之前的输出：日志片段、长命令结果、接口返回；
- 长链路重构：中间约定很多，摘要容易漏掉边界条件。
更可控的做法是在离开前手动运行 /compact，在任务的自然断点上压缩，而不是让它在 54 分钟时自动发生。官方文档也建议在任务之间的自然断点手动 /compact。重要的项目规则写进 CLAUDE.md，压缩后会从磁盘重新加载，见《Claude Code 的 CLAUDE.md 怎么写》。
用 AICodeWith 时怎么设置
通过 AICodeWith 使用 Claude Code，属于自定义 ANTHROPIC_BASE_URL 的情况，主对话默认是 5 分钟缓存。想用上空闲压缩，在 ~/.claude/settings.json 里同时配好 Base URL、Key 和 1 小时缓存：
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
"ANTHROPIC_AUTH_TOKEN": "替换成你的 AICodeWith API Key",
"ANTHROPIC_API_KEY": ""
},
"promptCacheTtl": "1h"
}
Base URL 不要加 /v1。完整的接入步骤和报错处理，见《Claude Code 如何接入第三方 API》。选哪个模型做主力，见《Claude Code 用哪个模型》。
常见错误和自查
| 现象 | 可能原因 | 怎么查 |
|---|---|---|
| 从没见过那行提示 | 版本太旧，或主对话不是 1 小时缓存 | claude --version；API 用户检查 promptCacheTtl |
| 设了 1h 还是不触发 | 上下文没到阈值，或电脑在第 54 分钟时休眠了 | 用 /usage 查看 Prompt cache 行，确认缓存是否仍热；保持电脑唤醒 |
| 想确认缓存时长是否生效 | — | 运行 claude -p "hello" --output-format json，看 usage.cache_creation 里是 ephemeral_1h_input_tokens 还是 ephemeral_5m_input_tokens |
| 设了 idleCompaction: false 不生效 | 版本低于 2.1.290 | 升级；旧版本可关 autoCompactEnabled |
| 设了 DISABLE_TELEMETRY 等变量后不触发 | 这些变量会关掉功能开关获取，空闲压缩依赖它 | 查看官方 env-vars 文档里“需要功能开关”的说明 |
常见问题
Idle Compaction 会额外花钱吗？
压缩本身要发一次生成摘要的请求，但它在缓存过期前发起，能读缓存。官方说明，缓存还热时一次 /compact 的成本只是上下文大小所示的一小部分。
API Key 用户能用吗？
能，但要把主对话缓存设成 1 小时："promptCacheTtl": "1h" 或 CLAUDE_CODE_PROMPT_CACHE_TTL=1h。默认 5 分钟缓存下基本触发不到。
关掉它会影响手动 /compact 吗？
不会。idleCompaction: false 和 DISABLE_AUTO_COMPACT=1 都不影响手动 /compact。
阈值能设成 5 万吗？
不能。低于 100000 的值会被抬到 100000。
用 -p 非交互模式会触发吗？
不会。官方列出的触发条件之一是交互式终端会话。
来源
- Lydia Hallie（Anthropic）X 帖：x.com/lydiahallie/status/2110484840256819380
- SemiAnalysis X 帖：x.com/SemiAnalysis_/status/2110444144233480309
- Claude Code 更新日志：github.com/anthropics/claude-code/blob/main/CHANGELOG.md
- Claude Code prompt caching 文档：code.claude.com/docs/en/prompt-caching
- Claude Code settings 文档（idleCompaction）：code.claude.com/docs/en/settings-reference
- Claude Code 环境变量文档：code.claude.com/docs/en/env-vars
