Claude Code がプロンプトキャッシングを使用する方法

Claude Code はプロンプトキャッシングを自動的に管理します。モデル切り替えがキャッシュなしの遅いターンをトリガーする理由、/compact のコスト、CLAUDE.md の編集がセッション中に適用されない理由、キャッシュヒット率を確認する方法を確認してください。

プロンプトキャッシングにより、Claude Code はより高速で費用効率的になります。キャッシングがなければ、API はターンごとに完全な履歴を再処理します。キャッシングがあれば、既に処理したものを再利用し、再読み込みをキャッシュされたトークンレートで請求し、変更されたものに対してのみ完全に処理します。

Claude Code はプロンプトキャッシングを自動的に処理します。ただし、無効にすることはできます。プロンプトキャッシングの仕組みを理解することは依然として有用です。キャッシュを無効にするアクションがあり、次の応答が遅くなり、再構築中により高くなるためです。このページでは、どのアクションがそうであるか、一部の設定が再起動を待つ理由、使用量が高く見える場合にキャッシュパフォーマンスを確認する方法について説明します。

キャッシュの構成方法

Claude Code でメッセージを送信するたびに、新しい API リクエストが作成されます。モデルはリクエスト間で何も記憶しないため、Claude Code は完全なコンテキストを再送信します。システムプロンプト、プロジェクトコンテキスト、すべての以前のメッセージとツール結果、および新しいメッセージです。新しいコンテンツは最後に追加されるため、各リクエストのほとんどは前のリクエストと同じです。プロンプトキャッシングは、API が変更されなかった部分の再処理を回避する方法です。

API は各リクエストの開始部分（プリフィックスと呼ばれます）を最近処理したコンテンツと照合することでキャッシュします。通常のターンでは、プリフィックスは前のリクエスト全体であり、最新の交換のみが新しいものです。一致は正確であるため、プリフィックスのどこかで変更があると、その後のすべてが再計算されます。ファイルごとまたはセグメントごとのキャッシングはありません。API リファレンスの プロンプトキャッシングの仕組み を参照して、基礎となるメカニズムを確認してください。

プリフィックスマッチングを最大限に活用するために、Claude Code は各リクエストを整理して、ターン間で変更されることが少ないコンテンツを最初に配置します。

会話レイヤーへの変更は、システムプロンプトとプロジェクトコンテキストをキャッシュされたままにします。システムプロンプトへの変更は、すべての後続コンテンツが異なるプリフィックスの後ろに配置されるようになるため、すべてを無効にします。3 番目の列は、完全なリストではなく一般的なトリガーを示しており、以下のセクションで完全なセットについて説明します。

プリフィックスマッチルールは、このページのほとんどの動作を説明しています。たとえば、Plan Mode と スキル読み込み は、その命令を会話メッセージとして追加するため、キャッシュされたプリフィックスはそのままです。

レイヤーテーブルに表示されないが、キャッシュされたままになるものに影響する 2 つの設定があります。

• モデル：各モデルには独自のキャッシュがあります。モデルを切り替えると、コンテンツが同じであってもリクエスト全体が再計算されます。以下の モデルの切り替え を参照してください。
• エフォートレベル：ほとんどのモデルでは、各エフォートレベルには独自のキャッシュがあるため、セッション中にエフォートを変更するとリクエスト全体が再計算されます。API キーまたは Claude サブスクリプションを使用した Opus 5.5 および Fable 5.1 では、デフォルトではキャッシュはそのままです。以下の エフォートレベルの変更 を参照してください。

キャッシュの場所

キャッシングはサーバー側で行われ、モデルを提供するインフラストラクチャで行われます。その場所は、認証方法によって異なります。

• API キー、Claude サブスクリプション、または Claude Platform on AWS：キャッシュは Anthropic のインフラストラクチャに存在し、Claude API を通じてアクセスされます。
• Amazon Bedrock または Google Cloud の Agent Platform：キャッシュはクラウドプロバイダーのサービングインフラストラクチャに存在します。
• Microsoft Foundry：デプロイメントの ホスティングオプション によって異なります。Azure デプロイメント上でホストされている場合は Azure インフラストラクチャで提供されます。Anthropic デプロイメント上でホストされている場合は Anthropic のインフラストラクチャで提供されます。
• カスタム ANTHROPIC_BASE_URL または LLM ゲートウェイ：キャッシュはリクエストが転送される場所に存在し、キャッシングが機能するかどうかはゲートウェイに依存します。

