プロンプトキャッシング — 概念と Claude Code での動作

更新 2026-08-10 5分で読めます GitHub で編集 ↗

プロンプトキャッシングは、リクエストの 前部分 (接頭辞) が直前のリクエストと同一のとき、その部分を再処理せずに再利用する API 機能です。キャッシュから読み込んだトークンは基本入力単価の 0.1 倍で課金されるため、繰り返されるコンテキスト (システムプロンプト、プロジェクト指示、対話履歴) が大きいほど削減効果が大きくなります。MoAI-ADK トークノミクスの「コンテキストダイエット」が常時ロードコンテキストを減らす側だとすれば、プロンプトキャッシングは残ったコンテキストを安く再利用する側です。

プラットフォームの基礎
プラットフォーム層の背景についてはプロンプトキャッシュを参照してください。MoAI-ADK としての説明はこのページです。

情報
やさしいたとえ — 毎ターン、モデルは対話全体を最初から読み直します。キャッシングは「前部分はさっき読んだそのままですね」と飛ばすしおりです。前部分が一文字でも変われば、しおりが無効になってその地点から読み直します。

核心概念 (API 共通)

接頭辞マッチング: キャッシュヒットには、ブレークポイントまでの内容 (ツール定義・システムプロンプト・メッセージ履歴を含む) が 100% 同一である必要があります。空白 1 つ違ってもその地点以降はすべて再計算されます。
価格倍率 (基本入力単価に対して): キャッシュ書き込み 5 分 TTL 1.25 倍 · 1 時間 TTL 2 倍 · キャッシュ読み込み 0.1 倍。
TTL (寿命): デフォルト 5 分、オプション 1 時間。TTL 内で再利用されるたびに寿命が無料で延長されます。
モデル別の最小キャッシュトークン: これより短い接頭辞はキャッシュされません (エラーなしで通常処理)。例: Fable 5 = 512、Opus 5・Sonnet 5 = 1,024、 Opus 4.7 = 2,048、Haiku 4.5 = 4,096 トークン。

Claude Code ユーザーなら — キャッシングは自動です

Claude Code はプロンプトキャッシングを 自動で管理します。cache_control を直接設定する必要も、設定する方法もありません。公式ドキュメント基準の動作は次のとおりです:

TTL 自動選択: サブスクリプションプラン (Pro/Max/Team/Enterprise) では 1 時間 TTL を自動要求します (プラン料金に含まれるため追加費用なし)。API キー・クラウドプロバイダー経由のときはデフォルト 5 分で、ENABLE_PROMPT_CACHING_1H=1 で 1 時間をオプトインできます。
環境変数制御: FORCE_PROMPT_CACHING_5M=1 (5 分強制)、 DISABLE_PROMPT_CACHING=1 (全体無効 — デバッグ用途以外は非推奨)、モデル別の DISABLE_PROMPT_CACHING_OPUS など。
リクエスト構成の最適化: Claude Code は変わりにくい内容 (システムプロンプト → プロジェクトコンテキスト → 対話) が前に来るようにリクエストを並べ、接頭辞ヒット率を高めます。

キャッシュを無効化する行動 (1 ターン遅く・高くなる)

モデル切替 (/model) · effort 変更 (/effort) — モデル・effort ごとにキャッシュが分離されています
MCP サーバーの接続/切断 (ツール定義が接頭辞にロードされている場合)
ツール全体の拒否 (deny) ルールの追加/削除
/compact (対話履歴が要約に置き換わる) · Claude Code アップグレード後の最初のターン

キャッシュを保持する行動

リポジトリファイルの編集 (読むときだけ対話に追加される) · スキル/コマンドの呼び出し · 権限モードの切替 · /rewind (すでにキャッシュされた接頭辞に戻る) · CLAUDE.md の途中修正 (キャッシュは保持されるが 変更も適用されない — 次の /clear・再起動で反映)

ヒット率の確認

応答の cache_creation_input_tokens (書き込み) / cache_read_input_tokens (読み込み) の比率が指標です — 読み込みが高いほどうまく動作中。
MoAI statusline の cache_hit セグメントでセッション中のリアルタイム確認が可能です。
書き込みがターンごとに高いままなら、上の「無効化する行動」のいずれかが接頭辞を変えているというサインです。

API を直接呼び出す場合 (参考)

以下は Anthropic API を直接呼び出す開発者にのみ該当する使用例です。Claude Code ユーザーは該当しません。

python

# API 直接呼び出し: 安定したシステムプロンプトにキャッシュブレークポイントを配置
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "安定したシステムプロンプト...",
        "cache_control": {"type": "ephemeral", "ttl": "1h"}
    }],
    messages=[{"role": "user", "content": user_query}]
)

原則は 1 つです: ブレークポイントは、毎リクエスト変わるデータ (質問、タイムスタンプ) の前の最後の安定ブロックに置きます。損益分岐はリクエスト 2 個 — 最初のリクエストの書き込みプレミアムは TTL 内の 2 番目のリクエストの 0.1 倍読み込みで回収されます。

MoAI が関与する範囲

この軸では何もありません。MoAI はプロンプトキャッシングの設定を提供せず、独自に cache_control を注入することもありません。Claude Code セッションのキャッシングは上のセクションのとおりランタイムが自動管理し、MoAI は介入できません — セッションのキャッシュ挙動を変える MoAI 側のスイッチは存在しません。

GLM バックエンド: z.ai (GLM) はコンテンツ類似度ベースの 暗黙的キャッシングを使い、これもプロバイダー側が自動で管理します。

要約

Claude Code ユーザー: 何も設定する必要なし。モデル/effort の切替と /compact を作業の合間の自然な境界でのみ行えば、ヒット率が保たれます。
API 直接呼び出し者: 安定ブロックにブレークポイント、リクエスト 2 個以上のときのみ 1 時間 TTL。
モニタリング: statusline cache_hit セグメント + cache_read/creation トークン比率。

出典 (公式ドキュメント):

How Claude Code uses prompt caching — 自動管理、TTL 自動選択、無効化/保持行動、環境変数
Prompt caching (API) — cache_control、価格倍率、モデル別の最小トークン
Manage costs effectively — Claude Code の自動コスト最適化