2026年9月8日時点の結論。Claude Codeのトークン使用量は /usage のSessionブロックで確認でき、v2.1.251以降はそこに Prompt cache (main) 行が増えて、キャッシュから読めた入力トークンの割合・ミス回数・いまキャッシュが温かいかどうかまで1行で出る。消費を減らす本丸は「プロンプトを短く書くこと」ではなく、作業の途中でキャッシュを壊す操作をしないことだ。キャッシュ読み取りは素の入力の10分の1の単価で課金されるため、ヒット率が落ちるとそのまま請求に乗る。
Claude Codeはターンごとに会話の全履歴を送り直す。プロンプトキャッシュは、その「前回と同じ部分」をモデル側が再処理せずに済ませる仕組みで、Claude Codeは既定で有効にしている（How Claude Code uses prompt caching）。普段は意識しなくていい。問題は、キャッシュが効かなくなる操作がいくつもあり、そのどれもがコマンド1つで踏めることだ。
この記事の要点
- 確認場所：
/usageのSessionブロック。Prompt cache (main)行はv2.1.251以降。 - 原因特定：v2.1.260以降は直前のミスの推定原因を
likely cause: tool definitions changedのように行末に出す。 - 単価差：キャッシュ読み取りは素の入力の0.1倍（Claude Fable 5.1とClaude Mythos 5.1は0.025倍）。5分TTLの書き込みは1.25倍、1時間TTLは2倍。
- 対象読者：Claude Codeを毎日使う開発者、チームの利用量を見ているリード、Agent SDKで自動化を回している人。
- 今日やること：
claude --versionを確認し、作業中のセッションで/usageを開く。
/usage のSessionブロックで今の内訳を読む
トークン使用量の確認場所は /usage の一択でいい。Sessionブロックにそのセッションの累計が出る（Manage costs effectively）。
Usage by model 行で4種類のトークンを分ける
Usage by model 行は、モデルごとに入力・出力・cache read・cache writeを並べて出す。見るべきは金額よりも比率だ。cache readがcache writeより大きく育っていればキャッシュは効いている。逆にcache writeが毎ターン積み上がっていれば、どこかでプレフィックスが変わり続けている。
この金額はトークン数から定価で計算した推定値で、請求そのものではない。累計は /clear でリセットされる。
Prompt cache (main) 行を読む
メイン会話の最初のAPI応答が返ったあと、Sessionブロックに次の1行が足される。
Prompt cache (main): 14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)
| 表示 | 意味 | 判断 |
|---|---|---|
N requests |
メイン会話で記録したAPIリクエスト数 | 母数。サブエージェントの分は含まない |
NN% of input tokens from cache |
入力トークンのうちキャッシュから読めた割合 | 低いままなら原因を探す |
N misses |
キャッシュにあった内容を再処理したリクエスト数 | 1件ごとに再処理コストが乗る |
N expected rebuild |
圧縮やツール結果削除の直後に起きた作り直し | 仕様どおりの再構築でミスとは別枠 |
warm / cold |
いまのプレフィックスがTTL内かどうか | cold は次の1回が丸ごと再処理になる合図 |
likely cause: ... |
直前のミスの推定原因（v2.1.260以降） | ここが対処の入口 |
ミスの判定はしきい値で決まる。キャッシュから読めたはずの内容のうち5%を超え、かつ2,000トークン以上を再処理したリクエストがミスになる。圧縮やツール結果の削除で説明がつくものは expected rebuild に振り分けられるので、misses が増えているときだけ疑えばいい。
なぜキャッシュヒット率が請求額を決めるのか
「プロンプトを短くする」より先に効くのがキャッシュだ。理由は構造と単価の2つにある。
リクエストは3層のプレフィックスでできている
APIはリクエストの先頭（プレフィックス）を照合してキャッシュを当てる。照合は完全一致で、途中が1文字でも変われば、そこから後ろは全部再計算になる。Claude Codeはこれに合わせて、変わりにくいものを前に置く順序でリクエストを組み立てている。
| 層 | 中身 | 変わるとき |
|---|---|---|
| システムプロンプト | 中核の指示、ツール定義、出力スタイル | 読み込まれたツール定義の集合が変わる、Claude Codeを更新する |
| プロジェクトコンテキスト | CLAUDE.md、自動メモリ、スコープなしのルール | セッション開始時、/clear や /compact の後 |
| 会話 | 自分のメッセージ、応答、ツール結果 | 毎ターン |
会話層が伸びるだけなら上の2層はキャッシュに残る。逆にシステムプロンプトが変わると、その後ろに並ぶ全部が別プレフィックス扱いになる。プランモードやスキルの読み込みが会話メッセージとして追記される設計になっているのも、この前方一致を壊さないためだ。
単価は読み取りと書き込みで10倍以上違う
課金の倍率は公開されている（Prompt caching）。5分TTLの書き込みは素の入力の1.25倍、1時間TTLの書き込みは2倍、読み取りは0.1倍。Claude Fable 5.1とClaude Mythos 5.1だけは読み取りが0.025倍になる。100万トークンあたりの単価に直すと次のとおり。
| モデル | 素の入力 | 5分キャッシュ書き込み | 1時間キャッシュ書き込み | キャッシュ読み取り |
|---|---|---|---|---|
| Claude Fable 5.1 | 10ドル | 12.50ドル | 20ドル | 0.25ドル |
| Claude Opus 5 | 5ドル | 6.25ドル | 10ドル | 0.50ドル |
| Claude Sonnet 5 | 2ドル | 2.50ドル | 4ドル | 0.20ドル |
| Claude Haiku 4.5 | 1ドル | 1.25ドル | 2ドル | 0.10ドル |
試算例（実測値ではありません・前提と計算式を明示します）。Claude Sonnet 5で会話が100,000トークンまで育ち、そこから40往復したとする。出力トークンは差が出ないので除く。
- 全ターンがキャッシュに当たる場合：100,000 × 0.20 ÷ 1,000,000 = 0.02ドル／ターン、40ターンで0.8ドル
- 全ターンが素の入力になる場合：100,000 × 2.00 ÷ 1,000,000 = 0.20ドル／ターン、40ターンで8.0ドル
同じ作業で10倍違う。サブスクリプションで使っている場合は請求額ではなくプラン利用量に効く。上限に当たったときの動き方はClaudeCodeの「sessionlimit」対処法｜再開手順にまとめてある。
キャッシュを壊す操作と、壊さない操作
原因の候補は限られている。公式ドキュメントが無効化する操作と維持する操作を列挙しているので、likely cause と突き合わせれば大半は特定できる。
作業の途中で踏むと1ターン分の再処理が起きるもの
- モデルの切り替え：モデルごとにキャッシュが別。内容が同じでも全文が再処理になる。
opusplan設定はプランモードの出入りがそのまま切替になる。 - effortレベルの変更：多くのモデルで全文再処理。APIキーまたはClaudeサブスクリプションでClaude Fable 5.1を使う場合だけ、v2.1.260以降は維持される。
- fast modeを入れる：ヘッダーがキャッシュキーに含まれるため、オンにした後の最初のリクエストが再処理になる。会話につき1回で、序盤に入れるほど安い。
- MCPサーバーの接続・切断：ツール定義がプレフィックスに載っている場合のみ。ツール検索で遅延読み込みされる既定構成では影響しない。
- プラグインの有効化・無効化：MCPサーバーを提供するプラグインだけが上と同じ扱い。スキル、コマンド、エージェント、フック、テーマは追記されるだけで保たれる。
- ツール全体のdenyルール追加：
Bashのような素のツール名を拒否するとコンテキストから消えるため無効化。Bash(rm *)のようなスコープ付きは影響しない。 - 会話の圧縮：仕様として会話層を作り直す。手順はClaude Code /compact｜長時間開発の5手順を参照。
- 画像の蓄積：画像・PDFの上限に達すると古い分がまとめて外され、その位置から再処理される。
- Claude Codeの更新：システムプロンプトやツール定義が変わるため、更新後の最初のターンが再処理になる。長い会話を更新後に再開した場合が最も高くつく。
気にせず使ってよいもの
ファイルの編集、CLAUDE.mdの編集、出力スタイルの変更、権限モードの切り替え、スキルやコマンドの呼び出し、/recap、/rewind、サブエージェントの起動は、いずれもキャッシュを保つ。
ここに実務上の罠が1つある。CLAUDE.mdと出力スタイルは「キャッシュを壊さないかわりに、その場では反映もされない」。どちらもセッション開始時に読み込まれた版が使われ続け、新しい内容は次の /clear、/compact、再起動で載る。途中で書き換えて効かないと悩むのはこの挙動が理由だ。
やり直したいときは /compact より /rewind が安い。/rewind は既にキャッシュされている過去のプレフィックスまで切り戻すので、新しいプレフィックスを作り直す圧縮と違ってミスにならない。
TTLを5分と1時間のどちらにするか
キャッシュは無操作が続くと期限切れになる。TTLは5分と1時間の2種類で、Claude Codeはリクエストを2つのバケットに分けて選ぶ。
既定値は契約形態で変わる
| リクエストの種類 | サブスクリプション（プラン内利用） | 利用クレジット・APIキー・クラウド |
|---|---|---|
メイン会話（対話、-p、Agent SDKのターン） |
1時間 | 5分 |
| それ以外（サブエージェント、ワークフロー、フォーク、圧縮など） | 5分（サーバー側制御の一部ヘルパーのみ1時間） | 5分 |
プランの上限を超えて利用クレジットに入ると、メイン会話も5分に落ちる。ここで1時間を維持したい場合は明示的に指定する。
設定キーと優先順位
メイン会話は promptCacheTtl 設定または CLAUDE_CODE_PROMPT_CACHE_TTL 環境変数、それ以外は subagentPromptCacheTtl 設定または CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL で指定する。受け付ける値は 5m と 1h だけで、v2.1.242以降が必要だ（Settings reference）。
{
"promptCacheTtl": "1h",
"subagentPromptCacheTtl": "5m"
}
複数の指定が重なったときの優先順位は6段。FORCE_PROMPT_CACHING_5M=1、バケットの環境変数、バケットの設定、サブエージェントのfrontmatterの experimental.cacheTtl（v2.1.248以降）、ENABLE_PROMPT_CACHING_1H=1、最後に既定値の順だ。組織の管理設定で長いTTLが入っているときに手元だけ戻すなら FORCE_PROMPT_CACHING_5M=1 を使う。
1時間TTLは書き込み単価が2倍になるので常に得とは限らない。5分を超える中断が何度も入る使い方なら、そのたびの再処理を避けられる分で回収できる。
どちらで書かれたか確認する
実際にどのTTLで書き込まれたかは次のコマンドの結果に出る。1時間分は ephemeral_1h_input_tokens、5分分は ephemeral_5m_input_tokens に入る。
claude -p "hello" --output-format json
ステータスラインで hit_ratio と warm を常時表示する
/usage は都度開く必要がある。常時見るならステータスラインのスクリプトから同じ数字を読める。v2.1.251以降、入力JSONに prompt_cache オブジェクトが入る（Status line）。
使うフィールドを絞る
主なフィールドは warm（TTL内かどうか）、hit_ratio（キャッシュ読み取りが全入力トークンに占める割合、0から1）、misses、expected_rebuilds、ttl、expires_at、recache_tokens_if_cold（いま冷えた場合に次のリクエストが書き直すトークン数）。v2.1.260以降は last_miss_cause に tools_changed、system_prompt_changed、ttl_expired_5m、likely_server_side といった原因名が入る。
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
HIT=$(echo "$input" | jq -r 'if .prompt_cache.hit_ratio then (.prompt_cache.hit_ratio * 100 | floor) else "--" end')
WARM=$(echo "$input" | jq -r 'if .prompt_cache.warm then "warm" else "cold" end')
CAUSE=$(echo "$input" | jq -r '.prompt_cache.last_miss_cause.causes[0] // empty')
echo "[$MODEL] cache ${HIT}% ${WARM} ${CAUSE}"
prompt_cache はメイン会話の最初の応答が返るまで存在しないので、// で既定値を用意しておく。サブエージェントの分は集計に含まれない。
組織単位で見るならOpenTelemetry
エクスポーターがユーザー別・セッション別に cache_read_tokens と cache_creation_tokens を出す。上限設計まで含めた全社側の組み立てはClaude Code全社導入のコスト可視化・上限設計ガイドにまとめてある。
ケースパターン別に効きどころを見積もる
以下は公開仕様から導いた構成例で、特定企業の運用実績ではない。
1つのセッションを長く回す使い方
最も素直に効く。モデルとeffortをセッション冒頭で決め切り、/compact はタスクの切れ目に自分のタイミングで走らせる。自動圧縮がタスクの途中で発火すると、圧縮そのものより作業を中断された側の影響が大きい。
worktreeを分けて並行させる使い方
注意が要る。キャッシュのスコープは実質「1マシン1ディレクトリ」で、システムプロンプトに作業ディレクトリやプラットフォーム情報が埋まっているため、同一リポジトリのworktree同士でも互いのキャッシュには当たらない。逆に、同じディレクトリで並行して走らせたセッション同士は同じプレフィックスを読み合う。
自動化・ファンアウトで回す使い方
ワークフローのファンアウトでは、同じプレフィックスを持つエージェントのうち先頭以外を既定で最大5秒待たせ、先頭が書いたキャッシュを読ませる設計になっている。この待ち時間は CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS で調整でき、0 で無効化できる。
よくある失敗パターンと回避策
- ❌
Prompt cache (main)行が出ないので機能していないと判断する → ⭕ v2.1.251以降が必要。2026年9月8日時点のnpmレジストリではlatestが2.1.263に対しstableタグは2.1.236のままで、stableチャンネルで配っている組織にはこの行がまだ届かない。 - ❌ 会話が重くなったのでモデルを軽いものへ切り替える → ⭕ 切り替えた瞬間に全文が再処理される。切り替えるならタスクの切れ目か
/clearの直後にする。 - ❌ ゲートウェイ経由でヒット率が0のままなのを設定ミスと考える → ⭕ ゲートウェイが
cache_controlマーカーを落として成功を返すと、会話全体が毎ターン素の入力として課金される。caching_observedがfalseなら経路を疑う。 - ❌ とりあえず全部1時間TTLにする → ⭕ 書き込みが2倍になる。中断が5分未満の連続作業しかしないなら割高な書き込みだけを払う。
今日から実行するチェックリスト
claude --versionを確認する（Prompt cache (main)行はv2.1.251以降、likely causeはv2.1.260以降）。- 作業中のセッションで
/usageを開き、ヒット率・ミス回数・warm/coldを控える。 - ミスがあれば行末の
likely causeを読み、該当する操作をタスク中に行っていないか振り返る。 - モデルとeffortをセッション冒頭で固定する運用に変える。
- APIキーやクラウド経由なら、中断の入り方を見て
promptCacheTtlを決める。 - ステータスラインに
hit_ratioとwarmを出し、悪化にその場で気づける状態にする。
よくある質問
Claude Codeのトークン使用量はどこで確認できますか
/usage のSessionブロックです。モデルごとに入力・出力・cache read・cache writeが分かれて表示され、トークン数から定価で計算した推定コストも並びます。累計は /clear でリセットされます。
キャッシュヒット率はどのくらいあれば正常ですか
公式に基準値の記載はありません。判断材料になるのは水準よりも推移です。cache_write_tokens が毎ターン積み上がり続けている、misses が増え続けているときに likely cause を見て原因の操作を特定する、という読み方をします。
プロンプトを短くすればトークンは減りますか
減りますが効き方は限定的です。会話が育つとリクエストの大半は履歴で占められ、その履歴はキャッシュ読み取りとして0.1倍で課金されます。長い会話ではヒット率のほうが支配的になります。
サブエージェントは親のキャッシュを使えますか
使えません。自分のシステムプロンプトとツールセットで別の会話を始めるため、最初のリクエストは親のキャッシュに当たりません。例外はフォークで、親の履歴をそのまま引き継ぐため親のキャッシュを読みます。
Claude Fable 5.1に切り替えるとキャッシュ費用はどうなりますか
キャッシュ読み取りが素の入力の0.025倍で、100万トークンあたり0.25ドルになります。他モデルの0.1倍より安い設定です。切り替えの手順と料金はClaude CodeのFable 5.1｜切替と料金で扱っています。
参考・出典
- Anthropic「How Claude Code uses prompt caching」（無効化する操作・維持する操作・TTL・スコープ）
- Anthropic「Manage costs effectively」（
/usageのSessionブロックとPrompt cache (main)行） - Anthropic「Status line」（
prompt_cacheオブジェクトのフィールド定義） - Anthropic「Settings reference」／「Environment variables」（TTLの設定キーと環境変数）
- Anthropic「Prompt caching」（Claude API公式・単価倍率とモデル別価格表）
- npm「@anthropic-ai/claude-code」（2026年9月8日時点のdist-tags）
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』『Claude仕事術』（SBクリエイティブ・シリーズ累計50,000部突破）。SBクリエイティブ「ビジネス+IT」ほかで生成AI連載を執筆。