Claude Code は会話中にシステムコンテキスト（ファイル変更通知など）も追加し、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定しない限り、すべてのプロバイダーと接続でそのブロックをキャッシング用にマークします。その場合、そのブロックはキャッシュなしで送信されます。

プロバイダー独自のエンドポイント、Amazon Bedrock とその Mantle エンドポイント、Google Cloud の Agent Platform、および Microsoft Foundry では、Claude API と同じ方法でブロックをキャッシュします。

リクエストが LLM ゲートウェイ、カスタム ANTHROPIC_BASE_URL、または ANTHROPIC_BEDROCK_BASE_URL などのクラウドプロバイダーベース URL オーバーライドを通過する場合、キャッシュされたままになるものは、ゲートウェイが Claude Code が送信する cache_control マーカー をどのように処理するかに依存します。

• 変更されずに転送する：ブロックと会話は、プロバイダー独自のエンドポイントと同じようにキャッシュされます。
• cache_control という名前の 400 エラーでマークされたリクエストを拒否する：Claude Code はマーカーをブロックから最後の会話メッセージに移動させてリクエストを再送信し、会話の残りの部分でそこに保持します。ブロックはキャッシュなし入力として請求されます。会話はキャッシュされたままです。
• マーカーを削除して成功を返す：会話履歴全体は、毎ターン、キャッシュなし入力として請求されます。ブロック形式のシステムコンテンツをプレーン文字列に変換するゲートウェイは、同じ方法でマーカーをドロップします。

各プロバイダーが保存および処理するものについては、データ使用 を参照してください。キャッシュがどこに存在するかに関係なく、エントリは非アクティブ期間後に期限切れになり、以下の キャッシュの有効期間 では TTL とそれを延長する方法について説明しています。

キャッシュを無効化するアクション

これらのアクションは、次のリクエストでキャッシュの一部または全部がミスになる原因となります。その後、新しいプレフィックスがキャッシュされるまで、1 回限りの遅く、より高額なターンが表示されます。これらのほとんどは、コストがあることを知ったら、タスク中に回避できます。モデルスイッチは、その後の遅いターンに気付くまで無料に感じられるかもしれません。

• モデルの切り替え
• 努力レベルの変更
• 高速モードの有効化
• MCP サーバーの接続または切断
• プラグインの有効化または無効化
• ツール全体の拒否
• 会話のコンパクト化
• 多くの画像の蓄積
• Claude Code のアップグレード

モデルの切り替え

各モデルには独自のキャッシュがあります。/model で切り替えると、コンテンツが同じであっても、次のリクエストはキャッシュヒットなしで会話履歴全体を読み込みます。

ターミナルで /model を実行すると、キャッシュがまだ温かい間は、Claude Code はスイッチの確認を求めます。ただし、新しいモデルが最後のレスポンスを生成したモデルではない場合に限ります。キャッシュは、Claude Code がこの会話で最後にリクエストを送信した後、または Claude が最後に応答した後、1 つのキャッシュ TTL の間、温かいままです。その時間が経過すると、キャッシュは期限切れになるため、Claude Code は確認を求めずに切り替えます。

v2.1.238 より前では、Claude Code はキャッシュ TTL をチェックせず、キャッシュが期限切れになった後でも確認を求めていました。

PreModelSwitch フックを使用して、この確認を必須にするか、スキップすることもできます。

opusplan モデル設定は、プランモード中は Opus に、実行中は Sonnet に解決されるため、各プランモードの切り替えはモデルスイッチであり、新しいキャッシュを開始します。

Fable モデルと Opus 5.5 および Opus 5 の自動モデルフォールバックもモデルスイッチです。安全分類器がフォールバックモデルを持つカテゴリーでリクエストにフラグを立てると、Claude Code はそのモデルでリクエストを再実行し、セッションはそこで続行されます。

スキルまたはコマンドのフロントマターがセッションの現在のモデル以外の modelを指定する場合、そのターンもモデルスイッチです。次のリクエストはキャッシュヒットなしで会話履歴全体を読み込みます。セッションモデルは次のプロンプトで再開されます。context: fork スキルは、代わりにフォークされたサブエージェントのモデルを設定します。

努力レベルの変更

ほとんどのモデルでは、セッション中に努力レベルを変更すると、次のリクエストはキャッシュヒットなしで会話履歴全体を読み込みます。キャッシュがまだ温かい間は、Claude Code は最初に変更を確認するよう求めます。

