Claude CodeのキャッシュTTLは5分か1時間か — 短縮の経緯と固定法

Claude Codeのキャッシュ時間(TTL)は、Claudeのサブスクリプションでプラン利用枠内の主会話なら1時間です。サブエージェントと、APIキー・クラウド経由のリクエストは5分です。5分で切れる場合は、promptCacheTtlを1hにすると主会話を1時間へ伸ばせます。3月の切り替わりの経緯は次の節から、固定の手順は「TTLを確かめて固定する手順」にあります。10月中旬からは、サブスクリプションの対話セッションだけが5分で書き込まれる事象も報告されています(「10月に再発した対話セッションだけの5分書き込み」の節)。

何が起きたか — 12万件のAPI呼び出しが示した切り替わり

2026年4月、あるユーザーがGitHub issue #46829で、Claude Codeのプロンプトキャッシュの生存時間(TTL)が2026年3月上旬を境に1時間から5分へ静かに切り替わったと報告しました。根拠は自分の~/.claude/projects/配下のセッションログをLinux機とWindows機の2台・異なるアカウントで解析した実データです。各レスポンスのusage.cache_creationにはephemeral_5m_input_tokensとephemeral_1h_input_tokensの内訳が含まれるため、どちらのTTLで書き込まれたかがリクエスト単位で判別できます。

分析対象は2026年1月11日から4月11日までの119,866件のAPI呼び出しです。切り替わりは4つのフェーズに分かれて見えました。

クライアントのバージョンや使い方は変えていないため、TTLの選択はサーバー側の設定によるものだと投稿者は分析しています。

コストとクォータへの実際の影響

投稿者は、公式料金に基づいて作った料金表(4月9日更新)で、実際の支払額と「もし1時間TTLのままだったら」の想定額を月別に比較しています。以下はSonnet 4.6の単価で計算した表です。

1時間TTLで運用できていた2月だけが無駄1.1%とほぼゼロで、3月は25.9%、4月も14.8%の過払いが続いています。Opus 4.6の単価で計算し直しても、無駄の割合は同じ17.1%です(合計は$9,268.97に対し$7,687.17)。モデルの単価差ではなく、キャッシュのTTL構成比そのものが無駄を決めていたことになります。

無駄が膨らむ仕組みは単価を並べると見えます。issueが使った単価はSonnet 4.6でキャッシュ読み取りが$0.30/MTok、5分書き込みが$3.75/MTok、1時間書き込みが$6.00/MTokです。同じ内容を5分TTLで書き、5分を超えて1時間以内に戻ると、書き直しで$3.75をもう一度払い、合計は$7.50になります。1時間TTLなら$6.00の書き込みに読み取り$0.30が加わるだけで、合計は$6.30です。

