# Claude Code のキャッシュミスと token コスト：1 回の turn が急に高く見える理由

> Claude Code の cache miss は独立した追加料金ではありません。経路、cache creation、cache read、直前の無効化要因、請求面をそろえてから判断します。

- URL: https://blog.laozhang.ai/ja/posts/claude-code-cache-miss-token-costs
- Published: 2026-05-24
- Updated: 2026-05-24
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ja/about)
- Topic: Claude Code
- Tags: Claude Code, Prompt Caching, Token Costs, Claude API, Anthropic

---
Claude Code で cache miss や高い token コストが見えたとき、最初に探すべきものは「未命中という名前の追加料金」ではありません。多くの場合、再利用できるはずの prefix が安い cache read に乗らず、入力が再処理された、または cache creation として再度書き込まれたという意味です。モデルが生成した output tokens は、入力側のキャッシュとは別に通常どおり発生します。

2026 年 5 月 24 日時点の Anthropic の公開価格では、5 分の cache write は基本 input の 1.25 倍、cache read は 0.1 倍です。同じ token 量で見れば 1.25 / 0.1 = 12.5 になります。つまり 12.5x は「書き込みと読み取りの比較」であり、Claude Code が公式に定義した cache miss 罰金ではありません。

次に確認するのは経路です。その数字は Claude のサブスクリプション利用量なのか、API key の従量課金なのか、Agent SDK の推定値なのか、Bedrock、Vertex、Foundry、gateway の記録なのか。経路を決めずに `/compact` を打つ、モデルを変える、バグだと決める、という順番にすると証拠が壊れます。まず `cache_creation_input_tokens`、`cache_read_input_tokens`、モデル、MCP、バージョン、時刻、請求面をそろえます。

