プロンプトキャッシュ

プロンプトキャッシュを使用すると、モデルプロバイダーは変更されていないプロンプトのプレフィックス（システム/開発者向け指示、ツール定義、その他の安定したコンテキスト）をターン間で再利用でき、リクエストごとに再処理する必要がなくなります。これにより、コンテキストが繰り返される長時間セッションで、トークンコストとレイテンシーが削減されます。

OpenClaw は、上流 API がこれらのカウンターを公開している場合、プロバイダーの使用量を cacheRead と cacheWrite に正規化します。使用量の概要（/status など）は、ライブセッションのスナップショットにキャッシュカウンターがない場合、最後のトランスクリプト使用量エントリにフォールバックします。ライブ値が 0 でない場合は、常にフォールバックより優先されます。

プロバイダーの参考資料:

• Anthropic のプロンプトキャッシュ
• OpenAI のプロンプトキャッシュ

主要な設定項目

cacheRetention

値: "none" | "short" | "long"。グローバルデフォルト、モデル単位、エージェント単位で設定できます。

agents:  defaults:    params:      cacheRetention: "long" # none | short | long    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "short" # このモデルではグローバルデフォルトを上書き  list:    - id: "alerts"      params:        cacheRetention: "none" # このエージェントでは両方のデフォルトを上書き

マージ順序（後のものが優先）:

1. agents.defaults.params - すべてのモデルに対するグローバルデフォルト
2. agents.defaults.models["provider/model"].params - モデル単位の上書き
3. agents.list[].params - エージェント ID で照合される、エージェント単位の上書き

ソース: src/agents/embedded-agent-runner/extra-params.ts（resolveExtraParams）。

contextPruning.mode: "cache-ttl"

キャッシュの TTL 期間が経過した後、古いツール結果のコンテキストを削除します。これにより、アイドル後のリクエストで過大な履歴が再びキャッシュされることを防ぎます。

agents:  defaults:    contextPruning:      mode: "cache-ttl"      ttl: "1h"

完全な動作については、セッションのプルーニングを参照してください。

Heartbeat によるウォーム状態の維持

Heartbeat はキャッシュ期間をウォーム状態に保ち、アイドル期間後に繰り返されるキャッシュ書き込みを削減できます。グローバル（agents.defaults.heartbeat）またはエージェント単位（agents.list[].heartbeat）で設定できます。

agents:  defaults:    heartbeat:      every: "55m"

プロバイダーの動作

Anthropic（直接 API および Vertex AI）

• cacheRetention は、anthropic および anthropic-vertex プロバイダーでサポートされます。また、cacheRetention が明示的に設定されている場合は、amazon-bedrock 上の Claude モデルと、カスタムの anthropic-messages 互換エンドポイントでもサポートされます。
• 未設定の場合、OpenClaw は直接 Anthropic に対して cacheRetention: "short" を初期値として設定します（anthropic および anthropic-vertex プロバイダーのみ。他の Anthropic 系ルートでは明示的な値が必要です）。
• ネイティブの Anthropic Messages レスポンスでは cache_read_input_tokens と cache_creation_input_tokens が公開され、それぞれ cacheRead と cacheWrite にマッピングされます。
• cacheRetention: "short" はデフォルトの 5 分間のエフェメラルキャッシュにマッピングされます。cacheRetention: "long" を明示的に設定すると、1 時間の TTL（cache_control: { type: "ephemeral", ttl: "1h" }）を要求します。暗黙的または環境変数による長期保持（明示的な cacheRetention なしで OPENCLAW_CACHE_RETENTION=long）が 1 時間の TTL にアップグレードされるのは、api.anthropic.com または Vertex AI（aiplatform.googleapis.com / *-aiplatform.googleapis.com）ホストのみです。他のホストでは 5 分間のキャッシュが維持されます。

ソース: src/agents/anthropic-payload-policy.ts（resolveAnthropicEphemeralCacheControl、isLongTtlEligibleEndpoint）。

OpenAI（直接 API）

