Claudeのプロンプトキャッシュの仕組み — warmの意味とTTL、課金形態ごとの違い

Claudeのプロンプトキャッシュとは — 仕組みは1つ、効き方は2つ

プロンプトキャッシュは、直前のリクエストと先頭が一致する部分(プレフィックス)を再処理せず、キャッシュから読み直す仕組みです。一致は完全一致で、プレフィックスの途中が1か所でも変わると、それ以降はすべて再計算されます。ファイル単位や区間単位のキャッシュはありません。

キャッシュが「温まっている(warm)」とは、最後のリクエストからTTL(有効期間)が切れていない状態です。APIの既定は5分、サブスクのClaude Codeはメインの会話が1時間です。

仕組みそのものはAPIでもサブスクリプションでも同じです。違うのは、節約が請求書の単価に出るか、利用上限の消費として出るかという一点です。APIキーで直接叩く場合、キャッシュの節約はトークン単価に反映されます。Claude Codeをサブスクリプションで使う場合、単価は表に出ず、5時間枠と週次上限の減り方として現れます。

キャッシュのコード実装はAnthropic APIのPrompt Cachingを理解する、Claude Codeの利用上限への効き方の数値はプロンプトキャッシュはClaude Codeの利用上限をどう軽くするかに詳しくあります。ここでは、キャッシュが効いていないと感じたときの切り分けを軸に、課金形態ごとの違いを見ていきます。

キャッシュが効かない・すぐ切れると感じたときの切り分け

症状が「請求が下がらない」でも「離席から戻ると遅い」でも、確認する順序は同じです。上から順に当てはめると原因を絞れます。

API課金でのプロンプトキャッシュ — 単価そのものが変わる

APIキーでの呼び出しは、キャッシュの読み書きがトークン単価の倍率として請求に乗ります。書き込みは通常の入力より高く、読み取りは大幅に安くなります。具体的な倍率は次の表のとおりです。

Claude Fable 5.1のキャッシュ読み取り$0.25は、0.025倍が実額でいくらになるかの具体例です。

最小トークン数はモデルで違います。Claude Fable 5.1・Mythos 5.1・Opus 5.5・Opus 5・Sonnet 5.5は512トークン、Sonnet 5は1,024トークン、Claude Opus 4.6と4.5、Haiku 4.5は4,096トークンです。短いシステムプロンプトだけでキャッシュが効かないなら、まずこの下限を疑うのが早道です。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {"type": "text", "text": "長いシステムプロンプト..."},
      {"type": "text", "text": "固定コンテキスト", "cache_control": {"type": "ephemeral"}}
    ],
    "messages": [{"role": "user", "content": "質問文"}]
  }'

cache_controlをどのブロックに置くかで、キャッシュされる範囲が決まります(置かずに済む自動プロンプトキャッシュは多ターン会話でどう動くかも参照)。既定のTTLは5分で、キャッシュを使うたびに無料で延長されます。会話の間隔が5分を超えて空くなら、ttl: "1h"の1時間キャッシュに切り替える判断になります。事前に温めておきたい場合はプロンプトキャッシュの事前ウォームアップをmax_tokens=0で行うが参考になります。

置き場所には落とし穴があります。書き込みが起きるのはブレークポイントだけで、その手前の安定した部分を後から探して書き込んではくれません。タイムスタンプのように毎回変わるブロックの末尾にcache_controlを置くと、毎回書き込みだけが発生して読み取りは一度も起きません。ブレークポイントは、リクエスト間で内容が同じ最後のブロックに置きます。

また、ブレークポイントから遡って探す範囲は20ブロックまでです。長い会話でブレークポイントが前回の書き込み位置から20ブロック以上進むと、既存のキャッシュが見つからなくなります。その場合は、手前にもう1つブレークポイントを置いて書き込みを積んでおきます。

1時間TTLと5分TTLは同一リクエスト内で併用できますが、1時間TTLのエントリは5分TTLより前に置く必要があります。長期固定のシステムプロンプトを1時間、ターンごとに変わる会話履歴を5分にする構成が典型です。

サブスクリプションでのプロンプトキャッシュ — TTLの既定値が変わる

Claude Codeは会話の全履歴を毎ターン送り直します。キャッシュが効いていれば、その再送分は読み取り単価で処理され、5時間枠と週次上限の消費もその分軽くなります。ただし、履歴が長ければ短い質問でも上限の消費は大きくなります。Claude Codeの公式ドキュメントも、一日開いたセッションでは1行の質問が会話全体分の使用量を引くと説明しています。

API課金にはない挙動が1つあります。既定のTTLが課金形態で変わることです。