![Claude Code cache miss の経路、write/read 比率、cache fields、stop rule を示す確認ボード](https://blog.laozhang.ai/posts/ja/claude-code-cache-miss-token-costs/img/cover.webp)

## まず見るもの：経路、フィールド、直前の変更

| 問い | 短い答え | 集める証拠 |
| --- | --- | --- |
| cache miss は別料金か | いいえ。安い read が起きず、prefix が再処理または再書き込みされた状態です。 | 同じ経路の cache creation と cache read。 |
| なぜ 12.5x と言われるのか | 5 分 write は 1.25x、read は 0.1x。同量なら 1.25 / 0.1 = 12.5 です。 | Anthropic の価格表と usage フィールド。 |
| 最初に確認すること | どの経路の数字か。subscription、API key、SDK、cloud provider、gateway を混ぜないこと。 | `/status`、`/cost`、Console、Usage and Cost API、provider invoice。 |
| 疑わしいパターン | 同じような turn で high creation、low read が続き、model、MCP、route、時間間隔が安定している。 | 隣接 turn の比較、MCP 一覧、model、version、時刻。 |
| 先にやらないこと | 原因不明のまま compact、provider 変更、bug 断定をしないこと。 | まず prefix を変えた行動を特定します。 |

経路そのものが曖昧なら、先に [Claude Code API key とサブスクリプション課金](https://blog.laozhang.ai/ja/posts/claude-code-api-key-vs-subscription-billing) を確認してください。MCP 定義や tool context が大きすぎるなら [Claude Code MCP context overload](https://blog.laozhang.ai/ja/posts/claude-code-mcp-context-overload) が近い問題です。キャッシュミスは入力側の再利用に関する説明であり、限度額、プラン窓、プロバイダー請求の全体像を一つで解決するものではありません。

## 12.5x は write/read の倍率で読む

[Claude API pricing](https://platform.claude.com/docs/en/about-claude/pricing) は、通常 input、cache write、cache read、output を分けています。現在の公開説明では、5 分 cache write が 1.25x、1 時間 cache write が 2x、cache read が 0.1x です。

```text
5-minute cache write / cache read = 1.25 / 0.1 = 12.5
1-hour cache write / cache read = 2.0 / 0.1 = 20
```

この式は同じ prefix の token 量を比較するときだけ意味があります。前回は read だったのに今回は write になった、あるいは read されると思った prefix が creation 側に出た、という読み方です。新しい会話、model の切り替え、MCP server の接続や切断、長い idle、Claude Code の更新、`/compact` の直後に一度 creation が増えることは、正常な説明で足りる場合があります。

コスト差が目立つのは prefix が大きいときです。長い会話履歴、プロジェクト context、tool result、MCP server definitions、subagent context、file pack、大きな system prompt が早い位置にあると、read できなかっただけで 1 turn が重く見えます。小さな miss はノイズかもしれませんが、大きな creation が似た turn で繰り返されるなら調査対象です。

## token の分類帳：total だけでは原因が見えない

![Claude Code cache creation と cache read token の分類帳](https://blog.laozhang.ai/posts/ja/claude-code-cache-miss-token-costs/img/token-ledger.webp)

高い turn を total tokens だけで見ると、量はわかっても原因がわかりません。Claude Code の数字は token class に分けて読んだほうが安全です。

| メーター | 意味 | 使い方 |
| --- | --- | --- |
| 通常 input tokens | キャッシュから読まれず、モデルが直接処理した入力。 | キャッシュがない、または一部だけ一致した場合の基礎コスト。 |
| `cache_creation_input_tokens` | prompt cache に書かれた、または creation 側で処理された token。 | 1 回の expected write は普通。連続 high creation が重要です。 |
| `cache_read_input_tokens` | 既存 cache entry から読まれた token。 | read が高く creation が低ければ再利用は概ね効いています。 |
| output tokens | モデルが生成した返答。 | 入力側キャッシュが効いても output は無料になりません。 |
| subscription usage | plan、seat、limit window、reset の使用量。 | API invoice と直接比較しないこと。 |
| `/cost` と SDK cost fields | ローカルまたはクライアント側の推定値。 | 傾向確認には便利ですが、正式請求より弱い証拠です。 |
| Console、Usage and Cost API、provider invoice | その経路の権威ある請求面。 | 最終的な金額確認や support packet に使います。 |

[Agent SDK cost tracking](https://code.claude.com/docs/en/agent-sdk/cost-tracking) は `total_cost_usd` や `costUSD` を estimate として扱います。推定値は runaway session の早期発見には役立ちますが、最終的な請求証拠としては Claude Console、Usage and Cost API、provider invoice など経路ごとの公式面に戻ります。

経路が曖昧なときは、まず最小確認をします。

```bash
claude
/status
/cost
```

`/status` は現在の account や route を見るため、`/cost` は API 風の費用監視に使うためのものです。請求を確定する証拠は、その run を生んだ経路に属します。

## 何が Claude Code のキャッシュを壊すのか

![Claude Code の model MCP compact route 変更による cache invalidator matrix](https://blog.laozhang.ai/posts/ja/claude-code-cache-miss-token-costs/img/invalidator-matrix.webp)

[Claude Code prompt caching](https://code.claude.com/docs/en/prompt-caching) の要点は prefix matching です。リクエストの早い位置が変わると、その後ろが似ていても以前の cache entry に一致しないことがあります。したがって、問題は「token が多い」だけでなく、「高い turn の直前に prefix の形が変わったか」です。

| 直前の行動 | リスク | 次に確認すること |
| --- | --- | --- |
| model の切り替え | 高 | spike 前後の model と timestamp を比較。 |
| MCP server の接続/切断 | 高 | tool definitions が早い prefix を変える可能性。 |
| tool 全体の deny | 高 | whole-tool denial は available tool context を変えます。 |
| `/compact` | 高 | conversation context を書き換え、reuse を切ることがあります。 |
| Claude Code の upgrade | 高 | prompt shape や cache scope が変わる可能性。 |
| provider、API route、gateway の変更 | 高 | cache scope と billing owner が変わります。 |
| 長い idle gap | 中 | TTL が切れて次の read に間に合わない可能性。 |
| subagent、fork、worktree、directory change | 中 | context が path、process、agent scope で分かれる可能性。 |
| ファイル編集 | 低め | context は増えますが、必ず早い prefix を壊すとは限りません。 |
| output style や permission mode の変更 | 低め | timing が一致する場合だけ記録します。 |
| `/recap` や rewind | 低め | 便利な操作ですが、usage fields は確認します。 |

安全な解釈は控えめです。意味のある context change のあとに cache write が出るのは自然です。stable route、stable model、stable MCP setup、短い時間差、似た prompt shape でも high creation が続くなら、異常として扱う価値があります。

## 経路ごとの証拠を混ぜない

同じ Claude Code 作業でも、数字は別々の契約から来ることがあります。subscription login、API key、Agent SDK、cloud provider、gateway はどれも usage や cost を表示し得ますが、同じメーターではありません。

| 経路 | 数字が意味し得るもの | 強い証拠 |
| --- | --- | --- |
| Claude subscription login | plan/seat usage、limit window、reset timing、included usage。 | Help Center の usage 説明、account status、`/status`、plan message。 |
| Claude API key | 従量課金 API token billing。 | Claude Console、Usage and Cost API、project billing settings。 |
| Agent SDK | SDK message 由来の usage と cost estimate。 | SDK fields と Console/Usage and Cost API の照合。 |
| Bedrock、Vertex、Foundry | provider 経由の model use、provider billing、cache support boundary。 | cloud provider invoice と route-specific logs。 |
| Gateway | gateway usage と upstream pass-through behavior。 | gateway logs と可能なら upstream billing。 |

[Claude Code costs](https://code.claude.com/docs/en/costs) と [Help Center usage article](https://support.claude.com/en/articles/14552983-models-usage-and-limits-in-claude-code) は、subscription usage と API billing を分けるために重要です。subscription limit message で API spend を証明しないこと。SDK estimate で subscription seat の請求を証明しないこと。

実際の症状が limit window の中断なら、[Claude Code の使用量と制限](https://blog.laozhang.ai/ja/posts/claude-code-usage-limit-issues) または [Claude Code rate limit reached](https://blog.laozhang.ai/ja/posts/claude-code-rate-limit-reached) を参照してください。cache math は入力側消費の説明であり、quota recovery 全体の代わりではありません。

## 修正の順序：小さく変えて次の turn で測る

![Claude Code cache miss の修正階段と support packet](https://blog.laozhang.ai/posts/ja/claude-code-cache-miss-token-costs/img/fix-ladder.webp)

一度の高コスト turn を見て、すぐに全体の作業設計を変える必要はありません。1 つずつ変え、次の似た turn で測ります。

1. **経路を特定する。** subscription usage、API key billing、SDK estimate、provider route、gateway route のどれか。
2. **cache fields を読む。** 数回の似た turn で `cache_creation_input_tokens` と `cache_read_input_tokens` を比較。
3. **invalidator を名付ける。** model、MCP、whole-tool denial、`/compact`、upgrade、provider、TTL、subagent、fork、worktree、directory scope。
4. **早い prefix を安定させる。** 同じ作業中に model や MCP setup を頻繁に変えない。
5. **無関係な仕事は `/clear` で分ける。** 関係ない context が早い位置に残るほど prefix は大きく不安定になります。
6. **`/compact` は自然な切れ目で使う。** 会話が大きすぎるときは有効ですが、cache miss への最初の反応ではありません。
7. **1-hour TTL は cadence で判断する。** write が高くなるため、後続 read が十分あるときだけ意味があります。
8. **次の似た turn を検証する。** 成功なら repeated creation が下がり、read が増えます。

同時に model 変更、MCP 削減、compact、gateway 変更をすると、下がった理由がわかりません。修正は小さく、証拠は同じ経路で比較します。

## 疑わしい spike の証拠セット

「cache bug かもしれない」という報告より、同じ経路と同じ context shape を比較できる証拠のほうが有用です。

| 証拠 | 重要な理由 |
| --- | --- |
| timestamp と timezone | usage record と invoice を合わせられます。 |
| Claude Code version | upgrade は prompt shape を変える可能性があります。 |
| model | model switch は高リスクの invalidator です。 |
| active route | subscription、API key、SDK、provider、gateway を混ぜません。 |
| MCP server list の前後 | connect/disconnect は早い prefix を変えます。 |
| tool permission changes | whole-tool denial は tool context を変えます。 |
| `/compact`、`/clear`、`/recap`、rewind history | conversation shape の解釈に関わります。 |
| `cache_creation_input_tokens` と `cache_read_input_tokens` | write/read の中核証拠です。 |
| 似た hit/miss turn の比較 | 単独スクリーンショットより強い証拠です。 |
| billing surface | Console、Usage and Cost API、provider invoice、subscription usage。 |

context change の直後に 1 回 write が出た程度では、bug と呼ぶには弱いです。stable route、stable model、stable MCP setup、短い時間差、似た input shape でも high creation が繰り返されるなら、support packet としてまとめる価値があります。

## よくある質問

### Claude Code の cache miss は別料金ですか？

いいえ。再利用できる prefix が cache read で安く読まれず、再処理または再書き込みされた状態として読むのが安全です。別料金名を探すより、token class と route を確認してください。

### なぜ 12.5x と言われますか？

Anthropic の現在の倍率では、5-minute cache write が 1.25x、cache read が 0.1x です。同じ token 量なら 1.25 / 0.1 = 12.5 になります。

### cache miss を証明するフィールドはどれですか？

`cache_creation_input_tokens` と `cache_read_input_tokens` から始めます。creation が高く read が低い場合、prefix が安く再利用されていない可能性があります。1 回より複数の似た turn の比較が重要です。

### `/compact` は token コストを下げますか？

場合によります。大きすぎる conversation を自然な境界で縮めるには役立ちますが、context を書き換えるため cache reuse を切ることもあります。

### 1-hour TTL は使うべきですか？

route が対応し、後続 read が高い write multiplier を回収できるときだけです。長い TTL は自動的に安くなる機能ではありません。

### `/cost` は Claude の請求書ですか？

いいえ。`/cost` や SDK cost fields は監視に便利な推定値です。最終証拠は Claude Console、Usage and Cost API、provider invoice、gateway record、または subscription usage surface です。

### いつ cache bug を疑えますか？

timestamp、version、model、route、MCP setup、permission changes、cache fields、似た hit/miss turn、billing surface が同じ経路でそろったあとです。それ以前は普通の invalidation や TTL expiry のほうがよくあります。

## 参考資料

本文で参照している外部ページを、登場順に並べています。最終更新日：2026-05-24。

- [Claude API pricing](https://platform.claude.com/docs/en/about-claude/pricing) (platform.claude.com)
- [Agent SDK cost tracking](https://code.claude.com/docs/en/agent-sdk/cost-tracking) (code.claude.com)
- [Claude Code prompt caching](https://code.claude.com/docs/en/prompt-caching) (code.claude.com)
- [Claude Code costs](https://code.claude.com/docs/en/costs) (code.claude.com)
- [Help Center usage article](https://support.claude.com/en/articles/14552983-models-usage-and-limits-in-claude-code) (support.claude.com)