• サポート対象の新しいモデルではプロンプトキャッシュが自動的に行われます。OpenClaw はブロック単位のキャッシュマーカーを挿入しません。
• OpenClaw は、ターン間でキャッシュルーティングを安定させるために prompt_cache_key を送信します。直接の api.openai.com ホストでは、これは自動的に行われます。OpenAI 互換プロキシ（oMLX、llama.cpp、カスタムエンドポイント）で有効にするには、モデル設定に compat.supportsPromptCacheKey: true が必要です。プロキシに対して自動検出されることはありません。
• prompt_cache_retention: "24h" が追加されるのは、cacheRetention: "long" が選択され、解決されたエンドポイントがキャッシュキーと長期保持の両方をサポートしている場合のみです（compat.supportsLongCacheRetention、デフォルトは true。Together AI と Cloudflare の互換プロファイルでは無効）。cacheRetention: "none" は両方のフィールドを抑制します。
• キャッシュヒットは、usage.prompt_tokens_details.cached_tokens（Chat Completions）または input_tokens_details.cached_tokens（Responses API）を通じて公開され、cacheRead にマッピングされます。
• Responses API のペイロードでは input_tokens_details.cache_write_tokens が公開される場合もあり、cacheWrite にマッピングされ、モデルのキャッシュ書き込みレートで料金が計算されます。このフィールドが省略された Responses ペイロードでは、cacheWrite は 0 のままです。OpenAI の Chat Completions API は cache_write_tokens カウンターを文書化も出力もしていませんが、OpenClaw は別個の書き込み数を報告する OpenRouter 互換および DeepSeek 形式のプロキシに対応するため、そこでも prompt_tokens_details.cache_write_tokens を読み取ります。
• 実際には、OpenAI は Anthropic の移動する全履歴の再利用よりも、初期プレフィックスキャッシュに近い動作をします。以下の OpenAI のライブ動作の想定を参照してください。

Amazon Bedrock

