OpenClaw v2026.3.13は、OpenAIトークンコスト削減のためのエージェントごとのcacheRetention設定を追加しました。

v2026.3.13での変更点

OpenClawバージョン2026.3.13では、エージェントごとのエントリに対してparams.cacheRetentionの適切な設定検証が追加されました。これにより、openclaw.json設定ファイルで宣言的にキャッシュ保持期間を設定できるようになりました。

デフォルトキャッシュ動作の問題点

OpenAIはAPIでprompt_cache_retention: "24h"を介して拡張プロンプトキャッシュ保持（24時間）をサポートしており、デフォルトの5〜10分ではなく24時間プロンプトプレフィックスをキャッシュします。キャッシュされた入力トークンは50%オフで課金されます。

10分を超えるハートビートサイクルでエージェントを実行している場合（ソースでは「基本的に全員」と記載）、各ターン間でキャッシュが完全に冷えてしまいます。これは、すべてのハートビートで入力コンテキスト全体に対して全額を支払っていることを意味します。

ソースでは、GPT-5.2で15のエージェントを60〜90分ごとのハートビートで実行するセットアップが説明されており、すべてのハートビートが確実にコールドスタートでした。システムプロンプト、ブートストラップコンテキスト、HEARTBEAT.md、AGENTS.md、SOUL.md、ツール定義など、すべてがキャッシュがハートビート間のギャップで期限切れになるため、各サイクルで全額で再送信されていました。

設定方法

これでopenclaw.jsonでキャッシュ保持を設定できます：

{
  "agents": {
    "list": [
      {
        "agentId": "my-agent",
        "params": {
          "cacheRetention": "long"
        }
      }
    ]
  }
}

"long"値は、pi-aiライブラリを介してOpenAIのprompt_cache_retention: "24h"にマッピングされます。

重要な注意点：ランタイムパッチが必要

OpenClawのresolveCacheRetention()関数には、デフォルトでOpenAIプロバイダーをブロックするガード節があります。AnthropicとBedrockのみが許可されます。そのため、設定が行われていても、値はAPIに到達する前にフィルタリングされます。

これを機能させるには、issue #27515のランタイムパッチが必要です。このパッチは、ガード節の許可プロバイダーリストにOpenAIを追加します。設定とパッチの両方がなければ、何も起こりません。

ソースの著者は、数週間パッチを適用していたが設定値を設定していなかったと指摘しています。つまり、パッチはextraParams?.cacheRetention !== void 0をチェックし、undefinedを取得し、それでもOpenAIをブロックしていました。設定なしではパッチは何もしていなかったのです。

コスト削減の可能性

15のエージェントがハートビートを実行し、各ターンで約128K〜170Kの入力トークンを送信する場合：

• 24時間キャッシュなし：すべての入力トークンの100%が全額で課金され、すべてのターンで発生。キャッシュはハートビート間の約60〜90分のギャップで消滅。
• 24時間キャッシュあり：安定したプレフィックス（システムプロンプト、エージェント設定、ツール定義など、通常入力の80〜90%）がハートビート間でキャッシュされ続ける。これらのトークンは半額で課金される。

1営業日中に15のエージェントを実行するシステムでは、入力トークンの大部分が全額から半額に移行する数百のハートビートサイクルが発生します。入力コストの削減効果は急速に増大します。