DISABLE_PROMPT_CACHING_OPUS/SONNETでモデル別にキャッシュを無効化

このTipsでできること

Claude Codeには、プロンプトキャッシュを丸ごと止めるDISABLE_PROMPT_CACHINGとは別に、モデルファミリー単位で個別に無効化できる4つの環境変数があります。DISABLE_PROMPT_CACHING_OPUS・DISABLE_PROMPT_CACHING_SONNET・DISABLE_PROMPT_CACHING_HAIKU・DISABLE_PROMPT_CACHING_FABLEです。Opusだけキャッシュを切ってSonnetとHaikuは通常どおり効かせる、といった使い分けができます。

キャッシュの保持時間(TTL)を選ぶCLAUDE_CODE_PROMPT_CACHE_TTLやpromptCacheTtl設定とは軸が違う点に注意してください。あちらは「キャッシュをどれだけ長く持つか」を決める変数で、こちらの4つは「そもそもキャッシュを書き込むかどうか」自体を切るスイッチです。TTLを1hにしていても、DISABLE_PROMPT_CACHING_OPUS=1を立てればOpusのリクエストはキャッシュ書き込みそのものが行われなくなります。TTLとON/OFFという2つの軸が別々に存在するため、キャッシュ関連の環境変数を検索するときは「保持時間を変えたいのか」「書き込みそのものを止めたいのか」を先に切り分けておくと、目的の変数にすぐたどり着けます。

やり方

いずれも値は1に設定するだけです。シェルで直接設定するか、.claude/settings.jsonのenvブロックに書きます。

export DISABLE_PROMPT_CACHING_OPUS=1
claude

設定ファイルに書く場合は次の形になります(公式ドキュメントのサンプルに沿った例示です)。

{
  "env": {
    "DISABLE_PROMPT_CACHING_OPUS": "1",
    "DISABLE_PROMPT_CACHING_SONNET": "1"
  }
}

4つの変数の効き先は次のとおりです。

対象を1モデルファミリーだけに絞り込めるので、複数モデルを併用する構成でも他のモデルの挙動やコストをまったく変えずに検証できるのがこの4変数の要点です。

DISABLE_PROMPT_CACHING_HAIKUだけ「default Haiku model(既定のHaikuモデル)」という対象定義が付いています。公式ドキュメントによると、これはhaikuエイリアスが解決する先のモデルを指し、そのモデルが動く場所すべて(Haikuをメインモデルにしているセッションの会話部分も含む)でキャッシュを無効化します。廃止予定のANTHROPIC_SMALL_FAST_MODELでバックグラウンドモデルを指定していて、それがメインモデルと異なる場合もこの変数の対象です。逆に、別バージョンのHaikuを明示的にメインモデルへ指定しているときはこの変数の対象外で、そちらを無効化したいなら全体スイッチのDISABLE_PROMPT_CACHINGを使います。メインの会話まで対象にするこの挙動にはClaude Code v2.1.283以降が必要です。OpusとSonnetの変数にはこうした対象範囲の説明がなく、単に「Opusモデル」「Sonnetモデル」を対象にすると書かれているだけです。

設定できる場所は4種類

この4変数は、Claude Codeが起動時に読む環境変数の設定経路すべてに対応しています。シェルのexportのほかに、次の4つのファイルのenvブロックからも設定できます。

DISABLE_PROMPT_CACHING_OPUSなどの4変数は、リポジトリのチェックアウト先が勝手に制御すべきでない変数の除外リスト(CLAUDE_CONFIG_DIRやOpenTelemetry関連など)には含まれていません。そのため.claude/settings.jsonに書いてコミットすれば、チーム全員に同じキャッシュ無効化設定を配布できます。個人だけで試したいときは.claude/settings.local.jsonに書けば、gitignore対象になりチームには影響しません。

補足

全体無効化との優先順位

DISABLE_PROMPT_CACHING(モデルを指定しない全体スイッチ)を設定すると、モデル別の4変数より優先されます。つまりDISABLE_PROMPT_CACHING=1が立っている状態でDISABLE_PROMPT_CACHING_OPUSを追加しても意味を持ちません。モデル別に個別制御したいときは、全体スイッチを外した状態で対象の変数だけを設定します。