API キーまたは Claude サブスクリプションを使用した Opus 5.5 および Fable 5.1 では、努力レベルの変更によってキャッシュが保持され、Claude Code は確認を求めずに新しいレベルを適用します。これは Amazon Bedrock、Google Cloud の Agent Platform、Claude アプリゲートウェイ、または CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定した場合、あるいは組織が HIPAA 構成を持つ場合には適用されません。

v2.1.260 より前では、API キーまたは Claude サブスクリプションを使用した Fable 5.1 での努力レベルの変更もキャッシュを無効化していました。

高速モードの有効化

高速モードを有効にすると、キャッシュキーの一部であるリクエストヘッダーが追加されるため、Claude Code が高速モードをオンにして送信する最初のリクエストはキャッシュヒットなしで会話履歴全体を読み込みます。Claude Code はターンの開始時にそのヘッダーを 1 回設定し、ターン全体でそれを保持するため、Claude が作業中に高速モードをオンにすると、ヘッダーからのキャッシュミスは次のターンの最初のリクエストで発生します。これらのキャッシュされていない入力トークンは高速モードレートで請求されます。これが、セッションの開始時にオンにするのが、長いセッションの深くでオンにするよりもコストが低い理由です。現在のモデルが高速モードをサポートしていない場合、高速モードを有効にするとモデルも切り替わり、そのスイッチ自体が実行中のターンの次のリクエストから新しいキャッシュを開始します。

コストは会話ごとに 1 回適用されます。最初の高速モードターンの後、Claude Code はヘッダーを送信し続け、キャッシュキーの一部ではないリクエストの速度設定のみを変更します。高速モードをオフにする、レート制限後の標準速度への自動フォールバック、およびその後にオンに戻すことはすべてキャッシュを保持します。使用クレジットが不足した場合、Claude Code は各拒否された高速モードリクエストを同じ方法で標準速度で再試行するため、このフォールバックもキャッシュを保持します。/clear と /compact はこれをリセットします。これらはとにかくそれらのポイントでキャッシュを再構築するためです。

MCP サーバーの接続または切断

ツール定義はシステムプロンプトレイヤーに存在するため、ターン間でリクエスト内のツール定義のセットが変わるとキャッシュが無効化されます。アドバイザーツールの切り替えは例外です。その定義はキャッシュブレークポイントの後に存在するため、/advisor を有効または無効にするとキャッシュされたプレフィックスはそのまま保持されます。MCP サーバーの変更がこれを行うかどうかは、そのツールがツール検索によって遅延されるか、プレフィックスに読み込まれるかによって異なります。

• 遅延ツール、サポートされているモデルのデフォルト：サーバーの接続、切断、またはツールリストの変更は、新しいコンテンツを追加するだけで、既にキャッシュされているものを乱しません。
• プレフィックスに読み込まれるツール：それらへの変更はキャッシュを無効化します。これは、ツール検索が利用できないか無効になっている場合に発生します。例えば、Claude 4.5 世代より前の Google Cloud の Agent Platform モデル、カスタム ANTHROPIC_BASE_URL ゲートウェイ、または Claude Code がデプロイメントがツール検索を拒否することを検出した Microsoft Foundry Azure でホストされているデプロイメントの場合です。また、alwaysLoadとマークされたサーバーまたはツール、および閾値ベースの読み込みによって前もって保持される定義の場合にも発生します。

ツールがプレフィックスに読み込まれる場合、無効化の最も一般的な原因は、セッション中にサーバーが接続または切断されることです。これは、あなたのアクションなしに発生する可能性があります。stdio サーバーのプロセスが終了する、HTTP セッションが期限切れになる、またはサーバーが一時的な障害後に自動的に再接続する場合です。接続されたサーバーは、そのツールリストを変更する動的ツール更新をプッシュすることもできます。

MCP 設定を編集しても、それ自体ではキャッシュは変わりません。新しい設定は、サーバーが接続または切断される再起動後にのみ有効になります。

プラグインの有効化または無効化

プラグインを有効または無効にする場合、変更のコストはプラグインが提供するコンポーネントタイプによって異なります。以下のケースは、各コンポーネントタイプ、Claude Code が変更を適用するタイミング、および同じセッション内でプラグインを再度無効にする場合の動作をカバーしています。

キャッシュを保持するプラグインコンポーネント