サブスクリプションプランは金額だけでなく利用枠(クォータ)でも制限されるため、影響はコストだけに留まりません。投稿者は2026年3月以降に5時間の利用枠を初めて使い切ったと報告しています。キャッシュの書き込みトークンは満額でクォータに計上される一方、読み取り分の係数は別issue(#45756)で検証中とされ、5分TTLへの切り替わりが消費を押し上げた最有力の説明として挙げられていました。

issueのコメント — 回帰ではなく用途別選択という説明

issueには、3月6日の変更は実在し意図的だが、回帰ではなく進行中のキャッシュ最適化の一部だというコメントが付きました。コメントしたのはリポジトリに権限を持たない一般ユーザーとして記録されたアカウントです。コメントの2分前に別のアカウントがassigneeに設定され、コメントの9分後(UTCで4月12日10時15分)にissueは「not planned」でクローズされました。コメントの要点は次の4つです。

1. 変更の有無: 3月6日に変更があった。日付の特定は正しい
2. 意図したTTL: リクエストごとに再利用パターンを予測して選ぶ設計で、単一のグローバルな既定値は元々存在しない
3. 1時間への統一: 全部のリクエストを1時間TTLにすると、1回しか使われないキャッシュでは書き込み単価(基本入力の約2倍と1.25倍、つまり約1.6倍)がそのまま乗るため総コストが増える。グローバルな切り替えは予定していない
4. クォータ換算: cache read側の係数は別issue(#45756)で追って回答する

同コメントは、プランの利用枠を使い切って超過利用に切り替わったセッションが、セッション終了までずっと5分TTLに固着してしまうクライアント側の不具合をv2.1.90で修正済みとも述べています。

別のユーザーが、UK・ドイツの2拠点・約40.7万ターン分の独自データでこの説明を検証しています。その集計が、リクエストごとの選択という説明を裏づけています。

3月6日以降は、サブエージェントのほうがメイン会話より先に、かつ完全に5分へ移っています。再利用されにくい一回きりの文脈を安い書き込みに寄せるという説明と整合する動きです。4月1日以降にメイン会話の比率が0〜6%へ戻る点は、同日付のv2.1.90の修正と時期が重なります。同じデータは、Vertex経由の課金では35,000ターンすべてが5分TTLだったことも示しています。Vertex AI向けの自動キャッシュ対応は当時「後日提供予定」とされ、課金経路によってキャッシュの挙動そのものが違う状態が別に存在していました。

「最適化」の裏で起きていた個別のバグ

リクエストごとに選ぶ設計という説明の一方で、公式changelogには「1時間TTLが通知なく5分に落ちていた」個別の不具合修正がこの後2回登場します。同じ症状に見えても、発生源は別々です。

issue提出(4月12日)からわずか2日後のv2.1.108で、コメントが「予定していない」と述べた全体の切り替えとは別に、1時間TTLを選べる手段が配られた形です。ただし最初のオプトインは、Bedrock・Vertexではv2.1.132まで400エラーの原因になっていました。さらにv2.1.129でも同種の不具合が別途見つかり、4月14日から5月6日までの3週間に「1時間TTLが気づかないうちに5分へ切り替わる」系の修正が2種類出たことになります。

同じ時期、--print --resumeのヘッドレス運用でもキャッシュが効かなくなる回帰が見つかりました。詳細は--print --resumeのキャッシュ回帰記事にあります。

10月に再発した対話セッションだけの5分書き込み

3月の件とは別の事象です。2026年10月12日18時18分(UTC)ごろから、サブスクリプションの対話セッションだけが主会話のキャッシュを5分で書く事象がGitHub issue #101685に報告されています。issueはopenのままで、担当者の割り当ても修正版の告知もありません。

投稿者の手元のセッションログでは、症状は次のように分かれていました。

環境変数・設定は何も入れておらず、プランの利用上限にも届いていない状態です。利用量クレジットを組織側で無効にしても変わらないため、利用量クレジットへ切り替わったときに5分へ落ちる既定の挙動(「TTLはどう決まるか」の節)とは別の原因です。最初の報告はWSL2でしたが、Team席のmacOSに加えてMaxプランのmacOSでも再現が出ています。開始が揺れる点も特徴で、コメントには10月13日、14日、15日、19日と、アカウントごとに時期が違う報告が並びます。同じv2.1.296〜v2.1.304でも、始まった時期はアカウント次第でした。

原因として最も具体的なのは、10月15日のコメントです。通信を自分のプロキシで観察した投稿者によると、対話セッションのクライアントは3か所のキャッシュ境界すべてにttl: "1h"を付けて送っています。ただし同じリクエストにcache-keepalive-2026-09-03というbetaが付くと、サーバーは書き込みを5分として記録しました。betaだけを送信途中で外すと、同じ内容が1時間で書かれています。claude -pはこのbetaを送らず、promptCacheTtlを明示した場合もクライアントが送らなくなります。症状の出方と回避策の効き方が、どちらもこの説明と合います。betaが有効になる条件はアカウント単位のリモート設定らしく、別のコメントではtengu_sequential_cloudというフラグがTeamアカウントでだけ有効になっていた例が出ています。いずれも利用者側の観察であり、Anthropicからの確認ではありません。

このbetaは、対話の待機中にクライアントが30秒おきに/v1/messages/cache_touchを送ってキャッシュを延命する仕組みに付随するものです。そのため、ラベルは5分でも実際の寿命は5分とは限りません。コメントには、5分と記録された書き込みが30分の空きを越えて読み取られ、70分で切れたという計測と、9.5分空けても約24万トークンの会話全体を読み取れたという例があります。一方、11.5分待機したセッションでは会話全体が書き直されており、延命が効くかどうかは一定していません。ラベルと実挙動のずれを確かめたい場合は、/usageのPrompt cache (main)行に出るwarm (… TTL, …)と、実際の再書き込み量の両方を見ます。

対処は、ここまでに出てきた設定と同じです。

{
  "promptCacheTtl": "1h"
}

「TTLはどう決まるか」の表は、この事象の影響を受けない場合の既定です。対話セッションで5分と表示されたら、3月の件ではなく、この設定で止められる別系統の症状かどうかをusage.cache_creationの内訳で確かめられます。

TTLはどう決まるか

現行の仕組みは、リクエストを2つのバケットに分けて考えます。主会話(対話ターン、-p実行、Agent SDKのターン)と、それ以外(サブエージェント・workflow・チームメイト・fork・圧縮・セッションタイトルなど)です。既定のTTLはバケットと課金形態の組み合わせで決まります。

プランの利用上限を超えて利用量クレジットに切り替わると、主会話のTTLも5分に落ちます。これは現在の既定の仕様です。サブエージェントは主会話と別の会話・別のキャッシュを持つため、サブスクリプションでも既定は5分のままです。

TTLは/modelの確認にも関わります。モデルを切り替えるとキャッシュ全体が計算し直しになるため、/modelはキャッシュが温まっている間だけ確認を求め、1つ分のTTLが過ぎれば確認なしで切り替えます。v2.1.238より前はTTLを見ずに、期限切れ後も確認を出していました。

TTLを確かめて固定する手順

コストや枠消費が急に増えたときは、次の順で原因をたどります。

3つ目のコマンドは次のとおりです。

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

/usageの表示例は、コストのページに次の形で載っています。末尾のwarm (1h TTL, last activity 40s ago)で、有効なTTLと最後の活動からの経過がわかります。

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)

長時間セッションでコストが増える他の原因まで切り分けたい場合は、Claude Codeで長時間セッションのコストが増える理由にまとめてあります。

自分でTTLを固定する方法

TTLを決める経路は複数あり、優先順位は次の順で最初に一致したものが使われます。

1. FORCE_PROMPT_CACHING_5M=1(両バケットを5分に強制)
2. バケットごとの環境変数(CLAUDE_CODE_PROMPT_CACHE_TTL / CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL)
3. バケットごとの設定(promptCacheTtl / subagentPromptCacheTtl)
4. サブエージェントのexperimental.cacheTtlfrontmatterフィールド(利用量クレジット中の1h指定は無視される)
5. ENABLE_PROMPT_CACHING_1H=1(両バケットに1時間を要求)
6. バケットごとの既定値(上表)

指定できる値は5mと1hだけで、それ以外は無視されます。promptCacheTtl・subagentPromptCacheTtlの2設定と対応する環境変数は、v2.1.242以降の要件です。changelogでこの2設定が新機能として載っているのはv2.1.243(2026-08-25)です。サブエージェント単位のexperimental.cacheTtlはv2.1.248(2026-08-27)で加わりました。

{
  "promptCacheTtl": "1h"
}

APIキー・Bedrock・Vertex・Foundry経由で長時間セッションを回している場合、既定は主会話も5分です。上の設定かENABLE_PROMPT_CACHING_1Hが実質的な対策になり、promptCacheTtlだけを1hにしても、主会話以外は5分のまま残ります。LLMゲートウェイ(ANTHROPIC_BASE_URL)経由の場合は、1時間リクエストの一部がanthropic-betaヘッダーで運ばれるため、ゲートウェイがそのヘッダーを変更せず転送する設定が要ります。Claude appsゲートウェイでは1時間TTLを使えません。

Amazon Bedrockでは、プロンプトキャッシュの対応、キャッシュできる最小のプレフィックス長、1時間TTLを使えるかどうかがモデルごとに異なります。Bedrockで1時間を指定する前に、使うモデルの対応を確かめる必要があります。Bedrock専用のENABLE_PROMPT_CACHING_1H_BEDROCKは非推奨ですが、v2.1.108のchangelogでは今も有効です。

逆にキャッシュの挙動を調べたいときや、管理設定で指定された長いTTLを上書きしたいときは、FORCE_PROMPT_CACHING_5M=1で両バケットを5分に戻せます。

API側の1時間キャッシュの単価とトレードオフはClaude APIの1時間キャッシュはいつ使うべきかで詳しく扱っています。

1時間と5分はどちらが向くか

利用形態ごとの対応の必要度は次のとおりです。

Claude Codeは一律スイッチからバケット別設定へキャッシュ制御を進化させた

3月の一件は、Claude Code側から見れば「1時間TTLという単一の既定値」を手放した瞬間だったといえます。その後に起きたのは既定値の復元ではなく、既定値が生む無駄を利用者側の設定で個別に打ち消す方向への置き換えでした。v2.1.108の環境変数は全体を一括で1時間に切り替えるだけでしたが、v2.1.243はバケット別、v2.1.248はサブエージェント単位まで粒度を上げています。

まとめ

長時間セッションやサブエージェントを多用する運用では、既定のTTLに頼らず、/usageのPrompt cache (main)行で現状を見てから、必要なバケットだけpromptCacheTtl・subagentPromptCacheTtlで固定する方法があります。短い連続作業が中心なら、5分TTLのままのほうが書き込みコストは安く済みます。