编码代理的提示缓存：能省多少，何时失效
编码代理每次请求都重发完整上下文，提示缓存让重复内容不必每次按原价计费。但它也很脆弱：开头附近只改一个字节，下一轮就可能重新支付全部成本。
代理会话中的每一步都是新的 API 请求，包括你发出的每条消息，以及代理送回的每批工具结果。模型不会在请求之间保留记忆，因此代理重发全部内容：系统提示、工具定义、项目指令、整段对话，最后才是新内容。大部分都与上次请求相同，提供方通过提示缓存避免重复处理。
Claude Code 会替你管理缓存；直接使用 API 时，一个顶层 cache_control 字段即可开启自动缓存。Codex CLI 使用的 OpenAI 模型也遵循前缀规则，但价格和有效期不同。下文的数字都是 Claude 的。
固定顺序中的精确前缀
缓存把每次请求的开头，也就是前缀，与近期处理过的内容比较。匹配必须完全一致：改动一个字符，它之后的所有内容都会失效。缓存不是按文件或章节分别建立的。
前缀按固定顺序读取：工具定义、系统提示，再到消息。某一层改变，会使该层及其后的内容失效。修改一条消息，工具和系统提示仍可缓存；修改工具定义，后面的缓存全部失效。
Claude Code 把很少变化的内容放在前面：自身指令和工具定义，然后是你的项目上下文（CLAUDE.md、记忆、规则），最后是对话。普通一轮中，上次请求的全部内容都能构成前缀，只有最新往返是新内容。
缓存写入和读取各花多少
缓存改变的是输入价格，不是回答。以 2026 年 9 月为准，Anthropic 按各模型的基本输入价格计算：有效期五分钟的缓存写入为 1.25 倍，一小时为 2 倍；读取为十分之一，但 Claude Fable 5.1 是 0.025 倍、Claude Opus 5.5 是 0.05 倍。最后一个缓存点之后的内容按普通输入计费。
| 模型 | 输入 | 输出 | 缓存读取 | 缓存写入 5 分钟 | 缓存写入 1 小时 | 上下文 |
|---|---|---|---|---|---|---|
| Claude Haiku 4.5 | 1.00 | 5.00 | 0.10 | 1.25 | 2.00 | 200,000 |
| Claude Sonnet 5 | 2.00 | 10.00 | 0.20 | 2.50 | 4.00 | 1,000,000 |
| Claude Sonnet 4.6 | 3.00 | 15.00 | 0.30 | 3.75 | 6.00 | 1,000,000 |
| Claude Opus 4.6 | 5.00 | 25.00 | 0.50 | 6.25 | 10.00 | 1,000,000 |
| Claude Opus 4.7 | 5.00 | 25.00 | 0.50 | 6.25 | 10.00 | 1,000,000 |
| Claude Opus 4.8 | 5.00 | 25.00 | 0.50 | 6.25 | 10.00 | 1,000,000 |
| Claude Opus 5 | 5.00 | 25.00 | 0.50 | 6.25 | 10.00 | 1,000,000 |
| Claude Opus 5.5 | 4.00 | 20.00 | 0.20 | 5.00 | 8.00 | 1,000,000 |
| Claude Fable 5 | 10.00 | 50.00 | 1.00 | 12.50 | 20.00 | 1,000,000 |
| Claude Fable 5.1 | 10.00 | 50.00 | 0.25 | 12.50 | 20.00 | 1,000,000 |
以 2026 年 9 月 Claude Sonnet 5 每百万输入 token 2 美元的标价，计算一段 100,000 token 的上下文。从缓存读取，每次请求花 0.02 美元；不使用缓存为 0.20 美元；未命中后重新写入，五分钟有效期为 0.25 美元，一小时为 0.40 美元。一次未命中比完全不用缓存还贵，因为写入价格高于普通输入。
按五分钟价格计算，多数模型重写一次相当于读取 12.5 次；Opus 5.5 是 25 次，Fable 5.1 是 50 次。读取越便宜，差距越大。五分钟缓存只要读取一次就能回本；一小时缓存需要读取两次。
五分钟还是一小时
有效期，也称 TTL，是缓存前缀在无人使用时能保留多久；每次读取都会免费重置计时器。计时从请求开始时算，不是从回答结束时算：如果回答流式输出持续四分钟，下一次请求只有约一分钟可复用五分钟缓存。
以 2026 年 9 月为准，Claude Code 在订阅套餐所含用量内，为主对话提供一小时缓存；使用 API 密钥、云服务提供商，或订阅转而消耗用量积分时，为五分钟。不论哪种方式，子代理默认都是五分钟。
要为主对话选择，可在设置中使用 promptCacheTtl，或把 CLAUDE_CODE_PROMPT_CACHE_TTL 环境变量设为 5m 或 1h（需要 Claude Code v2.1.242 或更新版本）。请求间隔在五至六十分钟之间时，一小时通常划算，例如开会、审查，或等待长时间构建。若请求总在五分钟内连续发出，一小时只会提高每次写入的成本。
claude -p "hello" --output-format json查看写入采用的有效期：usage.cache_creation 中，一小时写入列在 ephemeral_1h_input_tokens，五分钟列在 ephemeral_5m_input_tokens。
哪些变化会悄悄破坏缓存
缓存未命中不会报错，只是该轮更慢，用量中本应是读取的地方出现大量写入。编码代理中的常见原因有：
- 切换模型。每个模型有自己的缓存，任务中途使用
/model会以未缓存方式重读整段历史。指定另一模型的技能，以及在 Opus 与 Sonnet 间切换的opusplan规划模式，也一样。 - 改变推理强度。多数模型的每个强度级别有独立缓存。以 2026 年 9 月为准，使用 API 密钥或 Claude 订阅时，Opus 5.5 和 Fable 5.1 可保留缓存。
- 改变工具集合。工具定义排在最前面，增删一个都会使后面的内容失效。Claude Code 默认通过工具搜索按需加载 MCP 工具，使服务器变化留在前缀之外。若改为预先加载，例如经由自定义
ANTHROPIC_BASE_URL网关，MCP 服务器自行崩溃或重连也会破坏缓存。 - 提示开头的任何变化。系统提示中的时间戳会让其后内容每次请求都重写，永远无法从缓存读取。Claude Code 升级通常也会改变系统提示，所以升级后的首次会话从冷缓存开始。
- 暂停超过有效期：API 密钥默认五分钟，订阅默认一小时。
为什么休息后的第一轮更贵
未命中的成本会在下一次请求中支付一次：整个前缀重新处理，并按写入价格放回缓存；之后的请求又可从缓存读取。因此，即使休息后第一条消息只有一行，也会更慢、更贵。
压缩按设计会造成一次未命中，但缓存仍有效时成本较低，因为摘要请求能从缓存读取历史。休息很久后，它要按未缓存输入重新读取整段历史，所以刚回到会话就压缩尤其贵。
相应的习惯是：开始时选定模型和推理强度，离开前完成当前任务；主题变化时用 /clear，不要恢复冷却已久的会话。若要丢掉一条走错的路线，/rewind 比压缩合适：它截回已经缓存的前缀。Pro 和 Max 套餐下，Claude Code 还可在长时间离开后，提议从摘要恢复大型会话。
如何看缓存命中率
API 每次响应报告三个输入计数：cache_read_input_tokens 是从缓存读取的量；cache_creation_input_tokens 是写入量；input_tokens 只统计最后一个缓存点之后的内容，因此在缓存良好的会话中看起来很小。总输入是三者之和。
命中率是缓存读取量除以总输入。长期保持缓存有效的会话，每次请求大部分输入都应为读取。短会话中低命中率正常，因为首次写入占总输入很大比例；长会话每轮都大量写入，则应检查上面列出的原因。
/usageClaude Code v2.1.251 起，Prompt cache (main) 一行显示从缓存读取的输入比例、未命中次数，以及缓存是否仍有效。
从 v2.1.260 起，如果能判断原因，该行也会指出上次未命中的可能原因，例如工具定义改变。它只覆盖主对话：子代理有自己的提示和工具，首次请求无法读取父会话的缓存。API 用户可在 Console 的 Usage 页面查看缓存读取比例图表；截至 2026 年 9 月仍处于 beta 的缓存诊断功能，还会报告连续两次请求从哪里开始出现差异。
订阅与 API：谁承担未命中成本
使用 API 密钥时，未命中会按表中价格花钱，也会消耗速率上限余量。对多数 Claude 模型，缓存读取不计入每分钟输入 token 上限，写入和未缓存输入则计入。
Pro 或 Max 套餐没有逐 token 账单，/usage 中的美元金额是给 API 用户参考的估算。未命中改为消耗套餐上限。Claude Code 文档将缓存未命中列为长会话用量高于直觉的原因之一。Pro、Max、Team 和 Enterprise 套餐中，若未命中达到近期用量的十分之一，/usage 明细会给出提示。
缓存 token 仍然是 token
即使价格只有十分之一，每次请求仍会读取整段上下文。Claude Code 文档也指出，一段开了一整天的会话，即使只问一行，仍会为整段对话消耗用量。因此要同时做到两点：保持提示前端稳定以便缓存，并缩小上下文，让每次读取和未命中的成本都更低。
若不想手动维持较小上下文，capsul 可驱动你已经登录的代理 CLI，在你设定的 token 预算内发送任务所需内容。达到预算就停止，并告知未纳入的内容。基准测试页逐模型公布测量效果，同时列出答案检查结果。
常见问题
Claude Code 会自动使用提示缓存吗？
会。除非用 DISABLE_PROMPT_CACHING 环境变量将其关闭，否则 Claude Code 会自动管理提示缓存，并把较少变化的内容放在请求前面。以 2026 年 9 月为准，订阅套餐所含用量中的主对话使用一小时缓存；使用 API 密钥或云服务提供商时为五分钟。
Claude 的提示缓存有效期是 5 分钟还是 1 小时？
两种都有。API 默认五分钟；每次读取都会免费重置计时器。一小时有效期让每次写入从基本输入价格的 1.25 倍升到 2 倍。以 2026 年 9 月为准，Claude Code 在订阅主对话中默认用一小时，使用 API 密钥时用五分钟，除非你设置 promptCacheTtl。请求间隔超过五分钟时，一小时有效期才可能划算。
Claude 缓存读取 token 要多少钱？
以 2026 年 9 月为准，缓存读取通常是模型基本输入价格的十分之一，但 Claude Fable 5.1 是 0.025 倍，Claude Opus 5.5 是 0.05 倍。Claude Sonnet 5 每百万缓存读取 token 为 0.20 美元，未缓存输入为 2 美元。缓存写入比普通输入贵，因此只有后来发生读取，缓存才会省钱。
为什么我的提示缓存命中率低？
通常是提示开头的内容不断变化，或两次请求间隔超过缓存有效期。编码代理中常见原因包括会话中途切换模型或推理强度、工具定义变化、系统提示带时间戳，以及 API 密钥模式下暂停超过五分钟。短会话的命中率也天然偏低，因为首次写入占总输入比例很大。Claude Code 的 /usage 会统计未命中次数，v2.1.260 起还会尽可能指出最近一次的原因。
编辑 CLAUDE.md 会破坏提示缓存吗？
在 Claude Code 会话中途不会。项目根目录和用户级 CLAUDE.md 只在会话开始时读取一次，因此编辑既不会立即使缓存失效，也不会在下次 /clear、/compact 或重启前生效。子目录中的嵌套 CLAUDE.md 会在 Claude 首次读取该目录中的文件时才加载。
$ npm i -g @penra/capsul