Claude Code は、プラグインのスキル、コマンド、エージェント、フック、モニター、またはテーマのキャッシュを無効化することはありません。既存の会話の後にそのコンテンツを追加するため、次のリクエストはそのコンテンツに対して支払い、その前のすべてをキャッシュから読み込みます。

MCP サーバーを提供するプラグイン

MCP サーバーを提供するプラグインを有効または無効にする場合、Claude Code はMCP サーバーを接続または切断する場合と同じルールに従います。

• Claude Code がサーバーのツールを遅延させる場合、キャッシュを保持します。
• Claude Code がそれらをプレフィックスに読み込む場合、次のリクエストは会話全体を再読み込みします。

コード インテリジェンス プラグイン

コード インテリジェンス プラグインを有効にすると、Claude はLSP ツールを取得します。

プラグイン変更が適用される場合

/plugin メニューで行った変更は、/reload-pluginsを通じて行われます。Claude Code はメニューを閉じるときにこれを実行します。追加されたアナウンスメントまたは完全な再読み込みのいずれかのコストを、変更が適用された後の最初のターンで支払います。Claude Code は変更を独自に適用することもできます。

• command ソースを持つプラグインの場合、Claude Code はプラグイン自体を再読み込みできます。
• /plugin インターフェースからプラグインをインストールする場合、Claude Code はインストール中にそれを有効化できます。インストール概要は、それが行われたかどうかを示します。
• v2.1.246 以降で /cdでセッションを移動する場合、Claude Code は新しいディレクトリの設定が有効にするプラグインを移動の一部として適用します。/reload-plugins が保持する完全な再読み込み警告なしで。
• インタラクティブセッションでは、--plugin-dir で渡したプラグインのフォルダでプラグインを追加または削除する場合、変更は直ちに適用されます。それを適用すると完全な再読み込みがトリガーされる場合、Claude Code は変更を保持し、/reload-plugins を実行するための通知を表示します。Claude Code v2.1.265 以降が必要です。

/reload-plugins が実行され、再読み込みが完全な再読み込みをトリガーする場合、Claude Code は警告を表示し、再読み込みを適用しません。/reload-plugins --force を実行して、とにかくそれを適用します。

/reload-plugins は、デスクトップアプリ、Agent SDK、および -p を使用した非インタラクティブモードなど、インタラクティブターミナルのないセッションでも実行されます。セッションに直接入力する場合です。Claude Code v2.1.260 以降が必要です。

これらのセッションでは、再読み込みはプラグイン MCP サーバーの変更を除くすべてを適用します。これらは次のセッションで有効になり、セッション中に完全な再読み込みのコストは決してかかりません。

セッション内で有効化してから無効化するプラグイン

セッションの前半で有効にしたプラグインを無効にする場合、Claude Code は以前のリクエスト形状を復元します。そのプレフィックスがまだキャッシュ有効期間内にある場合、次のリクエストは再構築する代わりに、より古いキャッシュエントリを読み込みます。

ツール全体の拒否

Bash または WebFetch のような裸のツール名を拒否ルールとして追加すると、Claude はそのツールを次のリクエストから呼び出すことができなくなります。/permissions を通じて追加するか、設定ファイルを直接編集するかのいずれかです。これには、ターンの途中で /permissions を通じて追加するルールが含まれます。

ツール検索がアクティブな場合（サポートされているモデルではデフォルト）、リクエストのツール定義は変更されず、キャッシュされたプレフィックスは保持されます。ツール検索が利用できないか無効になっている場合、Claude Code は次のリクエストから定義を削除し、キャッシュを無効化します。ルールを後で削除する場合も同じです。

ツール名の位置で一致する拒否ルールのみがこの効果を持ちます。裸のツール名、同等の Bash(*) 形式、または "*" のようなツール名グロブです。"mcp__*" のような MCP ツールのみに一致するグロブは、同じ方法でそれらのツールをブロックします。Bash(rm *) のようなスコープ付き拒否ルール、およびすべての許可とアスクルールは、Claude が見るツールを変更しません。Claude Code は Claude が呼び出しを試みるときにそれらをチェックし、プレフィックスはそのまま保持されます。

会話のコンパクト化