具体的には次の組み合わせになります。

上から2行目が実務でつまずきやすいところです。「Opusだけ無効化を強化したつもりが、実は全体スイッチが先に効いていて他のモデルも巻き込んで無効化していた」という設定ミスは、DISABLE_PROMPT_CACHINGが環境のどこか(シェルのプロファイルや管理者設定)で先に立っていないかをenv | grep DISABLE_PROMPT_CACHINGのように直接確認しないと気づけません。

この設定ミスを解消するときは、.claude/settings.jsonのenvブロックに書くだけで足ります。同じ変数がシェルと設定ファイルの両方にある場合は設定ファイル側の値が使われる仕様なので、シェルのプロファイルでDISABLE_PROMPT_CACHING=1が立っていても、プロジェクトの.claude/settings.jsonでDISABLE_PROMPT_CACHINGを0にすれば上書きできます。ただし管理者設定(managed settings)で同じ変数が設定されている場合は別です。managed settingsはユーザー設定・プロジェクト設定より優先されるため、ユーザー側で0を指定しても上書きできません。組織全体でキャッシュ無効化を配布する運用をしているなら、個々のプロジェクトのsettings.jsonでは変更できない前提になります。

真偽値の書き方

Claude Codeの真偽値系の環境変数は、1またはtrue(大文字小文字は問わない)で有効、0またはfalseで無効になるという共通ルールに従います。DISABLE_PROMPT_CACHING_OPUSなどのこの4変数もこのルールの対象で、0にすれば明示的に無効化を解除できます(変数自体を消す方法と同じ効果です)。

設定ファイル側に対応するキーはない

プロンプトキャッシュの保持時間を選ぶpromptCacheTtl・subagentPromptCacheTtlという設定キーは.claude/settings.jsonに用意されていますが、モデル別に無効化するための設定キーは公式のsettings-referenceには存在しません。無効化そのものは環境変数でしか制御できず、設定ファイルから触るならenvブロック経由で環境変数を書く形になります。

真偽値の共通ルールが適用されない変数もある

Claude Codeの環境変数には、0を含む「何か値が入っていれば有効」という特殊な扱いをするものがあります(DISABLE_TELEMETRYやDISABLE_ERROR_REPORTINGなど)。DISABLE_PROMPT_CACHING_OPUSなどのこの4変数はこの特殊扱いの対象には入っておらず、通常の真偽値ルール(1/trueで有効、0/falseで無効)がそのまま適用されます。似た名前の変数を並べて設定するときは、この特殊扱いの有無を混同しないようにします。

ワークフローのファンアウト待機との違いに注意

CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MSというワークフロー用の環境変数があります。同じプロンプトキャッシュの接頭辞を共有する複数のエージェントを同時に起動するとき、後発のエージェントを一定時間待たせてキャッシュを効かせる仕組みです。このドキュメントには「DISABLE_PROMPT_CACHINGを設定すると、エージェントは待機しなくなる」と明記されていますが、これは全体無効化のDISABLE_PROMPT_CACHINGについての記述で、モデル別のDISABLE_PROMPT_CACHING_OPUSなどにこの効果があるとは書かれていません。ワークフローのファンアウトで挙動が変わるのは全体スイッチを使ったときだけ、と区別しておく必要があります。

モデル別に無効化する場面

キャッシュを丸ごと止めると、どのモデルのコスト差なのかが分からなくなります。たとえばOpusだけDISABLE_PROMPT_CACHING_OPUSで切り、SonnetとHaikuはキャッシュを効かせたままにすれば、Opusのキャッシュ有無によるトークン課金の差だけを切り分けて計測できます。サブエージェントのモデル配分を役割ごとにOpus/Sonnet/Haikuへ振り分けている構成では、特定の役割(モデル)だけキャッシュ挙動を変えて検証したいケースがこれに当たります。

