Claude Codeのキャッシュ時間は1時間か5分か — プロンプトキャッシュと利用上限

Claude Codeのプロンプトキャッシュが持つ時間(TTL)は、Claudeサブスクのプラン内消費ではメイン会話が1時間、APIキー・クラウド経由や使用量クレジット消費中は5分です。Claude Codeは会話の全履歴を毎ターン送り直します。プロンプトキャッシュが効いていれば、その再送分は安いキャッシュ読み取りの単価で処理されます。ただしキャッシュはモデル切り替えなどの操作で壊れ、壊れた直後の1ターンは全文を再処理します。キャッシュだけを消す専用コマンドはなく、/clearか/compactで組み直すと古いキャッシュは使われなくなります。上限の減りが速いと感じたら、まず/usageのPrompt cache (main)行で、壊れているのか、アイドル中に動いているのか、TTL(有効期間)が短くなっているのかを切り分けます。

プロンプトキャッシュは利用上限の消費にどう効くか

Claude Codeは新しいメッセージを送るたびに、システムプロンプト・プロジェクトコンテキスト・それまでの会話履歴をまるごと1つのリクエストとして送信します。新規部分は末尾に追記されるだけなので、直前のリクエストと先頭が一致する部分(プレフィックス)は、API側が最近処理した内容として読み直せます。一致は厳密で、プレフィックスの途中が1か所変わると、そこから後ろはすべて再計算になります。ファイル単位・区間単位のキャッシュはありません。

読み取り分の単価は通常の入力トークンのおよそ10%です(Opus 5.5とSonnet 5.5は5%、Fable 5.1・Mythos 5.1は2.5%)。一方で、プランの上限にどの比率で換算されるかは、確認した公式ページには書かれていません。書かれているのは逆側の事実です。キャッシュがあっても、一日開いた長い会話では一言の質問で会話全体ぶんの消費が出ます。キャッシュが効くのは「全文を新規に処理する」より安いという意味で、消費ゼロではありません。

ここで扱うのは会話プレフィックスを再利用するプロンプトキャッシュです。WebFetchが取得したページ自体は15分の別キャッシュで管理され、独立した仕組みです(Claude Code WebFetchのキャッシュとタイムアウト)。Anthropic API全般でのコスト削減の基本原理はAnthropic APIのPrompt Cachingを理解するにあります。

キャッシュの時間切れと「warm」表示の読み方

キャッシュは最後のリクエストから、設定されたTTLのあいだ生き続けます。リクエストが当たるたびにタイマーは戻るので、作業を続けているかぎり冷えません。TTLを過ぎた最初のターンだけが、全文を再処理して書き直す重いターンになります。

2026年3月に1時間TTLが5分へ切り替わった経緯は、Claude CodeのキャッシュTTLが1時間から5分に短縮された問題にまとめています。

ステータスラインや/usageに出るwarmは、いまのプレフィックスがTTL内にあるという意味です。coldなら次のリクエストで書き直しが走ります。残り時間を数えるより、ttlが1hか5mかを先に見るほうが早く判断できます。

キャッシュだけを消すコマンドは、プロンプトキャッシュの解説ページに載っていません。/clearと/compactはその時点でキャッシュを組み直す操作で、古いプレフィックスは使われなくなります。意図してキャッシュを切りたいのでなければ、/clearは新しい作業を始めるときに使います。

何がキャッシュを壊し、消費を増やすか

壊れると次のリクエストは会話全体を再処理するため、そのターンだけ通常単価の消費に戻ります。多くの操作は「システムプロンプトかツール定義が変わるか」で決まり、条件しだいで壊れたり壊れなかったりします。

モデル切り替えには見落としやすい経路が3つあります。frontmatterにmodelを書いたスキルやコマンドは、セッションのモデルと違えばそのターンが切り替えになります。Fable系・Opus 5.5・Sonnet 5.5・Opus 5では、安全分類器に引っかかったリクエストが自動フォールバックで別モデルに再実行される場合も切り替えです。opusplanはプランモードの出入りごとにOpusとSonnetを行き来します。

ターミナルで/modelを実行すると、キャッシュがまだ温かく、新しいモデルが直前の応答を返したモデルと違うときだけ確認が出ます。TTLを過ぎていれば確認なしで切り替わります(v2.1.238以降。それ以前はTTL後も確認が出ていました)。確認が出たときは、その1ターンぶんの再処理が発生するという意味です。