コンパクト化は、メッセージ履歴を概要に置き換えます。設計上、これは会話レイヤーを無効化します。次のリクエストには、古いものと共通のプレフィックスを共有しない、新しく短い履歴があるためです。Claude Code はシステムプロンプトレイヤーを再利用します。ただし、会話がそうでなければ変更されるシステムプロンプトを保持しながら再開された場合を除きます。その場合、最初のコンパクト化は現在のプロンプトに切り替わり、そのレイヤーは 1 回再構築されます。プロジェクトコンテキストをディスクから再読み込みします。これはセッション開始以降 CLAUDE.md とメモリが変更されていない場合にのみキャッシュヒットします。

概要を生成するために、Claude Code は会話と同じシステムプロンプト、ツール、および履歴を持つ別のリクエストを送信します。さらに、最終ユーザーメッセージとして追加された要約化指示があります。キャッシュが温かい間、そのリクエストはキャッシュからプレフィックスを読み込むため、セッション中の /compact はコンテキストサイズが示唆するコストの一部であり、ほとんどの時間を概要の生成に費やします。

キャッシュ有効期間より長い休止の後、読み込むキャッシュは残っていないため、要約化リクエストはキャッシュされていない入力として完全な履歴を再処理します。これが /compact が古いセッションを再開するときに最もコストがかかる理由です。温かいケースと冷たいケースの両方で、コンパクト化後のターンは、はるかに短い概要のためだけに会話キャッシュを再構築するため、そのターンは遅い部分ではありません。

多くの画像の蓄積

API は、各リクエストが実行できる画像と PDF の数を制限しています。現在の数については、API ドキュメントのリクエスト制限を参照してください。Claude Code はリクエスト内の画像と PDF の合計サイズもキャップするため、大きなスクリーンショットは小さいものより少ない画像で制限に達します。

次のリクエストがいずれかの制限を超える場合、Claude Code は送信する内容から最も古い画像と PDF のバッチを削除します。これにより、再度削除する必要があるまでさらに多くの余地が生まれます。Claude はもう削除された画像を見ることができません。Claude がそれらの 1 つを再度必要とする場合は、再度共有してください。

画像を削除すると、それらを保持していたメッセージが変更されるため、次のリクエストはそれらのメッセージの最も早いものから会話を再処理します。Claude Code はバッチごとに削除するため、新しいスクリーンショットごとに 1 つではなく、バッチごとに 1 つの遅いターンが表示されます。

Claude Code のアップグレード

新しい Claude Code バージョンは通常、システムプロンプトまたはツール定義を更新するため、アップグレード後に開始する最初の会話はトップからキャッシュを構築します。自動更新は新しいバージョンをバックグラウンドでダウンロードしますが、次の起動時に適用され、セッション中には決して適用されません。そのため、セッション中の驚きではなく、再起動後のキャッシュされていない最初のターンとしてこれが表示されます。DISABLE_AUTOUPDATER=1 を設定して、アップグレードが適用されるタイミングを制御します。

キャッシュを保持するアクション

これらのアクションは、会話の末尾に追加されるか、リクエストにまったく触れません。CLAUDE.md の編集など、その中には /clear、/compact、または再起動までキャッシュを保持する理由が、変更が実行中のセッションに到達しない理由と同じであるものもあります。

• リポジトリ内のファイルを編集する
• セッション中に CLAUDE.md を編集する
• 権限モードを変更する
• 出力スタイルを変更する
• スキルとコマンドを呼び出す
• /recap を実行する
• 会話を巻き戻す
• サブエージェントを生成する

リポジトリ内のファイルを編集する

ファイルの内容は Claude がそれらを読むときにのみコンテキストに入り、読み取りは会話に追加されます。Claude が以前読んだファイルを編集しても、履歴内の以前の読み取りは遡及的に変更されません。代わりに、Claude Code はファイルが変更されたことを示す <system-reminder> を追加し、必要に応じて Claude がそれを再度読み取ります。

セッション中に CLAUDE.md を編集する

プロジェクトルートとユーザーレベルの CLAUDE.md ファイルはセッション開始時に 1 回読み取られ、メモリに保持されます。セッション中にそれらを編集してもキャッシュは無効化されませんが、編集も適用されません。Claude はセッション開始時に読み込まれたバージョンで動作し続けます。新しいコンテンツは次の /clear、/compact、または再起動時に読み込まれます。

サブディレクトリ内のネストされた CLAUDE.md ファイルとpaths: frontmatter を持つルールは後で、Claude が最初に一致するファイルを読むときに読み込まれます。読み込まれる前にそれを編集すると、実際に効果があります。読み込まれた後、コンテンツは会話履歴の一部であるため、セッション中の編集は遡及的にそれを変更しません。

