Claude Code 里看到缓存未命中或一次 turn 的 token 成本突然升高，通常不是多出来一个“未命中手续费”。更准确的理解是：本来应该走便宜缓存读取的可复用前缀没有被读到，系统重新处理输入、写入缓存，或者只命中了其中一部分，输出 token 仍然照常计入。
截至 2026 年 5 月 24 日，Anthropic 的公开价格把这个差异讲得很清楚：5 分钟缓存写入按基础输入价格的 1.25 倍计，缓存读取按 0.1 倍计。同样一段前缀从“写入”变成“读取”，比值就是 1.25 / 0.1 = 12.5。这个数字是写入和读取之间的倍率差，不是 Claude Code 官方定义的 cache miss 附加费。
真正要先确认的是路线。这个数字来自订阅登录的使用量、API key 账单、Agent SDK 估算、Bedrock、Vertex、Foundry，还是某个 gateway？路线不清时，不要先改 /compact，也不要直接说是缓存 bug。先拿到 cache_creation_input_tokens、cache_read_input_tokens、模型、MCP 变化、版本、时间戳和对应账单面。
快速判断：先证明路线，再修缓存
| 问题 | 短答案 | 要收集的证据 |
|---|---|---|
| 缓存未命中是不是单独收费？ | 不是。它表示便宜读取没有发生，前缀被重新处理或重新写入。 | 同一路线里的 cache creation 与 cache read 字段。 |
| 为什么有人说贵 12.5 倍？ | 5 分钟 cache write 是 1.25x，cache read 是 0.1x，同样 token 量相除是 12.5。 | 当前 Anthropic 价格页和本次使用记录。 |
| 第一项检查是什么？ | 路线归属。订阅、API key、SDK、云厂商、gateway 不能混看。 | /status、/cost、Console、Usage and Cost API、云厂商账单。 |
| 什么时候更可疑？ | 相似 turn 连续出现高 cache creation、低 cache read，且模型、MCP、路线、时间间隔都稳定。 | 相邻 turn 的字段差异、版本、MCP 列表、模型、路径或工作树变化。 |
| 不该先做什么？ | 不要盲目 compact、换模型、换 provider 或把社区截图当账单证据。 | 先定位失效动作，再决定最小修复。 |
如果你的问题其实是订阅和 API key 到底谁在计费，先看 Claude Code API key 与订阅计费。如果是上下文太大、MCP 工具太多导致每次请求都很重，应该切到 Claude Code MCP 上下文过载。缓存未命中只解释“为什么这次没吃到读取折扣”，不自动解释所有限额和账单问题。
12.5x 只是写入/读取的数学
Anthropic 的 Claude API pricing 将普通输入、缓存写入、缓存读取和输出分开计价。按当前公开口径，5 分钟 cache write 是基础输入价格的 1.25 倍，1 小时 cache write 是 2 倍，cache read 是 0.1 倍。
text5-minute cache write / cache read = 1.25 / 0.1 = 12.5 1-hour cache write / cache read = 2.0 / 0.1 = 20
所以，12.5x 可以用来解释“同样一段前缀，如果这次是写入而不是读取，为什么成本看起来高很多”。它不能单独证明 Claude Code 多收了一个未命中费用，也不能单独证明产品有 bug。一个新会话、模型切换、MCP 变化、长时间空闲、升级版本或压缩上下文之后出现一次 cache creation，可能只是预期行为。
这个差异在大前缀里最明显：长对话历史、项目文件上下文、工具返回、MCP server 定义、子代理上下文、大 system prompt 或一次性贴入的资料包。小前缀 miss 可能只是噪音；大前缀连续 miss，才值得进入证据级排查。
token 分类账：别只看总量
排查时把一次 turn 拆成 token 类别，比看一个总 token 数可靠。总数只能说明“这次很大”，不能说明“为什么贵”。
| 计量项 | 含义 | 排查用途 |
|---|---|---|
| 普通输入 token | 没有从缓存读取、直接被模型处理的输入。 | 判断没有缓存或只部分命中的基础成本。 |
cache_creation_input_tokens | 被写入缓存或为缓存创建处理的 token。 | 一次预期写入正常；连续高写入才是警报。 |
cache_read_input_tokens | 从已有缓存中读取的 token。 | 读取高、写入低通常说明缓存复用有效。 |
| 输出 token | 模型生成的回答。 | 缓存只能降低输入侧成本，不能让输出免费。 |
| 订阅使用量 | plan 或 seat 的窗口、限制、重置提示。 | 不能直接拿来和 API 发票比较。 |
/cost 与 SDK cost 字段 | 本地或客户端估算。 | 适合监控趋势，但弱于正式账单。 |
| Console、Usage and Cost API、云厂商账单 | 对各自路线有权威性的账单面。 | 作为最终金额、报销或支持工单证据。 |
Anthropic 的 Agent SDK cost tracking 明确把 total_cost_usd、costUSD 这类字段定位为估算。估算很有用，能发现 runaway session，也能帮助你比较几次相似 turn，但它不是银行账单，也不是云厂商 invoice。
路线不清时，先在 Claude Code 里做最小确认：
bashclaude /status /cost
/status 用来确认当前账号或路线，/cost 可作为 API 风格花费监控。最终要对账时，仍然回到产生这次运行的那条路线：Claude Console、Usage and Cost API、Bedrock/Vertex/Foundry 发票、gateway 日志，或订阅使用量页面。
哪些动作会让缓存失效
Claude Code 的 prompt caching 文档 讲的是前缀匹配。前面发生变化，后面即使内容看起来一样，也可能无法复用旧缓存。排查时不要只问“我是不是用了很多 token”，更要问“在这次昂贵 turn 之前，前缀形状有没有改变”。
| 最近动作 | 风险 | 下一步检查 |
|---|---|---|
| 切换模型 | 高 | 对比 spike 前后的 model 字段和时间戳。 |
| 连接或断开 MCP server | 高 | MCP 工具定义可能改变早期前缀。 |
| 拒绝整个工具 | 高 | whole-tool denial 会改变可用工具上下文。 |
执行 /compact | 高 | compact 会重写对话上下文，可能打断复用。 |
| 升级 Claude Code | 高 | 版本变化可能改变 prompt 形状或缓存作用域。 |
| 更换 provider、API route 或 gateway | 高 | 缓存作用域和账单归属都可能变。 |
| 长时间空闲 | 中 | TTL 可能已过期，下一次自然要写入。 |
| 子代理、fork、worktree、目录变化 | 中 | 上下文可能按路径、进程、agent 或 route 分裂。 |
| 编辑文件 | 较低 | 文件变动会增加上下文，但不必然改写早期前缀。 |
| 改 output style 或 permission mode | 较低 | 如果 timing 正好吻合，仍要记录。 |
/recap 或 rewind | 较低 | 有助于导航，但仍要看字段变化。 |
稳妥结论要保守：一次 cache write 可能只是新前缀第一次写入；多次相似 turn 连续写入才异常。所谓“相似”至少要同模型、同路线、同 MCP 设置、短时间间隔、没有 compact 或升级，并且输入结构接近。
路线证据：不要把五种数字混成一个账单
同一个人类工作流可以经过不同计量合同。订阅登录、API key、SDK 估算、云厂商和 gateway 都可能在界面上显示“成本”或“使用量”，但它们不是同一种证据。
| 路线 | 数字可能代表什么 | 更强证据 |
|---|---|---|
| Claude 订阅登录 | plan/seat 使用量、窗口限制、重置时间和 included usage 行为。 | Help Center 用量说明、账号状态、/status、plan 提示。 |
| Claude API key | 按量 API token 账单。 | Claude Console、Usage and Cost API、项目计费设置。 |
| Agent SDK | SDK 消息里的使用量和成本估算。 | SDK 字段加 Console 或 Usage and Cost API 对照。 |
| Bedrock、Vertex、Foundry | 云厂商路线的模型使用、缓存支持和 provider 账单。 | 云厂商 invoice、请求日志和 provider 路线文档。 |
| gateway | gateway 的记录以及上游 pass-through 行为。 | gateway 日志加可取得的上游账单。 |
Anthropic 的 Claude Code costs 和 Help Center usage and limits 重点是把订阅使用量和 API 账单分开。订阅限额提示不能证明 API spend；API 估算也不能证明订阅 seat 被额外收费。
如果最终问题是 plan 窗口被打断，看 Claude Code rate limit 或 Claude Code rate limit reached。缓存数学能解释为什么某段上下文消耗更快，但不能替代限额恢复流程。
修复顺序：先小改，再验证下一次
不要把一次高成本 turn 当作重构整个工作流的理由。先用最小动作复现和确认。
- 确认路线。 这次数字来自订阅使用量、API key、SDK 估算、云厂商还是 gateway。
- 读取缓存字段。 连续几次相似 turn 对比
cache_creation_input_tokens和cache_read_input_tokens。 - 命名失效动作。 检查模型、MCP、whole-tool denial、
/compact、升级、provider、TTL、子代理、fork、worktree、目录变化。 - 保持可复用前缀稳定。 同一任务里不要频繁切模型、换 MCP 或把无关文件塞进早期上下文。
- 用
/clear切开无关任务。 无关任务混在一起会让前缀又大又乱。 - 只在自然边界使用
/compact。 对话太大时 compact 有价值，但它不是 cache miss 的第一反应。 - 谨慎评估 1 小时 TTL。 1 小时写入倍率更高，只有后续读取能覆盖这次更贵写入时才值得。
- 验证下一次相似 turn。 修复有效应表现为重复 creation 下降、read 上升，且路线和模型没有变。
这套顺序的好处是可回滚。先改一个变量，再看字段变化；不要同时换模型、关 MCP、compact、换 gateway，否则即便成本下降，你也不知道真正原因。
可疑 spike 证据包
不要只发一句“Claude Code 缓存 bug 了”。能让同事或支持工程师判断的证据包，至少要能对齐同一路线、同一时间和同一上下文形状。
| 证据 | 为什么重要 |
|---|---|
| 时间戳和时区 | 让使用记录和账单记录可以对齐。 |
| Claude Code 版本 | 升级可能改变 prompt 形状。 |
| 模型 | 模型切换是已知高风险失效动作。 |
| 活跃路线 | 订阅、API key、SDK、provider、gateway 不能混证据。 |
| MCP server 前后列表 | connect/disconnect 会改变早期前缀。 |
| 工具权限变化 | whole-tool denial 是高风险动作。 |
/compact、/clear、/recap、rewind 历史 | 这些动作会影响对话形状。 |
cache_creation_input_tokens 与 cache_read_input_tokens | 写入与读取的核心证据。 |
| 相似 hit/miss turn 对照 | 一张孤立截图弱，成对比较强。 |
| 账单面 | Console、Usage and Cost API、provider invoice 或订阅限额提示。 |
边界很简单：如果刚换模型、刚连 MCP、刚 compact、刚升级或刚跨 provider，一次 cache creation 很可能正常。如果路线、模型、MCP、时间间隔和上下文都稳定，仍反复 creation、几乎没有 read，再进入 bug 或支持工单路径。
常见问题
Claude Code cache miss 是单独费用吗？
不是。更准确的说法是，原本可复用前缀没有通过便宜读取路径复用，而是被重新处理或写入缓存。账单里应看 token 类别和路线，不是找一个叫 cache miss fee 的新项目。
为什么会看到 12.5x？
这个数字来自 Anthropic 当前缓存倍率：5 分钟 cache write 是基础输入的 1.25x，cache read 是 0.1x。相同 token 量下，1.25 除以 0.1 等于 12.5。它是写入和读取的比较，不是官方未命中罚金。
哪些字段最能证明缓存行为？
先看 cache_creation_input_tokens 和 cache_read_input_tokens。高 creation、低 read 表示这段前缀没有被便宜读取。连续几次相似 turn 都这样，比单次 spike 更有诊断意义。
/compact 会降低 token 成本吗？
有时会，但它不是万能修复。/compact 可以在自然边界压缩超大对话，但也会重写上下文，从而打断已有缓存复用。先确认是否真的上下文过大，再使用 compact。
1 小时 TTL 应该打开吗？
只有路线支持、并且你的复用节奏能吃到后续读取时才值得。1 小时写入倍率高于 5 分钟写入，如果后续没有足够读取，它可能只是让第一次写入更贵。
/cost 就是我的 Claude 账单吗？
不是。/cost 和 SDK cost 字段适合监控趋势，尤其在 API 风格路线里很方便。最终账单应回到 Claude Console、Usage and Cost API、云厂商 invoice、gateway 对账记录，或订阅使用量页面。
什么时候可以说是缓存 bug？
当你已经有同一路线证据：时间戳、版本、模型、路线、MCP 设置、工具权限、cache creation/read 字段、相似 hit/miss turn 和对应账单面。没有这些证据之前，普通失效动作或 TTL 过期更常见。