次の操作は、会話の末尾に追記するだけか会話自体に触れないため、キャッシュを維持します。

• ファイルの編集(変更は<system-reminder>として末尾に追記される)
• CLAUDE.mdの編集(次の/clear・/compact・再起動まで反映されない)
• 出力スタイルの変更(v2.1.251以降は次のメッセージから反映される)
• 権限モードの切り替え(opusplanのプランモードを除く)
• スキルやコマンドの呼び出し(frontmatterで別モデルを指定した場合を除く)
• /recap
• /rewind(すでにキャッシュ済みのプレフィックスまで巻き戻すだけなので、むしろ安全な操作です)
• サブエージェントの起動

アイドル中でも上限を消費する要因

会話を開いたまま何も入力していなくても、Claude Codeが新しいターンを発生させることがあります。キャッシュが冷えていれば、そのターンは全文を再処理します。

この4つに加え、プロンプト候補(次に打つ文の提案)もモデルへリクエストを送ります。会話のキャッシュを再利用するので大半は読み取りです。キャッシュが冷えているときと、アカウントが上限に近いときは、候補の生成自体が見送られます(/configのPrompt suggestionsで止められます)。

Pro・Maxの利用上限とTTLの関係

rate_limitsオブジェクト(5時間枠・週次上限。Claude appsゲートウェイ経由では支出上限)は、誰にでも見えるわけではありません。Claude.ai Pro・Maxのサブスクリプション利用者か、支出上限を設定されたClaude appsゲートウェイ経由でだけ現れます。5時間枠と週次上限の基本的な仕組みはClaude Pro制限の仕組みが扱うので、ここではキャッシュのTTLがその消費とどう結びつくかに絞ります。

TTLは会話ごとではなく、リクエストの種類ごとに2つのバケットへ分かれます。メイン会話は対話ターン・-p実行・Agent SDKで、それ以外はサブエージェント・ワークフロー・compaction・セッションタイトルなどです。

5時間枠か週次上限を使い切って使用量クレジットへ入ると、Claude Codeはメイン会話のTTLを自動的に5分へ落とします。離席を挟んでも壊れにくかったキャッシュが、上限超過を境に壊れやすくなるということです。ステータスラインのttlが5mに変われば見分けられます。

上限を超えたあとは、5分を超える離席を挟むたびにキャッシュが冷え、戻った最初のターンで全文を再処理します。/compactを使うなら、TTLを過ぎて冷える前のほうが要約リクエスト自体を安く済ませられます。

上限の減りが速いときの切り分け

観測手段は/usageとステータスラインの2つです。

/usageのPrompt cache (main)行は、たとえば次のように出ます(公式ドキュメントの例)。

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)

「miss」は、キャッシュから読めたはずの量の5%超かつ2,000トークン以上を再処理したリクエストです。/compactやツール結果のクリアが原因の再構築は「expected rebuild」として別に数えます。この行はメイン会話だけが対象で、サブエージェントの消費は含みません。/clearでセッションブロックごとリセットされます。

同じ数値はステータスラインのprompt_cacheオブジェクトにも入ります(v2.1.251以降)。直近リクエストの内訳を読むcurrent_usageはcurrent_usageで直近リクエストの内訳を読む方法にあります。

warm・ttl・hit_ratio・missesだけを1行に出すステータスラインは、次のスクリプトで組めます。公式ドキュメントのprompt_cacheのサンプルJSONを標準入力に渡して、出力を確かめました(実際のセッションでの計測値ではありません)。