権限モードを変更する

権限モード（手動から編集を受け入れるなど）を切り替えても、システムプロンプトやツール定義は変更されないため、モード変更はキャッシュセーフです。例外は opusplan モデル設定を使用した plan mode です。これはプラン モードに入るか終了するときに、モデルを Opus と Sonnet の間で切り替えます。これにより、モード切り替えはモデル切り替えになります。

出力スタイルを変更する

セッション中に /output-style、/config、または outputStyle 設定で出力スタイルを切り替えると、Claude は次のメッセージから新しいスタイルを使用します。Claude Code は新しいスタイルの指示をメッセージとして会話に配信するため、そのリクエストはシステムプロンプトと以前の会話をキャッシュから読み取ります。

v2.1.251 より前では、セッション中のスタイル切り替えはキャッシュを保持していましたが、/clear を実行するか新しいセッションを開始するまで適用されませんでした。

スキルとコマンドを呼び出す

スキルとコマンドは、呼び出しポイントでユーザーメッセージとして指示を挿入します。会話内の以前のものは何も変わりません。frontmatter で model という名前を付けたスキルまたはコマンドは、そのターンのモデル切り替えになる可能性があります。

`/recap` を実行する

/recapはターミナルに表示するための概要を生成します。/compact とは異なり、メッセージ履歴を置き換えるのではなく、コマンド出力として概要を追加するため、キャッシュされたプレフィックスはそのまま残ります。

会話を巻き戻す

/rewindは会話を以前のターンに切り詰めます。残りの履歴は、その時点でキャッシュが構築されたのと同じコンテンツであり、システムプロンプトとプロジェクトコンテキストレイヤーは変更されないため、次のリクエストは以前のキャッシュエントリにヒットします。それ以降のすべてのターンはそのプレフィックスを読み取っており、元のターンが TTL より長い前であっても、エントリをウォーム状態に保ちました。

会話と一緒にファイルチェックポイントを復元しても、キャッシュに対する個別の効果はありません。ファイルの内容は、リポジトリ内のファイルを編集すると同じように、Claude がそれらを読むときにのみコンテキストに入ります。

セッションの再開

セッションを再開する場合、Claude Code は会話全体を再度送信し、リクエストはキャッシュから、そのプレフィックスの変更されていない部分で、かつ キャッシュの有効期限内にある部分を読み込みます。このページの上部にあるレイヤーテーブルは、各レイヤーで何が変わるかを示しています。

システムプロンプトは Claude Code のアップグレード後、または再開時に異なる --append-system-prompt テキストがある場合に変更されます。デフォルトでは、再開された会話は開始時のシステムプロンプトを保持するため、その履歴は同じプロンプトの背後にあり、会話がコンパクト化されるか新しい会話で変更が有効になります。再開されたセッションのシステムプロンプトフラグは Claude Code がすべてのリクエストでプロンプトを再構築する場合をカバーしています。

キャッシュライフタイム

キャッシュされたプリフィックスは、非アクティブ期間後に期限切れになります。キャッシュにヒットするすべてのリクエストはタイマーをリセットするため、作業を続ける限りキャッシュは温かく保たれます。十分に長いギャップの後、次のリクエストは完全な入力を再計算し、キャッシュを再確立します。これが、立ち去った後の最初のターンが顕著に遅い理由です。

Pro または Max プランでは、長い休止後に大規模なセッションを再開する場合、Claude Code はサマリーから再開することを提案するため、後続のリクエストは完全な履歴を保持する必要がありません。

Time to Live（TTL）は、キャッシュが生き残るギャップの長さを制御します。API は 2 つを提供します。5 分の TTL と、より長い休止を通じてキャッシュを温かく保つ1 時間の TTLですが、キャッシュ書き込みをより高いレートで請求します。より長い TTL は、セッションをアイドル状態のままにして戻ってくる場合に役立ちます。期限切れのプリフィックスが発生する再処理をスキップできるためです。5 分を超えてアイドル状態にならない短いバースト作業では、より高い書き込みレートが適用され、より長いキャッシュライフタイムが未使用のままになるため、コストが高くなります。

各リクエストが取得する TTL

Claude Code はリクエストごとに TTL を決定し、すべてのリクエストは 2 つの固定バケットのいずれかに該当します。

