OpenClawのプロンプトキャッシュ設定：コスト削減と応答速度向上

長いチャットセッションを続けていると、同じようなシステム指示や背景情報を何度も送ることになり、トークンコストが積み重なって驚くことがありますよね。また、入力が長くなるほどレスポンスまでの待ち時間も増えてしまい、開発のリズムが崩れてしまうこともあるでしょう。

Prompt caching を利用すると、モデルプロバイダーは変更のないプロンプトの接頭辞（通常はシステム指示や安定したコンテキストなど）を、ターンの枠を超えて再利用できるようになります。最初のマッチするリクエストがキャッシュを書き込み（cacheWrite）、それ以降のマッチするリクエストがそのキャッシュを読み取る（cacheRead）仕組みです。

これが重要な理由は、トークンコストの削減、レスポンスの高速化、そして長時間のセッションにおけるパフォーマンスの安定化にあります。キャッシュがない場合、入力の大部分が変わっていなくても、繰り返されるプロンプトに対して毎回フルでコストを支払うことになってしまいます。

このページでは、プロンプトの再利用とトークンコストに影響を与える、キャッシュ関連の設定項目について解説します。

Anthropic の料金詳細は、こちらを参照してください： https://docs.anthropic.com/docs/build-with-claude/prompt-caching

主要な設定項目

`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"

設定の適用順序（マージ順序）：

agents.defaults.params (グローバルデフォルト — すべてのモデルに適用)
agents.defaults.models["provider/model"].params (モデル別の設定)
agents.list[].params (一致するエージェント ID。キー単位で上書き)

レガシーな `cacheControlTtl`

以前の形式の値も引き続き受け入れられ、以下のようにマッピングされます：

5m -> short
1h -> long

新しい設定では cacheRetention を使うのがおすすめです。

`contextPruning.mode: "cache-ttl"`

キャッシュの TTL ウィンドウが過ぎた後に古い tool-result コンテキストを削除します。これにより、アイドル後のリクエストで肥大化した履歴を再キャッシュすることを防ぎます。

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

詳細な動作については Session Pruning を確認してください。

Heartbeat によるウォームアップ

Heartbeat 機能を使うと、キャッシュウィンドウをアクティブに保ち、アイドル時間後の繰り返しのキャッシュ書き込みを減らすことができます。

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

エージェントごとの heartbeat は agents.list[].heartbeat で設定可能です。

プロバイダーごとの動作

Anthropic (直接 API)

cacheRetention をサポートしています。
Anthropic の API-key 認証プロファイルを使用している場合、未設定の Anthropic モデル参照に対して OpenClaw は cacheRetention: "short" を初期値として設定します。

Amazon Bedrock

Anthropic Claude のモデル参照 (amazon-bedrock/*anthropic.claude*) は、明示的な cacheRetention のパススルーをサポートしています。
Anthropic 以外の Bedrock モデルは、実行時に強制的に cacheRetention: "none" となります。

OpenRouter の Anthropic モデル

openrouter/anthropic/* のモデル参照では、OpenClaw がシステム/デベロッパープロンプトのブロックに Anthropic の cache_control を挿入し、プロンプトキャッシュの再利用率を高めます。

その他のプロバイダー

プロバイダーがこのキャッシュモードをサポートしていない場合、cacheRetention を設定しても効果はありません。

チューニングのパターン

混合トラフィック (推奨されるデフォルト)

メインのエージェントには長期間のベースラインを維持し、頻繁に発生する通知用エージェントではキャッシュを無効にする構成です。

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" を有効にします。
キャッシュを維持するメリットがあるエージェントに対してのみ、TTL より短い間隔で heartbeat を設定します。

キャッシュの診断

OpenClaw は、組み込みエージェントの実行用に専用のキャッシュトレース診断機能を提供しています。

`diagnostics.cacheTrace` 設定

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional
    includeMessages: false # default true
    includePrompt: false # default true
    includeSystem: false # default 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 full やセッション使用状況のサマリー）の cacheRead および cacheWrite で確認できます。

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

ほとんどのターンで cacheWrite が高い場合：システムプロンプトに入力される値が頻繁に変わっていないか確認し、モデルやプロバイダーがキャッシュ設定をサポートしているか再確認してください。
cacheRetention の効果がない場合：モデルのキーが agents.defaults.models["provider/model"] と正確に一致しているか確認してください。
Bedrock の Nova/Mistral リクエストでキャッシュ設定をしている場合：実行時に強制的に none に設定されるのが正常な動作です。

次のステップ

Anthropic プロバイダーの設定を確認して、具体的な API 連携を始めましょう。
トークン使用量とコストを詳しく見て、予算管理を最適化しましょう。

セットアップで困ったときは、AI Setup Assistant に相談してください。

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。