Claude CodeのキャッシュTTLが1時間から5分に短縮された問題と対処法
2026年3月、Claude Codeのプロンプトキャッシュが1時間TTLから5分TTLへ静かに切り替わり、コストと利用枠消費が増えました。GitHub issueのデータとAnthropicの回答、その後の修正の流れを追います。
何が起きたか — 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呼び出しです。
| フェーズ | 期間 | TTLの挙動 |
|---|---|---|
| 1 | 期間1/11〜1/31 | TTLの挙動5分のみ(1時間ティアがAPIにまだ無かったとみられる) |
| 2 | 期間2/1〜3/5 | TTLの挙動1時間のみ。33日以上連続で5分がほぼゼロ |
| 3 | 期間3/6〜3/7 | TTLの挙動移行期。5分トークンが再出現 |
| 4 | 期間3/8〜4/11 | TTLの挙動5分が主流。1時間は少数派か消滅 |
2月1日から3月5日までの33日間、5分トークンがほぼゼロの状態が2台のマシンで一致して続いていました。3月6日に5分トークンが再出現し、3月8日には5分側が1時間側の5倍という比率まで反転しています。クライアント側のバージョンや使い方は変えていないため、TTLの選択はサーバー側の設定によるものだと投稿者は分析しました。
コストとクォータへの実際の影響
投稿者は2026年4月9日更新の公式料金表を使い、実際の支払額と「もし1時間TTLのままだったら」の想定額を月別に比較しています。
| 月 | 実際の支払額 | 1時間TTLだった場合 | 超過分 | 無駄になった割合 |
|---|---|---|---|---|
| 2026年1月 | 実際の支払額$78.99 | 1時間TTLだった場合$37.54 | 超過分$41.45 | 無駄になった割合52.5% |
| 2026年2月 | 実際の支払額$1,120.43 | 1時間TTLだった場合$1,108.11 | 超過分$12.32 | 無駄になった割合1.1% |
| 2026年3月 | 実際の支払額$2,776.11 | 1時間TTLだった場合$2,057.01 | 超過分$719.09 | 無駄になった割合25.9% |
| 2026年4月(11日まで) | 実際の支払額$1,193.01 | 1時間TTLだった場合$1,016.78 | 超過分$176.23 | 無駄になった割合14.8% |
| 合計 | 実際の支払額$5,561.17 | 1時間TTLだった場合$4,612.09 | 超過分$949.08 | 無駄になった割合17.1% |
1時間TTLで運用できていた2月だけが無駄1.1%とほぼゼロで、3月は25.9%、4月も14.8%の過払いが続いています。claude-opus-4-6の料金で同じ計算をしても無駄の割合は同じ17.1%になるとされており、モデルの単価差ではなくキャッシュのTTL構成比そのものが無駄を決めていたことになります。
サブスクリプションプランは金額だけでなく利用枠(クォータ)でも制限されるため、影響はコストだけに留まりません。投稿者を含む複数のユーザーが、2026年3月以降に5時間の利用枠を初めて使い切ったと報告しています。キャッシュの書き込みトークンは満額でクォータに計上される一方、読み取り分の係数は別issue(#45756)で検証中とされ、5分TTLへの切り替わりがクォータ消費を押し上げた最有力の説明として挙げられていました。
issueへの回答 — 回帰ではなく用途別選択という説明
issueにはJarred-Sumner氏からコメントが寄せられています。3月6日の変更は実在し意図的だが、回帰ではなく進行中のキャッシュ最適化の一部だという説明です。要点は次の4つでした。
- 変更の有無: 3月6日に変更があった。日付の特定は正しい
- 意図したTTL: リクエストごとに再利用パターンを予測して選ぶ設計で、単一のグローバルな既定値は元々存在しない
- 1時間への統一: 全部のリクエストを1時間TTLにすると、1回しか使われないキャッシュでは書き込み単価(1時間TTLは5分TTLの約1.6倍)がそのまま乗るため総コストが増える。グローバルな切り替えは予定していない
- クォータ換算: cache read側の係数は別issue(#45756)で追って回答する
同コメントでは、サブスクリプション利用枠を使い切って利用量クレジット(オーバーエイジ)に切り替わったセッションが、セッション終了までずっと5分TTLに固着してしまうクライアント側の不具合をv2.1.90で修正済みとも説明されています。ただしこの具体的な修正項目は、v2.1.90の公開changelogには個別の項目として記載されていません。
GitHub APIでこのissueのメタデータを確認すると、Jarred-Sumner氏のauthor_associationはNONEで、リポジトリへの特別な権限を持たない一般ユーザーとして記録されています。公開プロフィールにも所属先の記載はありません。一方、Jarred-Sumner氏のコメントから9分後、issueはnotitatall氏によって「not planned(対応しない)」としてクローズされており、このnotitatall氏の公開プロフィールには所属先として「Anthropic」と記載があります。コメント本文そのものを公式見解と断定できる材料はissue単体にはありませんが、クローズまでの経緯を見る限り、内容自体は組織側の判断と歩調を合わせたものだったとうかがえます。
別のユーザー(spm1001氏)が、UK・ドイツの2拠点・約40.7万ターン分の独自データでこの説明を検証しています。1時間TTLが安定していた2月7日〜3月5日の期間、メイン会話のターンは5分比率がほぼ0%だった一方、サブエージェントのターンはすでに14%が5分でした。3月6日以降はメインターンでも5分比率が急上昇しましたが、サブエージェントより遅れて・不完全に切り替わっており、リクエスト単位の選択という説明とおおむね整合する挙動です。同じデータは、Vertex経由の課金では一貫して5分TTLのみだったことも示しています。当時Vertex AI向けの自動キャッシュ対応は「後日提供予定」とされ、課金経路によってキャッシュの挙動そのものが違う状態が別に存在していました。
「最適化」の裏で起きていた個別のバグ
リクエストごとに選ぶ設計という説明の一方で、公式changelogには「1時間TTLが通知なく5分に落ちていた」個別の不具合修正がこの後2回登場します。同じ症状に見えても、発生源が異なる独立した修正です。
issue提出(4月12日)からわずか2日後のv2.1.108で、コメントが「予定していない」としていたはずの1時間TTLへのオプトイン手段が配られた形になっています。さらに3週間後のv2.1.129でも同種の不具合が別途見つかり修正されました。4月14日から5月6日までの3週間で、「1時間TTLが気づかないうちに5分へ切り替わる」系の不具合が2種類、独立に見つかって修正されたことになります。
TTLはどう決まるか
現行の仕組みは、リクエストを2つのバケットに分けて考えます。主会話(対話ターン、-p実行、Agent SDKのターン)と、それ以外(サブエージェント・workflow・チームメイト・fork・圧縮・セッションタイトルなど)です。既定のTTLはバケットと課金形態の組み合わせで決まります。
| リクエストのバケット | サブスクリプション(プラン利用枠内) | 利用量クレジット・APIキー・クラウド経由 |
|---|---|---|
| 主会話 | サブスクリプション(プラン利用枠内)1時間 | 利用量クレジット・APIキー・クラウド経由5分 |
| それ以外 | サブスクリプション(プラン利用枠内)5分(一部のサーバー側補助リクエストのみ1時間) | 利用量クレジット・APIキー・クラウド経由5分 |
プランの利用上限を超えて利用量クレジットに切り替わると、主会話のTTLも5分に落ちます。これは3月の回帰とは別の、現在も続く仕様です。サブエージェントは主会話と別の会話・別のキャッシュを持つため、サブスクリプションでも既定は5分のままという点も、リクエストごとに選ぶ設計という説明と一致します。
今どちらのTTLが使われているかを確認する
claude -p "hello" --output-format json | jq '.usage.cache_creation'ephemeral_1h_input_tokensに値が入っていれば1時間TTL、ephemeral_5m_input_tokens側に入っていれば5分TTLでキャッシュが書き込まれています。コマンドを打たずに確認したい場合は、/usageページの「Prompt cache (main)」行や、ステータスラインに表示されるprompt_cacheオブジェクトでも同じ内訳を見られます。長時間セッションでコストが増える他の原因まで含めて切り分けたい場合は、Claude Codeで長時間セッションのコストが増える理由にまとめてあります。
自分でTTLを固定する方法
TTLを決める経路は複数あり、優先順位は次の順で最初に一致したものが使われます。
FORCE_PROMPT_CACHING_5M=1(両バケットを5分に強制)- バケットごとの環境変数(
CLAUDE_CODE_PROMPT_CACHE_TTL/CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL) - バケットごとの設定(
promptCacheTtl/subagentPromptCacheTtl) - サブエージェントの
experimental.cacheTtlfrontmatterフィールド(利用量クレジット中の1h指定は無視される) ENABLE_PROMPT_CACHING_1H=1(両バケットに1時間を要求)- バケットごとの既定値(上表)
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環境変数が実質的な対策になります。API側の1時間キャッシュの単価とトレードオフはClaude APIの1時間キャッシュはいつ使うべきかで詳しく扱っています。
利用形態別の影響と打ち手
| 利用形態 | 対応の必要度 | 理由 |
|---|---|---|
| サブスクリプションでプラン利用枠内の対話が中心 | 対応の必要度ほぼ影響なし | 理由主会話は既定で1時間TTL。何もしなくてよい |
| サブスクリプションで利用量クレジットに切り替わることが多い | 対応の必要度明確な恩恵あり | 理由promptCacheTtlで主会話のTTLを1時間に保てる |
| APIキー・Bedrock・Vertex・Foundryで長時間セッションを回す | 対応の必要度明確な恩恵あり | 理由既定は主会話も5分。promptCacheTtlかENABLE_PROMPT_CACHING_1Hで1時間に上げる |
| サブエージェントを多用するワークフロー | 対応の必要度条件次第 | 理由再利用が見込める分だけsubagentPromptCacheTtlやexperimental.cacheTtlで1時間に伸ばす |
Claude Codeは一律スイッチからバケット別設定へキャッシュ制御を進化させた
3月の一件は、Claude Code側から見れば「1時間TTLという単一の既定値」を手放した瞬間だったといえます。その後に起きたのは既定値の復元ではなく、既定値が生む無駄を利用者側の設定で個別に打ち消す方向への置き換えでした。v2.1.108の環境変数は全体を一括で1時間に切り替えるだけでしたが、v2.1.243はバケット別、v2.1.248はサブエージェント単位まで粒度を上げています。
長時間セッションや多段サブエージェントを運用しているなら、既定値まかせにせずpromptCacheTtl・subagentPromptCacheTtlを明示しておくほうが、同種の既定値変更が今後起きても影響を受けにくくなります。
よくある質問
1時間TTLに統一すれば必ず安くなりますか
なりません。1時間TTLの書き込み単価は5分TTLよりおよそ1.6倍高く、キャッシュしたコンテキストが1時間以内に再利用されないなら5分TTLのままのほうが安く済みます。1回しか使われないサブエージェントの呼び出しを無条件で1時間TTLにすると、逆に単価が上がります。
APIキー利用者にも影響しますか
影響します。APIキー・Bedrock・Vertex・Foundryは、主会話であっても既定は5分TTLです。サブスクリプションの主会話だけが既定1時間という扱いなので、長時間セッションをAPIキーで回している場合はpromptCacheTtlかENABLE_PROMPT_CACHING_1Hを自分で設定する必要があります。
まとめ
Claude CodeのキャッシュTTLは、2026年3月上旬に1時間から5分へ実際に切り替わり、投稿者の分析では3か月合算で17.1%のコスト過払いとクォータ消費の増加につながっていました。issueへの回答はこれを回帰ではなくリクエスト単位の最適化と説明していますが、同じ時期には「1時間TTLが気づかないうちに5分へ切り替わる」個別の不具合もv2.1.108・v2.1.129で別々に修正されています。現在は主会話とそれ以外の2バケットで既定TTLが決まり、promptCacheTtl・subagentPromptCacheTtl・experimental.cacheTtlで利用者側から明示的に上書きできます。長時間セッションやサブエージェントを多用する運用では、既定値に頼らずclaude -p "hello" --output-format jsonで現状を確認し、必要な範囲だけTTLを固定しておくのが実務的な対策です。