• メイン会話: インタラクティブなターン、非インタラクティブな -p 実行、Agent SDK ターン、およびそれらと共にインラインで実行される Claude Code ヘルパー
• その他すべて: サブエージェント、ワークフロー、プロセス内チームメイト、フォーク、圧縮、セッションタイトルなど、その会話の外で Claude Code が行うリクエスト

TTL を自分で選択しない限り、Claude Code は Claude サブスクリプション内でプランに含まれる使用量内でのみ 1 時間の TTL をリクエストします。そこでメイン会話に対して 1 時間をリクエストし、Anthropic がサーバー側で制御する小さなヘルパーリクエストセットをリクエストします。このテーブルは、両方の種類の請求下での各バケットのデフォルト TTL を示しています。

プランの使用量制限を超えて、Claude Code が使用クレジットを引き出すと、その使用量に対して請求されるため、Claude Code はメイン会話をより安い 5 分の TTL に低下させます。そこで 1 時間の TTL を保つには、TTL を自分で選択してください。

TTL を自分で選択する

どちらのバケットに対しても TTL を設定できます。各コントロールは 5m または 1h を取り、Claude Code は他の値を無視します。

• メイン会話: promptCacheTtl 設定、または CLAUDE_CODE_PROMPT_CACHE_TTL 環境変数
• その他すべて: subagentPromptCacheTtl 設定、または CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL 環境変数

両方の設定と両方の環境変数には Claude Code v2.1.242 以降が必要です。API キーで署名するか、クラウドプロバイダーを使用する場合は、promptCacheTtl を 1h に設定して、メイン会話に 1 時間のキャッシュを与えます。その外のリクエストは、そのバケットに対しても TTL を選択するまで 5 分のデフォルトを保ちます。

複数のコントロールが適用される場合、Claude Code はこの順序で最初にマッチするものを取ります。

1. FORCE_PROMPT_CACHING_5M=1。両方のバケットに対して 5 分を強制します
2. バケットの環境変数
3. バケットの設定
4. サブエージェントのリクエストの場合、サブエージェントの experimental frontmatter フィールドの cacheTtl 値。Claude Code v2.1.248 以降が必要です。Claude サブスクリプションが使用クレジットを使用している間、Claude Code はそこの 1h を無視します
5. ENABLE_PROMPT_CACHING_1H=1。両方のバケットに対して 1 時間をリクエストします
6. リクエストのバケットのデフォルト

キャッシング動作をデバッグする場合、2 つの TTL を比較する場合、または管理設定で設定された長い TTL をオーバーライドする場合は、FORCE_PROMPT_CACHING_5M=1 を設定します。

メイン会話のキャッシュ書き込みが使用した TTL を確認するには、claude -p "hello" --output-format json を実行し、結果の usage.cache_creation を読みます。Claude Code は 1 時間のキャッシュ書き込みを ephemeral_1h_input_tokens の下で報告し、5 分のキャッシュ書き込みを ephemeral_5m_input_tokens の下で報告します。

ANTHROPIC_BASE_URL で設定した LLM ゲートウェイを通じて、1 時間のリクエストの一部は anthropic-beta ヘッダーで移動するため、ゲートウェイをそのヘッダーを変更されずに転送するように設定します。1 時間の TTL はClaude アプリゲートウェイを通じて利用できません。Amazon Bedrock では、プロンプトキャッシングサポート、最小キャッシュ可能プリフィックス長、および 1 時間の TTL 可用性はすべてモデルによって異なります。キャッシュトークン数がゼロのままの場合は、Amazon Bedrock ドキュメントのサポートされているモデル、リージョン、制限を確認してください。

キャッシュスコープ

Claude Code では、キャッシュは事実上 1 つのマシンとディレクトリにスコープされます。各会話は作業ディレクトリ、プラットフォーム、シェル、OS バージョンを保持し、システムプロンプトは自動メモリパスに名前を付けるため、異なるディレクトリの 2 つのセッションは異なるプリフィックスを構築し、互いのキャッシュをミスします。これには同じリポジトリの worktrees が含まれます。各 worktree は独自の作業ディレクトリを持つためです。

同じディレクトリで並行して実行するセッションは、一致するプリフィックスを構築し、互いのキャッシュを読み取ります。順序付きセッションは、起動時に取得された git ステータススナップショットが一致する場合にのみプリフィックスを共有します。各会話はそのスナップショットからブランチと最近のコミットも保持するためです。

