cache-keepalive
如果你常常来不及在缓存有效期内读完 Agent 的回答并回复它,可以考虑缓存保温。例如,在缓存寿命为 5 分钟的环境里,阅读、思考或离开一会儿就可能跨过这个窗口;具体时间因模型、产品链路和配置而异,不能统一按 5 分钟判断。
**缓存保温并非一律需要。**顺序是:先查 TTL,能直接用 1 小时 TTL 就先改 TTL;改完还有跨不过去的空档,再按公式算账;算下来划算,才挑一个现成工具。
保温请求仍是一次真实模型调用。"自动"指程序决定何时触发,不是零 token,也不是绕过套餐或 API 限额。
先问四个问题
保温防的是「静默期跨过缓存寿命导致冷重建」。它不是普遍有收益的,按顺序问:
- **默认缓存寿命是否已覆盖你的静默窗口?**覆盖了就不需要保温;没覆盖,先看能不能直接把寿命改长(第一、二节)。
- 算下来划不划算?按续温公式算(第三节)。usage 只能证明命中,不能证明省钱。
- **有没有可归因的合成请求入口?**没有则方法不适用。Claude Code 现在有现成的入口和工具(第四节)。
- **能不能读到 usage 验证命中?**读不到就别上自动链:无法验证就无法熔断,而每一拍都是真实计费请求(第五节)。
一、先查 TTL
不要把一个产品面的 TTL 外推到另一个产品面,也不要信"默认就是 1 小时",先实测。
Claude Code:
claude -p "hello" --output-format json
看结果里的 usage.cache_creation:写入记在 ephemeral_1h_input_tokens 就是 1 小时档,记在 ephemeral_5m_input_tokens 就是 5 分钟档。/usage 里的 Prompt cache (main) 一行(v2.1.251+)也会显示命中率、未命中次数和当前冷热。
以下按官方文档 https://code.claude.com/docs/en/prompt-caching(2026-11-16 核对):
| 你的情况 | 主会话默认 | 子代理、fork、压缩等其他请求 |
|---|---|---|
| Claude 订阅,套餐额度内 | 1 小时 | 5 分钟(少数服务端控制的辅助请求为 1 小时) |
| 订阅超额、改用 usage credits | 自动降到 5 分钟 | 5 分钟 |
| API key、云平台、自建网关 | 5 分钟 | 5 分钟 |
几处容易踩的坑:
- 订阅超额会悄悄降档。超出套餐额度后改按 usage credits 计费,Claude Code 会把主会话切回 5 分钟。想保住 1 小时就自己设 TTL。
- 网关要原样转发
anthropic-beta头。经ANTHROPIC_BASE_URL走网关时,1 小时 TTL 的请求有一部分放在anthropic-beta头里(extended-cache-ttl-…),网关要原样转发。 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1会剥掉这个头。这个变量是给"上游拒收预发布 beta 头、报 400"的网关准备的。设了它,请求体里仍会带ttl: "1h",但extended-cache-ttl头不再发送;能不能拿到 1 小时,取决于上游认不认只有ttl字段的请求。设了它的人一定要实测一次。- effort 和模型都会换缓存。多数模型每个 effort 档各有一份缓存,切档等于冷启动;Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 起在 API key 或订阅下切 effort 不失效,但设了
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS、走 Bedrock / Google Cloud / Claude apps gateway 或 HIPAA 配置时仍会失效。保温请求要继承原 turn 的 model 和 effort,切档放到阶段断点。
Codex 和其他链路:没有统一的查询方法,只能在本机同一 thread 做冷热对照(见第五节)。OpenAI API 用 prompt_cache_options.ttl(GPT-5.6 起默认 30m,可选 12h,写入 2.5 倍);ChatGPT 订阅下的 Codex CLI 不保证等同 API 的 TTL。
二、能用 1 小时就先改 TTL
在 Claude Code 里,保温之前先试这两个设置(v2.1.242+,只接受 5m 或 1h):
- 主会话:
promptCacheTtl: "1h",或环境变量CLAUDE_CODE_PROMPT_CACHE_TTL=1h - 子代理、fork、压缩等:
subagentPromptCacheTtl: "1h",或CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h
多个设置同时存在时,FORCE_PROMPT_CACHING_5M=1 优先级最高(两个桶都强制 5 分钟),其次是各桶的环境变量、各桶的设置,最后才是 ENABLE_PROMPT_CACHING_1H=1。
1 小时不是白送的:写入 2 倍基础价,5 分钟是 1.25 倍。如果你几乎不会空闲超过 5 分钟,换 1 小时只会多花钱。改完重跑第一节的命令,确认写入落在 ephemeral_1h。
1 小时 TTL 下的空闲压缩(idle compaction):上下文达到 20 万 token(CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 可改,最低 10 万)的会话,空闲约 54 分钟、1 小时缓存过期之前,Claude Code 会把它压缩成摘要(终端 v2.1.299 起,VS Code 和桌面版 Code 标签页 v2.1.314 起;v2.1.314 起网关和云平台用户只要开了 1 小时 TTL 也会触发)。它和"55 分钟保温"撞在同一个时间点:cache-refresher 的作者实测续温不会推迟压缩,压缩后下一条消息发的是摘要,之前保住的长前缀就白保了。保温和空闲压缩二选一:要保温就设 idleCompaction: false(v2.1.290+),或只对 20 万以下的会话保温。
三、还要保温,先算账
触发条件不再用经验节拍,改用 Pi 的续温公式(packages/ai/src/cache-warming.ts):
续聊概率 × 重建代价 − 续温代价 ≥ 阈值 → 续温,否则停
重建代价 = 前缀 × (写入价 − 读取价)
续温代价 = 前缀 × 读取价 + 极少量输出
Pi 的默认值:缓存寿命过去 90% 时评估一次;空闲时续聊概率取 0.15(他们用自己的数据测出来的常数);阈值 0.05 美元;续温请求只要 1 个输出 token、不重试;空闲保温最长 30 分钟。
这个公式的意义在于把"值不值"拆成三个能各自测的数:
- 续聊概率:最该用自己的数据替换。按"已经空闲到这一拍"为条件,统计在下一个缓存寿命内回来的比例。它随空闲时长下降很快,所以公式会自己在合适的时候停,不用另设拍数上限。
- 重建代价:取决于前缀大小和写入倍率,上下文越长越值得保。公式也自然给出一个"短会话不保温"的门槛,不用再单独设 20k 之类的下限。
- 续温代价:前缀乘读取价。读取价各模型不同(Opus 5.5 是基础价 0.05 倍,多数模型 0.1 倍),一定要用你实际模型的价格。
触发点贴着命中率开始衰减的那一点,而不是贴着 TTL 边界:公式在每一拍重新算续聊概率,概率掉下去就停,这正是这条原则的量化版本。
订阅用户的"美元"只是一把尺子:一次续温读取在 5 小时和每周额度里怎么折算,目前没找到官方说明。
四、算下来划算,挑现成工具
Claude Code v2.1.287 起有 mods(模组)。官方文档说 $.model.fork 会重放会话的最后一次请求,大部分从缓存读取,模型看得到工具但调用不了;下面几个工具都用它续温,并说明续温轮不进会话历史。这正是以前要靠 asyncRewake、合成用户轮和 PreToolUse 拒绝工具才勉强做到的事,所以不要再自己写保温状态机,直接挑一个:
| 工具 | 适合谁 | 怎么做 |
|---|---|---|
| karanb192/cache-tax | 想在冷发送前被拦一下的人 | /keepwarm 90m 开一个有边界的保温窗口,空闲 50 分钟发一次 fork;读到 0 或写入达到读取的 10% 就停;发消息前显示预估重写费用。需要 1 小时 TTL |
| olddonkey/cache-refresher | 想先看账、再决定要不要自动的人 | 状态栏倒计时,面板里并排显示"过期一次多少钱"和"续一次多少钱";自动续温默认关闭,开启后会临时关掉空闲压缩 |
| paulbkim-dev/claude-code-cache-warmer | 想装上就不管的人 | 照搬 Pi 的公式和 0.05 美元阈值;支持 5 分钟和 1 小时两档(会替你设 CLAUDE_CODE_PROMPT_CACHE_TTL);空闲时每档默认最多续 5 次 |
没有 mods 的旧版本可以看 ARahim3/cachebeat(Stop hook 的 asyncRewake 方案,会在会话历史里留下保温轮)。
想让保温轮顺带更新一份工作文档(模型此刻正对着完整上下文,是写交接摘要最便宜的时刻):fork 能拿到回复,可以在 mod 里把续温提示换成"更新工作文档"再由 mod 写盘。只是输出不再是 1 个 token,这部分要算进续温代价。
装上以后,仍然按第五节验一次:fork 走的是"其他请求"那个桶,官方默认 5 分钟;cache-tax 和 cache-warmer 都观察到 fork 续上了 1 小时前缀,但各自只有少量样本。
Codex 和其他没有 fork 接口的链路:先按公式算账;算下来不亏,再考虑同 thread 的 resume 方案,并且一定要排除一次性 worker(codex exec 的 rollout 标有 source=exec)。
五、先实测,再相信
usage 命中证据优先于社区经验和跨产品类比。实测建议包含以下对照(部分项跳过仍可上线,但会降低置信度):
- 长前缀冷启动对照 C;
- 同一会话的立即正对照 H;
- 候选时间点至少两个独立样本;
- 超过候选边界的冷启动阴性对照;
- 多拍链式实验,证明命中真的刷新 TTL,而不是只在首次写入后绝对计时。
上下文至少约 20k tokens,否则差异容易淹没在公共系统前缀和测量噪声中。只比较任何工具调用前的第一段模型请求;同一 turn 在工具返回后的第二段可能立刻命中,会把已经冷掉的第一段伪装成成功。
Codex 若存在长期公共背景缓存,不能只看 cached 绝对值。记录冷基线 C,用 D=max(0, first_cached-C) 判断会话长前缀的增量,并把 C 绑定 CLI 版本与测量时间。
验收报告分开写"已验证节拍"和"真实 TTL":不能因为选了 450 秒就声称 TTL 已确认为 10 或 15 分钟。
六、核算:usage 只证明命中,不证明省钱
保温跑了一阵以后,用会话记录回放一遍:
- 把每段空闲按"回来前是否过期"分组,统计冷重建的次数和写入量;
- 把保温请求本身的读取和输出全部算进成本;
- 对比"不保温""只改 TTL""改 TTL 加保温"几种方案的总费用。
一个真实的反例:作者环境的 Codex 侧按真实记录测算,长静默事件只占 0.24%(Claude 侧为 2.0%)、前缀中位数只有 Claude 的 39%、缓存写入倍率也更低。全链重放显示回本需救回约 168 次,而覆盖窗口内可救的未命中总共只有 108 次,即使每次都救成功仍然亏损,因此整体关闭。同一套方法在两条链路上给出相反结论,这正是"先判断该不该"的意义。
运行原则
- 实测和回放优先于社区经验、官方默认值和其他产品的类比。
- 能改 TTL 解决的,不保温;能用现成工具的,不自造。
- 短对话不保温;缓存已冷不补拍;空闲压缩和保温不同时打在一个点上。
- 任何异常停保温,但永远放行用户自己的输入。