​

プロンプトキャッシュ

• Anthropic のプロンプトキャッシュ: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• OpenAI のプロンプトキャッシュ: https://developers.openai.com/api/docs/guides/prompt-caching
• OpenAI API のヘッダーとリクエスト ID: https://developers.openai.com/api/reference/overview
• Anthropic のリクエスト ID とエラー: https://platform.claude.com/docs/en/api/errors

​

主要な設定項目

​

cacheRetention（グローバル既定値、モデル別、およびエージェント別）

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long

agents:
  list:
    - id: "alerts"
      params:
        cacheRetention: "none"

1. agents.defaults.params（グローバル既定値 — すべてのモデルに適用）
2. agents.defaults.models["provider/model"].params（モデル別の上書き）
3. agents.list[].params（一致するエージェント id。キーごとに上書き）

​

contextPruning.mode: "cache-ttl"

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

​

ハートビートによるウォーム維持

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

​

プロバイダーの挙動

​

Anthropic（直接 API）

• cacheRetention がサポートされています。
• Anthropic の API キー認証プロファイルでは、未設定時に Anthropic モデル参照へ cacheRetention: "short" を OpenClaw が初期設定します。
• Anthropic ネイティブ Messages レスポンスは cache_read_input_tokens と cache_creation_input_tokens の両方を公開するため、OpenClaw は cacheRead と cacheWrite の両方を表示できます。
• ネイティブ Anthropic リクエストでは、cacheRetention: "short" は既定の 5 分間のエフェメラルキャッシュに対応し、cacheRetention: "long" は直接の api.anthropic.com ホストでのみ TTL 1 時間へ引き上げられます。

​

OpenAI（直接 API）

• プロンプトキャッシュは、対応する最近のモデルでは自動です。OpenClaw がブロック単位のキャッシュマーカーを挿入する必要はありません。
• OpenClaw は、ターン間でキャッシュルーティングを安定させるために prompt_cache_key を使用し、直接の OpenAI ホストで cacheRetention: "long" が選ばれた場合にのみ prompt_cache_retention: "24h" を使用します。
• OpenAI のレスポンスは、usage.prompt_tokens_details.cached_tokens（または Responses API イベント上の input_tokens_details.cached_tokens）を通じてキャッシュ済みプロンプトトークンを公開します。OpenClaw はこれを cacheRead に対応付けます。
• OpenAI は別個の cache-write トークンカウンターを公開しないため、プロバイダーがキャッシュをウォームしている場合でも、OpenAI 経路では cacheWrite は 0 のままです。
• OpenAI は x-request-id、openai-processing-ms、x-ratelimit-* などの有用なトレースおよびレート制限ヘッダーを返しますが、キャッシュヒットの集計はヘッダーではなく usage ペイロードから取得するべきです。
• 実際には、OpenAI は Anthropic のような移動する完全履歴の再利用というより、初期接頭辞キャッシュのように振る舞うことがよくあります。安定した長い接頭辞のテキストターンでは、現在のライブプローブで 4864 キャッシュ済みトークン付近のプラトーに達することがあり、tool-heavy または MCP 形式のトランスクリプトでは、完全に同じ繰り返しでも 4608 キャッシュ済みトークン付近で頭打ちになることがよくあります。

​

Anthropic Vertex