基礎となる API キャッシュはより広いです。キャッシュは組織間で分離され、一部のプロバイダーでは、組織内のワークスペース間で分離されます。これらの境界内で、同じモデルとプリフィックスを持つ 2 つのリクエストは同じキャッシュを読み取ります。自動化されたプロセスのフリートを実行する Agent SDK 呼び出し元については、ユーザーとマシン間でプロンプトキャッシングを改善を参照して、システムプロンプトのマシンごとのセクションを抑制し、マシン間でキャッシュを共有します。

キャッシュパフォーマンスを確認する

キャッシュパフォーマンスは、API がすべての応答で報告する 2 つのトークン数として表示されます。最も直接的な方法は、current_usage オブジェクトを読み取るstatusline スクリプトを監視することです。

読み取りから作成への比率が高いほど、キャッシングが機能しています。作成がターンごとに高いままの場合、プリフィックスで何かが変更されています。キャッシュを無効にするアクションセクションは、通常の原因をリストします。

セッションごとのサマリーについては、/usage を実行してください。メインの会話の最初の応答の後、Claude Code はセッションブロックにPrompt cache (main) 行を追加し、セッションのヒット率、ミス数、およびキャッシュが現在ウォームであるかどうかを表示します。statusline スクリプトは、prompt_cache オブジェクトから同じ数値を読み取ることができます。どちらも Claude Code v2.1.251 以降が必要です。

Prompt cache (main) 行は、Claude Code が識別できる場合、最後のミスの可能性のある原因も名前を付けます。例えば likely cause: tool definitions changed のようにです。可能性のある原因テキストには Claude Code v2.1.260 以降が必要です。

組織全体の可視性については、OpenTelemetry エクスポーターはユーザーとセッションごとにキャッシュ読み取りと作成トークンを報告します。メトリックとイベント属性リファレンスについては、使用状況の監視を参照してください。

サブエージェントとキャッシュ

サブエージェントは、親とは別に、独自のシステムプロンプトとツールセットを持つ独自の会話を開始します。最初のリクエストは親のキャッシュを読み取りません。2 つのプリフィックスが異なるためです。また、独自のターン全体で独自のキャッシュを温めます。サブエージェントはメイン会話の TTL バケットの外にあるため、サブスクリプション上でも 5 分間の TTL を取得します。より長い TTL を選択するまでです。

親のキャッシュは影響を受けません。親の側から、サブエージェントの呼び出しと結果は会話に追加され、親のプリフィックスはそのままです。

一方、フォークは、親のシステムプロンプト、ツール、会話履歴を正確に継承するため、最初のリクエストは親のキャッシュを読み取ります。

他のリクエストも、以前のリクエストがキャッシュしたプリフィックスを読み取ることができます。

• セッションコピー: /forkでコピーしたセッションは、コピーされた会話の最後にメッセージとして分離命令を受け取るため、元の会話が構築したキャッシュはそのままです。
• コンパクト化: 会話のコンパクト化で説明されている要約呼び出しは、同じプリフィックス共有アプローチを使用します。
• 再開されたサブエージェント: Claude がサブエージェントを再開する場合、再開実行の最初のリクエストは、元の実行が温めたキャッシュを読み取ることができます。
• ワークフローファンアウト: ワークフローファンアウトの同じプリフィックスエージェントでは、Claude Code はデフォルトで最初のエージェント以外をすべて最大 5 秒間保持するため、最初のエージェントがキャッシュしたプリフィックスを読み取ることができます。

プロンプトキャッシングを無効にする

キャッシング動作を特定のモデルまたはプロバイダーでデバッグするときは、キャッシングを無効にすることが時々役立ちます。オフにするには、これらの環境変数のいずれかを 1 に設定します。

組織全体でキャッシングポリシーを設定するには、これらのいずれかまたは TTL 変数を 管理設定の env ブロックに入れます。通常の使用では、キャッシングを有効のままにしてください。

関連リソース

• Claude Code の構築から学んだ教訓: プロンプトキャッシングがすべて: Plan mode、遅延ツール読み込み、コンパクト化の設計根拠
• コンテキストウィンドウを探索: コンテキストに読み込まれるもの、いつ読み込まれるか
• トークン使用量を削減: コンテキストサイズを管理するためのキャッシング以外の戦略
• コストを追跡および削減: Agent SDK 呼び出し元のキャッシュトークン追跡と TTL 設定
• プロンプトキャッシング: 基礎となる API メカニズム、ブレークポイント、価格設定