コスト面で見ると、キャッシュの読み込み(cacheRead)と書き込み(cacheWrite)は通常の入出力トークンとは別のレートで課金されます。modelPricing設定の契約レート上書きでもinput・outputとは別にcacheRead・cacheWriteをモデルごとに指定する仕様になっており、キャッシュ有無でコスト構造そのものが変わることが分かります。Opusのように単価が高いモデルだけキャッシュを切って、通常課金とキャッシュ課金のどちらが実際に安く付くかを自分の使い方で比較する、という検証にはこの4変数がそのまま使えます。

もう一つの使い道は、キャッシュ有無によるコスト差の実測です。プロンプトキャッシュはリクエストの先頭(prefix)が完全に一致したときだけ効く仕組みで、ファイル単位・セグメント単位のキャッシュは存在しません。プレフィックスのどこかが変わると、そこから先はまとめて再計算されるだけで、古い内容がそのまま返ってくるわけではありません。DISABLE_PROMPT_CACHING_OPUSで対象モデルだけキャッシュを止め、/usageでキャッシュ有無それぞれのコストを見比べれば、そのモデルでキャッシュがどれだけコストを下げているかを他のモデルへの影響なしに確認できます。

プロンプトキャッシュそのものの仕組みや、5分/1時間のTTLがどう課金に効くかはClaudeのプロンプトキャッシュの仕組みで扱っています。Claude Codeの利用上限(サブスクリプションのweekly limit等)への影響はプロンプトキャッシュはClaude Codeの利用上限をどう軽くするか、ワークフローのファンアウトでキャッシュがどう効くかはClaude Codeワークフローのプロンプトキャッシュの効き方に詳細があります。

Fableモデルを個別に扱う理由

DISABLE_PROMPT_CACHING_FABLEが対象にするFableは、Opus・Sonnet・Haikuとは別枠のモデルファミリーです。ANTHROPIC_DEFAULT_FABLE_MODELでfableエイリアスが解決するモデルIDを指定したり、サードパーティプロバイダーでの自動フォールバック対象として認識させたりする専用の環境変数群があり、/modelピッカーの表示名や対応capabilityも個別に設定できます。モデルの解決経路自体がOpus/Sonnetとは別立てなので、プロンプトキャッシュの無効化スイッチも同じ粒度で分かれていると考えると整理しやすくなります。

設定を戻すときの注意

無効化を解除するときは、変数を0にするか、変数そのものを未設定に戻します。シェルでexportした変数は、unset DISABLE_PROMPT_CACHING_OPUSで消してもそのシェルの現在のプロセスに反映されるだけで、Claude Code自体は環境変数を起動時に読むため、既に起動しているセッションには反映されません。.claude/settings.jsonのenvブロックで設定した場合は、ファイルを保存した時点で実行中のセッションにも新しい値が反映されますが、ファイルから変数の行そのものを削除したときだけは、次回起動まで無効化状態が残ります。「消したのに直らない」ときは、この2つの経路のどちらで設定したかを先に確認してください。同じ変数をシェルとsettings.jsonの両方に書いている場合は、設定ファイル側の値がシェルの値を上書きする点も合わせて確認します。

まとめ

DISABLE_PROMPT_CACHING_OPUS・_SONNET・_HAIKU・_FABLEの4変数を使えば、モデルファミリー単位でプロンプトキャッシュを個別に切れます。全体を止めるDISABLE_PROMPT_CACHINGが設定されていると4変数より優先される点、設定ファイル側に対応するキーが無く環境変数でしか触れない点、ワークフローのファンアウト待機に影響するのは全体スイッチだけである点の3つを押さえておけば、モデル別のキャッシュ検証で意図しない挙動に当たることは避けられます。

シェルでexportするか、.claude/settings.jsonのenvブロックに書くかは、個人の一時的な検証かチーム共有の設定かで使い分けます。個人の検証であれば.claude/settings.local.json、チーム全員に配りたい設定であれば.claude/settings.jsonに書いてバージョン管理に含めるのが、他の環境変数と同じ標準的な運用になります。