#!/bin/bash
input=$(cat)
echo "$input" | jq -r '.prompt_cache
  | if . == null then "cache: -"
    else "cache " + (if .warm then "warm" else "cold" end)
      + " " + (.ttl // "?")
      + " hit " + (((.hit_ratio // 0) * 100 | floor | tostring)) + "%"
      + " miss " + (.misses | tostring)
    end'

echo '{"prompt_cache":{"warm":true,"ttl":"1h","hit_ratio":0.91,"misses":2}}' | ./statusline.sh

cache warm 1h hit 91% miss 2

prompt_cacheがまだ無いセッション(初回応答前)ではcache: -を返します。

キャッシュの書き込みにどのTTLが使われたかは、次のコマンドで確認できます。

claude -p "hello" --output-format json | jq '.usage.cache_creation'

ephemeral_1h_input_tokensとephemeral_5m_input_tokensのどちらにキャッシュ書き込みが計上されたかが分かります。なお、/usageのプラン消費内訳には「Behavior flags」が出ることがあります。長いコンテキストやキャッシュミスのような挙動が直近使用量の10%以上を占めると表示されます(Pro・Max・Team・Enterpriseプランの場合)。利用上限の警告メッセージそのものの見分け方はClaude Codeの利用上限にまとめてあります。

TTLを自分で選ぶ設定

TTLは明示的に設定できます(v2.1.242以降)。APIキーやクラウドプロバイダー経由でメイン会話を1時間キャッシュにしたい場合や、使用量クレジットに入っても1時間TTLを維持したい場合に使います。値は5mか1hだけで、それ以外はClaude Codeが無視します。

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "1h"
}

promptCacheTtlはメイン会話、subagentPromptCacheTtlはサブエージェントなどそれ以外のバケットに効きます。片方だけ設定すると、もう一方は既定のままです。環境変数でも同じ指定ができます。

CLAUDE_CODE_PROMPT_CACHE_TTL=1h claude

サブエージェント側はCLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTLです。複数の指定が重なったときの優先順位は次のとおりで、上にあるものほど強く効きます。

1. FORCE_PROMPT_CACHING_5M=1(両バケットを強制的に5分に)
2. 各バケットの環境変数
3. 各バケットの設定
4. サブエージェントのexperimental.cacheTtlフロントマター(v2.1.248以降)。ただしサブスクリプションが使用量クレジットを消費中は、ここに1hを指定してもClaude Codeは無視します
5. ENABLE_PROMPT_CACHING_1H=1(両バケットを1時間に)
6. リクエストの種類ごとの既定値

FORCE_PROMPT_CACHING_5M=1は、キャッシュの挙動を調べるときや、管理設定で長いTTLが強制されている環境で5分と比べたいときに使います。

キャッシュの再利用を上げる別の入口として、claude --helpには次のフラグがあります(v2.1.285で確認)。

--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)

作業ディレクトリやgitステータスをシステムプロンプトから外し、複数のユーザー・マシンで同じプレフィックスを共有しやすくするフラグです。1人で対話的に使う場合の節約策ではなく、同じタスクを多数のマシンで回す運用向けです。

よくあるつまずき

--resumeで古いセッションを再開すると、既定では元のセッションが使っていたシステムプロンプトを保ちます。そのため、Claude Codeをアップグレードしていても、再開しただけでは新しいプロンプトへの切り替えによる全損にはなりません。切り替わるのは会話を/compactしたとき(または新しい会話)で、--append-system-promptの内容を変えて再開した場合も同じです。長い放置後の再開で重くなる主因は、TTLを過ぎて読み取れるキャッシュが残っていないことです。Pro・Maxプランでは、大きなセッションを長い休憩後に再開しようとすると要約からの再開を提案されるので、全履歴を持ち込まずに済みます。

サブエージェントとワークフローのファンアウトはメイン会話のTTLバケットの外にあり、サブスクリプションでも既定は5分です。サブエージェントは自分のシステムプロンプトとツールで別の会話を始めるため、最初のリクエストで親のキャッシュは読めません。親のプレフィックスは影響を受けません。ファンアウト内で同じプレフィックスを持つエージェント同士がキャッシュを共有できる条件はClaude Codeワークフローのプロンプトキャッシュの効き方で扱っています。

git worktreeは同じリポジトリでも作業ディレクトリが別なので、それぞれが独立にキャッシュを温め直します。システムプロンプトに自動メモリのパスが、会話の冒頭に作業ディレクトリ・プラットフォーム・シェル・OSの情報が入るためです。同じディレクトリで並列に開いた複数セッションはキャッシュを共有できますが、順番に開くセッション同士は、起動時のgitステータス(ブランチと直近コミット)が一致するときしか共有できません。

プロキシやLLMゲートウェイ経由の場合は、cache_controlマーカーの扱いで結果が変わります。マーカーを削除したまま成功を返すゲートウェイでは、会話履歴全体が毎ターン未キャッシュの入力として課金されます。ステータスラインのcaching_observedがfalseなら、キャッシュが無効か、プロバイダーやゲートウェイがキャッシュのトークン数を返していない状態です。

まとめ

使用量クレジットに入る使い方や、APIキー・クラウド経由で離席を挟む使い方なら、promptCacheTtlで1時間を選ぶかどうかが分かれ目です。数分おきに操作が続く短時間の作業なら、既定の5分のままで足ります。