# Cache Keepalive

> 提示缓存保温值不值的判断与排障：先查当前链路的缓存寿命（TTL），再按续温公式算账，最后挑现成工具，不自造保温链。用于 Claude Code、Codex 或其他带提示缓存的 Agent：阅读和回复的间隔可能超过缓存寿命、想知道该改 TTL 还是保温、保温跑了一阵想核算省没省、或缓存莫名不命中时使用。

- Skill: `ruodou233/cache-keepalive` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx get-skill add ruodou233/cache-keepalive`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruodou233/cache-keepalive/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ruodou233 (https://skillmd.com/u/ruodou233)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/ruodou233/cache-keepalive

---


# cache-keepalive

如果你常常来不及在缓存有效期内读完 Agent 的回答并回复它，可以考虑缓存保温。例如，在缓存寿命为 5 分钟的环境里，阅读、思考或离开一会儿就可能跨过这个窗口；具体时间因模型、产品链路和配置而异，不能统一按 5 分钟判断。

**缓存保温并非一律需要。**顺序是：先查 TTL，能直接用 1 小时 TTL 就先改 TTL；改完还有跨不过去的空档，再按公式算账；算下来划算，才挑一个现成工具。

保温请求仍是一次真实模型调用。"自动"指程序决定何时触发，不是零 token，也不是绕过套餐或 API 限额。

## 先问四个问题

保温防的是「静默期跨过缓存寿命导致冷重建」。它不是普遍有收益的，按顺序问：

1. **默认缓存寿命是否已覆盖你的静默窗口？**覆盖了就不需要保温；没覆盖，先看能不能直接把寿命改长（第一、二节）。
2. **算下来划不划算？**按续温公式算（第三节）。usage 只能证明**命中**，不能证明**省钱**。
3. **有没有可归因的合成请求入口？**没有则方法不适用。Claude Code 现在有现成的入口和工具（第四节）。
4. **能不能读到 usage 验证命中？**读不到就别上自动链：无法验证就无法熔断，而每一拍都是真实计费请求（第五节）。

## 一、先查 TTL

不要把一个产品面的 TTL 外推到另一个产品面，也不要信"默认就是 1 小时"，先实测。

Claude Code：

```bash
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](https://github.com/earendil-works/pi) 的续温公式（`packages/ai/src/cache-warming.ts`）：

```text
续聊概率 × 重建代价 − 续温代价 ≥ 阈值        → 续温，否则停
重建代价 = 前缀 × (写入价 − 读取价)
续温代价 = 前缀 × 读取价 + 极少量输出
```

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](https://github.com/karanb192/cache-tax) | 想在冷发送前被拦一下的人 | `/keepwarm 90m` 开一个有边界的保温窗口，空闲 50 分钟发一次 fork；读到 0 或写入达到读取的 10% 就停；发消息前显示预估重写费用。需要 1 小时 TTL |
| [olddonkey/cache-refresher](https://github.com/olddonkey/cache-refresher) | 想先看账、再决定要不要自动的人 | 状态栏倒计时，面板里并排显示"过期一次多少钱"和"续一次多少钱"；自动续温默认关闭，开启后会临时关掉空闲压缩 |
| [paulbkim-dev/claude-code-cache-warmer](https://github.com/paulbkim-dev/claude-code-cache-warmer) | 想装上就不管的人 | 照搬 Pi 的公式和 0.05 美元阈值；支持 5 分钟和 1 小时两档（会替你设 `CLAUDE_CODE_PROMPT_CACHE_TTL`）；空闲时每档默认最多续 5 次 |

没有 mods 的旧版本可以看 [ARahim3/cachebeat](https://github.com/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 命中证据优先于社区经验和跨产品类比。实测建议包含以下对照（部分项跳过仍可上线，但会降低置信度）：

1. 长前缀冷启动对照 C；
2. 同一会话的立即正对照 H；
3. 候选时间点至少两个独立样本；
4. 超过候选边界的冷启动阴性对照；
5. 多拍链式实验，证明命中真的刷新 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 次，**即使每次都救成功仍然亏损**，因此整体关闭。同一套方法在两条链路上给出相反结论，这正是"先判断该不该"的意义。

## 运行原则

1. 实测和回放优先于社区经验、官方默认值和其他产品的类比。
2. 能改 TTL 解决的，不保温；能用现成工具的，不自造。
3. 短对话不保温；缓存已冷不补拍；空闲压缩和保温不同时打在一个点上。
4. 任何异常停保温，但永远放行用户自己的输入。