• Anthropic Claude のモデル参照（amazon-bedrock/*anthropic.claude*、および AWS システム推論プロファイルのプレフィックス us./eu./global.anthropic.claude*）は、明示的な cacheRetention の引き渡しをサポートします。
• Anthropic 以外の Bedrock モデル（例: amazon.nova-*）は、設定された cacheRetention 値にかかわらず、実行時にはキャッシュ保持なしとして解決されます。
• 不透明な Bedrock アプリケーション推論プロファイル ARN（claude を含まないプロファイル ID）も、ARN だけではモデルファミリーを推測できないため、cacheRetention が明示的に設定されていない限り、キャッシュ保持なしとして解決されます。

OpenRouter

openrouter/anthropic/* モデル参照の場合、OpenClaw はシステム/開発者プロンプトブロックに Anthropic の cache_control マーカーを挿入します。ただし、リクエストの送信先が検証済みの OpenRouter ルート（デフォルトエンドポイント上の openrouter、または openrouter.ai に解決される任意のプロバイダー/ベース URL）のままである場合に限ります。モデルの送信先を任意の OpenAI 互換プロキシ URL に変更すると、この挿入は停止します。

contextPruning.mode: "cache-ttl" は、openrouter/anthropic/*、openrouter/deepseek/*、openrouter/moonshot/*、openrouter/moonshotai/*、openrouter/zai/* のモデル参照で使用できます。これらのルートは、OpenClaw がマーカーを挿入しなくても、プロバイダー側でプロンプトキャッシュを処理するためです。

ソース: extensions/openrouter/index.ts（OPENROUTER_CACHE_TTL_MODEL_PREFIXES）。

OpenRouter での DeepSeek キャッシュの構築はベストエフォートで、数秒かかることがあります。直後のフォローアップリクエストでは、依然として cached_tokens: 0 と表示される場合があります。少し待ってから同じプレフィックスのリクエストを繰り返し、usage.prompt_tokens_details.cached_tokens をキャッシュヒットのシグナルとして使用して検証してください。

Google Gemini（直接 API）

• Gemini の直接トランスポート（api: "google-generative-ai"）は、上流の cachedContentTokenCount を通じてキャッシュヒットを報告し、cacheRead にマッピングされます。
• 対象モデルファミリー: gemini-2.5* および gemini-3*（このプレフィックス一致に含まれない Live/プレビューのバリアント、たとえば gemini-live-2.5-flash-preview は除外）。
• 対象モデルに cacheRetention が設定されている場合、OpenClaw はシステムプロンプト用の cachedContents リソースを自動的に作成、再利用、更新します。キャッシュ済みコンテンツのハンドルを手動で指定する必要はありません。TTL は cacheRetention: "short" の場合は 300s、"long" の場合は 3600s です。
• 既存の Gemini キャッシュ済みコンテンツのハンドルを params.cachedContent（または旧形式の params.cached_content）として渡すこともできます。明示的なハンドルを指定すると、自動キャッシュ管理パスは完全にスキップされます。
• これは Anthropic/OpenAI のプロンプトプレフィックスキャッシュとは異なります。OpenClaw はインラインキャッシュマーカーを挿入する代わりに、Gemini 用のプロバイダーネイティブな cachedContents リソースを管理します。

ソース: src/agents/embedded-agent-runner/google-prompt-cache.ts。

CLI ハーネスプロバイダー（Claude Code、Gemini CLI）

JSONL 使用量イベント（jsonlDialect: "claude-stream-json" または "gemini-stream-json"）を出力する CLI バックエンドは、共有の使用量パーサーを通ります。このパーサーは、cacheRead にマッピングされる単純な cached カウンターを含む、複数のフィールド名のバリアントを認識します。CLI の JSON ペイロードで直接の入力トークンフィールドが省略されている場合、OpenClaw はそれを input_tokens - cached として算出します。これは使用量の正規化のみを行うものであり、これらの CLI 駆動モデル向けに Anthropic/OpenAI 形式のプロンプトキャッシュマーカーを作成するものではありません。

ソース: src/agents/cli-output.ts（toCliUsage）。

その他のプロバイダー

プロバイダーが上記のいずれのキャッシュモードもサポートしていない場合、cacheRetention は効果を持ちません。

システムプロンプトのキャッシュ境界

OpenClaw は、内部のキャッシュプレフィックス境界で、システムプロンプトを 安定したプレフィックス と 変動するサフィックス に分割します。境界より前のコンテンツ（ツール定義、Skills のメタデータ、ワークスペースファイル）は、ターン間でバイト単位に同一となるように順序付けられます。境界より後のコンテンツ（例: HEARTBEAT.md、実行時タイムスタンプ、その他のターン単位のメタデータ）は、キャッシュされたプレフィックスを無効化せずに変更できます。

主な設計上の選択:

• 安定したワークスペースのプロジェクトコンテキストファイルは HEARTBEAT.md より前に配置されるため、Heartbeat による変動で安定したプレフィックスが無効化されません。
• この境界は Anthropic 系、OpenAI 系、Google、CLI のトランスポート整形全体に適用されるため、サポートされるすべてのプロバイダーが同じプレフィックスの安定性から恩恵を受けます。
• Codex Responses と Anthropic Vertex のリクエストは、境界を考慮したキャッシュ整形を通じてルーティングされるため、キャッシュの再利用がプロバイダーに実際に送信される内容と一致します。
• システムプロンプトのフィンガープリントは正規化されます（空白、改行、フックによって追加されたコンテキスト、実行時機能の順序）。これにより、意味的に変更されていないプロンプトは、ターン間でキャッシュを共有できます。

設定またはワークスペースの変更後に予期しない cacheWrite の急増が見られる場合は、その変更がキャッシュ境界より前か後かを確認してください。変動するコンテンツを境界より後に移動する（または安定化する）ことで、通常は問題を解決できます。

OpenClaw のキャッシュ安定性ガード

• バンドルされた MCP ツールカタログは、ツール登録前に決定論的にソートされます（まずサーバー名、次にツール名）。そのため、listTools() の順序が変わってもツールブロックが変動せず、プロンプトキャッシュのプレフィックスが無効化されません。
• 永続化された画像ブロックを含む旧セッションでは、直近 3 回の完了済みターン がそのまま保持されます（画像を含むターンだけでなく、すべての完了済みターンを数えます）。それより古い処理済み画像ブロックはテキストマーカーに置き換えられるため、画像を多用するフォローアップで大きな古いペイロードが繰り返し再送信されることを防ぎます。

調整パターン

混合トラフィック（推奨デフォルト）

メインエージェントには長期的な基準設定を維持し、バースト的な通知エージェントではキャッシュを無効にします。

agents:  defaults:    model:      primary: "anthropic/claude-opus-4-6"    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "long"  list:    - id: "research"      default: true      heartbeat:        every: "55m"    - id: "alerts"      params:        cacheRetention: "none"

コスト優先の基準設定

• 基準となる cacheRetention: "short" を設定します。
• contextPruning.mode: "cache-ttl" を有効にします。
• ウォームキャッシュの恩恵を受けるエージェントに限り、Heartbeat の間隔を TTL より短く保ちます。

ライブ回帰テスト

OpenClaw は、繰り返されるプレフィックス、ツールターン、画像ターン、MCP 形式のツールトランスクリプト、Anthropic のキャッシュなし制御を対象とする、統合ライブキャッシュ回帰ゲートを実行します。

• src/agents/live-cache-regression.live.test.ts
• src/agents/live-cache-regression-runner.ts
• src/agents/live-cache-regression-baseline.ts

次のコマンドで実行します。

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

ベースラインファイルには、直近で観測されたライブ数値と、テストが確認するプロバイダー固有の回帰下限値が保存されます。各実行では、実行ごとに新しいセッション ID とプロンプト名前空間を使用するため、以前のキャッシュ状態が現在のサンプルを汚染しません。Anthropic と OpenAI では判定方法が異なります。Anthropic で下限値を下回ると重大な回帰としてテストが失敗しますが、OpenAI で下限値を下回った場合は監視のみ（警告として記録され、実行は失敗しません）です。プロバイダー間で単一の共通しきい値を共有することはありません。

Anthropic のライブ動作の想定

• cacheWrite による明示的なウォームアップ書き込みが行われることを想定してください。
• Anthropic のキャッシュ制御では会話の進行に伴ってキャッシュのブレークポイントが移動するため、ターンを繰り返すと履歴のほぼ全体が再利用されることを想定してください。
• 安定、ツール、画像、MCP 形式の各レーンに設定されたベースライン下限値は、厳格なリグレッションゲートです。

OpenAI のライブ環境での想定

• cacheRead のみを想定してください。Chat Completions では cacheWrite は 0 のままです。
• ターンを繰り返した際のキャッシュ再利用は、Anthropic のように移動しながら履歴全体を再利用する動作ではなく、プロバイダー固有の上限到達として扱ってください。
• 下限値は監視専用です（未達はテスト失敗ではなく警告として記録されます）。gpt-5.4-mini で観測されたライブ動作に基づいています。

直近で観測されたベースライン値（live-cache-regression-baseline.ts より）は、安定したプレフィックスが cacheRead=4864、ヒット率 0.966、ツールトランスクリプトが cacheRead=4608、ヒット率 0.896、画像トランスクリプトが cacheRead=4864、ヒット率 0.954、MCP 形式のトランスクリプトが cacheRead=4608、ヒット率 0.891 でした。

アサーションが異なる理由：Anthropic は明示的なキャッシュのブレークポイントと、移動しながら会話履歴を再利用する仕組みを公開しています。一方、OpenAI のライブトラフィックで実際に再利用可能なプレフィックスは、プロンプト全体より前の段階で上限に達する場合があります。2 つのプロバイダーを単一のプロバイダー横断パーセンテージしきい値で比較すると、誤ったリグレッション判定が発生します。

diagnostics.cacheTrace の設定

diagnostics:  cacheTrace:    enabled: true    filePath: "~/.openclaw/logs/cache-trace.jsonl" # 任意    includeMessages: false # デフォルトは true    includePrompt: false # デフォルトは true    includeSystem: false # デフォルトは true

デフォルト値：

環境変数による切り替え（一時的なデバッグ）

確認する項目

• キャッシュトレースイベントは JSONL 形式で、session:loaded、prompt:before、stream:context、session:after などの段階別スナップショットを含みます。
• ターンごとのキャッシュトークンへの影響は通常の使用量表示で確認できます。cacheRead と cacheWrite は、/usage tokens、/status、セッション使用量の概要、カスタムの messages.usageTemplate レイアウトに表示されます。
• Anthropic では、キャッシュが有効な場合に cacheRead と cacheWrite の両方が記録されることを想定してください。
• OpenAI では、キャッシュヒット時に cacheRead が記録されることを想定してください。cacheWrite は、それを含む Responses API ペイロードでのみ設定されます（上記の OpenAI を参照）。
• OpenAI は、x-request-id、openai-processing-ms、x-ratelimit-* などのトレース用ヘッダーやレート制限ヘッダーも返します。これらはリクエストの追跡に使用できますが、キャッシュヒットの集計にはヘッダーではなく使用量ペイロードを使用してください。

クイックトラブルシューティング

• ほとんどのターンで cacheWrite が高い：変動するシステムプロンプト入力がないか確認し、モデルまたはプロバイダーがキャッシュ設定をサポートしていることを検証してください。
• Anthropic で cacheWrite が高い：キャッシュのブレークポイントが、リクエストごとに変化するコンテンツ上に設定されていることがよくあります。
• OpenAI の cacheRead が低い：安定したプレフィックスが先頭にあり、繰り返されるプレフィックスが少なくとも 1024 トークンあり、キャッシュを共有すべきターンで同じ prompt_cache_key が再利用されていることを確認してください。
• cacheRetention の効果がない：モデルキーが agents.defaults.models["provider/model"] と一致していることを確認してください。
• キャッシュ設定を含む Bedrock Nova リクエスト：想定どおりです。実行時にはキャッシュ保持なしとして解決されます。

関連ドキュメント：

• Anthropic
• トークン使用量とコスト
• セッションのプルーニング
• Gateway 設定リファレンス

関連項目

• トークン使用量とコスト
• API の使用量とコスト