• Vertex AI 上の Anthropic モデル（anthropic-vertex/*）は、直接の Anthropic と同じ方法で cacheRetention をサポートします。
• cacheRetention: "long" は、Vertex AI エンドポイント上で実際の 1 時間のプロンプトキャッシュ TTL に対応します。
• anthropic-vertex の既定のキャッシュ保持は、直接の Anthropic の既定値と一致します。
• Vertex リクエストは、プロバイダーが実際に受け取る内容にキャッシュ再利用が一致するよう、境界を考慮したキャッシュ整形を通じてルーティングされます。

​

Amazon Bedrock

• Anthropic Claude モデル参照（amazon-bedrock/*anthropic.claude*）は、明示的な cacheRetention の透過をサポートします。
• Anthropic 以外の Bedrock モデルは、実行時に cacheRetention: "none" へ強制されます。

​

OpenRouter Anthropic models

​

その他のプロバイダー

​

Google Gemini 直接 API

• 直接の Gemini トランスポート（api: "google-generative-ai"）は、上流の cachedContentTokenCount を通じてキャッシュヒットを報告します。OpenClaw はこれを cacheRead に対応付けます。
• 直接の Gemini モデルに cacheRetention が設定されると、OpenClaw は Google AI Studio 実行向けに system prompts の cachedContents リソースを自動的に作成、再利用、更新します。これは、キャッシュ済みコンテンツハンドルを事前に手動作成する必要がなくなったことを意味します。
• 既存の Gemini キャッシュ済みコンテンツハンドルは、設定済みモデル上で params.cachedContent（または旧式の params.cached_content）として引き続き渡せます。
• これは Anthropic/OpenAI のプロンプト接頭辞キャッシュとは別物です。Gemini では、OpenClaw はリクエストにキャッシュマーカーを注入するのではなく、プロバイダーネイティブの cachedContents リソースを管理します。

​

Gemini CLI JSON usage

• Gemini CLI の JSON 出力でも、stats.cached を通じてキャッシュヒットが表れることがあります。OpenClaw はこれを cacheRead に対応付けます。
• CLI が直接の stats.input 値を省略した場合、OpenClaw は stats.input_tokens - stats.cached から入力トークン数を導出します。
• これは usage の正規化にすぎません。OpenClaw が Gemini CLI に対して Anthropic/OpenAI 形式のプロンプトキャッシュマーカーを作成していることを意味するわけではありません。

​

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

• 安定した workspace project-context files は HEARTBEAT.md より前に順序付けされるため、 heartbeat の変動が安定した接頭辞を壊しません。
• この境界は Anthropic 系、OpenAI 系、Google、および CLI トランスポート整形全体に適用されるため、 すべての対応プロバイダーが同じ接頭辞安定性の恩恵を受けます。
• Codex Responses と Anthropic Vertex のリクエストは、 キャッシュ再利用がプロバイダーが実際に受け取る内容と一致するよう、 境界を考慮したキャッシュ整形を通じてルーティングされます。
• システムプロンプトのフィンガープリントは正規化され （空白、改行コード、フックによって追加されたコンテキスト、実行時 capability の順序）、 意味的に変化していないプロンプトがターン間で同じ KV/キャッシュを共有できるようにします。

​

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

• バンドルされた MCP ツールカタログは、tool registration の前に決定的にソートされるため、listTools() の順序変化で tools ブロックが揺らいで プロンプトキャッシュ接頭辞が壊れることを防ぎます。
• 永続化された画像ブロックを持つ旧式セッションでは、最新の 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 未満に保ちます。

​

キャッシュ診断

​

ライブ回帰テスト

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

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

​

Anthropic のライブ期待値

• cacheWrite による明示的なウォームアップ書き込みを期待します。
• Anthropic のキャッシュ制御は会話を通じてキャッシュブレークポイントを前進させるため、繰り返しターンでは会話履歴のほぼ全体が再利用されることを期待します。
• 現在のライブアサーションでも、安定パス、ツールパス、画像パスに対して高いヒット率しきい値を使用しています。

​

OpenAI のライブ期待値

• cacheRead のみを期待します。cacheWrite は 0 のままです。
• 繰り返しターンのキャッシュ再利用は、Anthropic のような移動する完全履歴の再利用ではなく、プロバイダー固有のプラトーとして扱います。
• 現在のライブアサーションでは、gpt-5.4-mini で観測されたライブ挙動に基づく保守的な下限チェックを使用しています:
  • 安定した接頭辞: cacheRead >= 4608、ヒット率 >= 0.90
  • ツールトランスクリプト: cacheRead >= 4096、ヒット率 >= 0.85
  • 画像トランスクリプト: cacheRead >= 3840、ヒット率 >= 0.82
  • MCP 形式トランスクリプト: cacheRead >= 4096、ヒット率 >= 0.85

• 安定した接頭辞: cacheRead=4864、ヒット率 0.966
• ツールトランスクリプト: cacheRead=4608、ヒット率 0.896
• 画像トランスクリプト: cacheRead=4864、ヒット率 0.954
• MCP 形式トランスクリプト: cacheRead=4608、ヒット率 0.891

• Anthropic は明示的なキャッシュブレークポイントと、移動する会話履歴の再利用を公開しています。
• OpenAI のプロンプトキャッシュも依然として正確な接頭辞に敏感ですが、ライブ Responses トラフィックで実際に再利用可能な接頭辞は、完全なプロンプトより早く頭打ちになることがあります。
• そのため、Anthropic と OpenAI を単一のプロバイダー横断パーセンテージしきい値で比較すると、誤った回帰判定が生じます。

​

diagnostics.cacheTrace 設定

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # 任意
    includeMessages: false # 既定値 true
    includePrompt: false # 既定値 true
    includeSystem: false # 既定値 true

• filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
• includeMessages: true
• includePrompt: true
• includeSystem: true

​

環境変数トグル（単発のデバッグ）

• OPENCLAW_CACHE_TRACE=1 はキャッシュトレースを有効にします。
• OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl は出力パスを上書きします。
• OPENCLAW_CACHE_TRACE_MESSAGES=0|1 は完全なメッセージペイロードの取得を切り替えます。
• OPENCLAW_CACHE_TRACE_PROMPT=0|1 はプロンプトテキストの取得を切り替えます。
• OPENCLAW_CACHE_TRACE_SYSTEM=0|1 はシステムプロンプトの取得を切り替えます。

​

確認すべき点

• キャッシュトレースイベントは JSONL で、session:loaded、prompt:before、stream:context、session:after などの段階的スナップショットを含みます。
• ターンごとのキャッシュトークン影響は、通常の usage 表示で cacheRead と cacheWrite を通じて確認できます（たとえば /usage full やセッション usage サマリー）。
• Anthropic では、キャッシュが有効なとき cacheRead と cacheWrite の両方を期待します。
• OpenAI では、キャッシュヒット時に cacheRead を期待し、cacheWrite は 0 のままであることを期待します。OpenAI は別個の cache-write トークンフィールドを公開しません。
• リクエストトレースが必要な場合は、リクエスト ID とレート制限ヘッダーをキャッシュメトリクスとは別に記録してください。OpenClaw の現在の cache-trace 出力は、生のプロバイダーレスポンスヘッダーではなく、プロンプト/セッション形状と正規化されたトークン usage に焦点を当てています。

​

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

• ほとんどのターンで cacheWrite が高い: 変動するシステムプロンプト入力を確認し、モデル/プロバイダーがキャッシュ設定をサポートしていることを検証してください。
• Anthropic で cacheWrite が高い: 多くの場合、キャッシュブレークポイントが毎回変化するコンテンツに当たっていることを意味します。
• OpenAI で cacheRead が低い: 安定した接頭辞が先頭にあること、繰り返される接頭辞が少なくとも 1024 トークンであること、同じ prompt_cache_key がキャッシュ共有すべきターン間で再利用されていることを検証してください。
• cacheRetention に効果がない: モデルキーが agents.defaults.models["provider/model"] に一致していることを確認してください。
• キャッシュ設定付きの Bedrock Nova/Mistral リクエスト: 実行時に none へ強制されるのが想定動作です。

• Anthropic
• Token Use and Costs
• Session Pruning
• Gateway Configuration Reference