プラン枠を使い切って使用量クレジット(usage credits)に切り替わると、課金が発生する状態になるため、メインの会話も5分TTLに落ちます。プラン枠の範囲内なら、離席しても1時間はキャッシュが生きます。使用量クレジットに入ると、同じ離席が5分で切れ、次のメッセージが会話全体を再処理する重いターンになります。

TTLは自分で指定できます。指定できる値は5mと1hだけです(v2.1.242以降)。

複数の指定が重なったときの優先順は、FORCE_PROMPT_CACHING_5M=1、環境変数、設定、サブエージェントのcacheTtl(v2.1.248以降)、ENABLE_PROMPT_CACHING_1H=1、既定値の順です。APIキーでサインインしていて1時間を維持したい場合は、promptCacheTtlを1hにします。ただし、サブエージェントなどの別枠は、そちらにも指定しない限り5分のままです。4番目のサブエージェントのcacheTtlは、使用量クレジットを使っている間は1hが無視されます。

どのTTLで書き込まれたかは、claude -p "hello" --output-format jsonの結果のusage.cache_creationで確認できます。1時間の書き込みはephemeral_1h_input_tokens、5分の書き込みはephemeral_5m_input_tokensに出ます。

サブスクの節でここまで見てきた挙動は、Claude Codeのドキュメントに書かれたものです。claude.aiのWebやアプリでのTTLや上限への効き方は、確認できた一次ソースにないため、この記事では断定しません。

キャッシュがwarmとは — 切れる条件と1時間への切り替え

warmは、キャッシュにヒットするたびにタイマーが延びる状態を指します。使い続けている間は温まったままで、TTLを超えて空くと次のリクエストが全入力を再計算し、キャッシュを作り直します。離席後の最初のターンだけ遅いのは、このためです。

1時間TTLを使う方法は課金形態で異なります。サブスクのプラン枠内なら、メインの会話は何もしなくても1時間です。APIキーやクラウド経由でClaude Codeを使うなら、promptCacheTtlを1hにするか、ENABLE_PROMPT_CACHING_1H=1を設定します。後者はメインの会話とサブエージェントなどの両方に1時間を要求します。

1時間TTLは5分TTLよりキャッシュの書き込み単価が高くなります。5分以上空かない短い作業では、長い有効期間が使われないまま割高になります。

/usageの行で、キャッシュが温まっているか確かめる

/usageのセッションブロックには、メインの会話の最初の応答のあとにPrompt cache (main)行が加わります(v2.1.251以降)。

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)

ミスと数えられるのは、読めたはずの入力のうち5%を超え、かつ2,000トークン以上を再処理したリクエストです。それ未満の再処理は数えません。圧縮やツール結果の削除による想定内の再構築は、ミスとは別にexpected rebuildとして数えます。ミスの原因が特定できるとlikely cause: tool definitions changedのように原因候補が付きます(v2.1.260以降)。この行が数えるのはメインの会話だけで、サブエージェントは含みません。

warm (1h TTL...)の表示は、いまのTTLの手がかりになります。使用量クレジットに切り替わっていれば、5分に変わります。ミスの原因をさらに切り分ける方法はCache diagnosticsでキャッシュミスの原因を特定するにあります。

Claude Codeでキャッシュが壊れる操作と、壊れない操作

サブスク利用者が最適化する対象は単価ではなく、何がキャッシュを壊して上限の消費を増やすかです。壊れる操作は、次の1ターンだけ会話全体を再処理させます。

/compactと、Claude Codeのアップグレードは、上の2つの列に収まりません。/compactは会話のキャッシュを作り直しますが、作り直すのは短い要約の分だけです。アップグレードはセッション途中では適用されず、再起動後の最初の会話がキャッシュを一から作ります。

「壊れる」側のeffort変更は、モデルで扱いが分かれます。Opus 5.5・Sonnet 5.5・Fable 5.1をAPIキーかサブスクで使う場合は、effortを変えてもキャッシュが保たれ、確認なしで反映されます。Bedrock・Google CloudのAgent Platform・Claude apps gatewayでは、この例外は当たりません。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定した場合や、組織がHIPAA構成の場合も同様です。v2.1.260より前は、Fable 5.1でも壊れていました。

モデル切替のときは、キャッシュが温かい間だけ確認が出ます。温かい期間は、Claude Codeが最後にリクエストを送ってからTTL1つ分です。TTLが過ぎると確認なしで切り替わります。v2.1.238より前は、期限切れでも確認が出ていました。

fast modeが壊すのは、リクエストヘッダーがキャッシュキーの一部だからです。会話で初めてオンにした最初のリクエストだけが全損で、あとはオフにしても再びオンにしても保たれます。/clearと/compactは、この状態をリセットします。

サブエージェントは、親とは別のシステムプロンプトとツール構成で新しい会話を始めるので、最初のリクエストで親のキャッシュを読めません。親のキャッシュは影響を受けません。メインの会話と別枠のため、プラン枠の内側でも既定は5分TTLです。長いサブエージェント処理を挟むワークフローでは、この5分だけ先に切れることがあります。フォーク(会話を引き継ぐ分岐)は、親のシステムプロンプトとツールと履歴をそのまま引き継ぐので、最初のリクエストから親のキャッシュを読めます。

キャッシュはどこまで共有されるか

Claude Codeのキャッシュは、実質的に1台のマシンと1つのディレクトリに限られます。システムプロンプトに自動メモリのパスが入り、会話の冒頭に作業ディレクトリ・プラットフォーム・シェル・OSのバージョンが載るためです。ディレクトリが違う2つのセッションは、別々のプレフィックスを作り、互いのキャッシュを読みません。

同じディレクトリで並列に走らせたセッションは、一致するプレフィックスを作るので、互いのキャッシュを読みます。順番に走らせるセッションは、起動時のgit statusのスナップショットが一致するときだけ共有されます。会話にブランチと直近のコミットが入るからです。

下の基盤になるAPIのキャッシュは、もっと広く共有されます。組織のあいだは分離され、プロバイダーによってはワークスペース間も分離されます。その範囲の内側では、モデルとプレフィックスが同じ2つのリクエストが同じキャッシュを読みます。

手元のclaude(v2.1.285で確認)には、この共有を広げる起動オプションがあります。changelogでは、print mode(-p)向けに追加されたオプションとして初出です。対話モードでの効き方は、確認できた一次ソースにありません。

claude --help

  --exclude-dynamic-system-prompt-sections
      Move per-machine sections (cwd, env info, memory paths, git status) from
      the system prompt into the first user message. Improves cross-user
      prompt-cache reuse. Only applies with the default system prompt (ignored
      with --system-prompt). (default: false)

cwd・環境情報・メモリのパス・git statusといったマシンごとの部分を、システムプロンプトから最初のユーザーメッセージへ移します。同じシステムプロンプトを複数のユーザーやマシンで共有するとき、キャッシュを効かせやすくするための指定です。既定では無効です。

ゲートウェイやクラウド経由だと何が変わるか

キャッシュの実体は、モデルを提供しているインフラ側にあります。APIキー・Claudeサブスクリプション・Claude Platform on AWSならAnthropicの側、BedrockとGoogle CloudのAgent Platformならクラウドプロバイダーの側です。Microsoft Foundryはデプロイのホスティング方式で変わります。

ANTHROPIC_BASE_URLやLLMゲートウェイを経由する場合は、ゲートウェイがcache_controlのマーカーをどう扱うかで結果が分かれます。

• そのまま転送する: プロバイダー本来のエンドポイントと同じようにキャッシュされる
• cache_controlを名指しした400エラーで拒否する: Claude Codeがマーカーを最後の会話メッセージに移して再送し、その会話の残りでもそこに置く。システムプロンプトのブロックは未キャッシュの入力として課金され、会話はキャッシュされる
• 成功を返しつつマーカーを黙って消す: 会話履歴のすべてが毎ターン未キャッシュの入力として課金される

3つ目は、エラーが出ないぶん気づきにくい型です。ブロック形式のシステムプロンプトを単なる文字列に変換するゲートウェイも、同じようにマーカーを落とします。Prompt cache (main)行は各プロバイダーとゲートウェイで動くので、ヒット率が極端に低いときはここから疑えます。Bedrockではモデルごとにキャッシュ対応・最小長・1時間TTLの可否が違うため、キャッシュのトークン数が0のままなら、AWS側の対応表を確認します。

API利用者とサブスク利用者、何を最適化するか

取り違えると空回りします。API向けの助言(TTLを自分で選ぶ)をサブスクの日常利用に持ち込んでも、既定で1時間なので効果は薄く、逆にサブスク向けの助言(操作を避ける)をAPI実装に持ち込んでも、単価設計の代わりにはなりません。プランの枠と使用量クレジットの関係はClaude料金プラン比較にまとめてあります。

まとめ

プロンプトキャッシュは、書き込み・読み取り・TTLの3変数で決まり、その効き方は「いま請求のどの側にいるか」で変わります。自分がどちら側にいるかは、APIならレスポンスのusage、Claude Codeなら/usageのPrompt cache (main)行のTTL表示で確かめられます。効きが悪いときは、まず操作(モデル切替など)、次にTTL、最後にゲートウェイの順で疑うと絞り込みやすくなります。