セッションプルーニング (削減)

​

実行のタイミング

• mode: "cache-ttl" が有効で、そのセッションの直前の Anthropic 呼び出しから ttl 以上の時間が経過している場合に実行されます。
• その回のリクエストでモデルに送信されるメッセージ群にのみ影響します。
• Anthropic API（および OpenRouter 経由の Anthropic モデル）への呼び出し時のみ有効です。
• モデルの cacheRetention ポリシー（short = 5分, long = 1時間）に合わせて ttl を設定すると、最も効果的です。
• プルーニングが実行されると TTL ウィンドウがリセットされ、再び ttl が経過するまでは以降のリクエストでもキャッシュが維持されます。

​

スマートデフォルト (Anthropic)

• OAuth または setup-token プロファイルを使用する場合: cache-ttl プルーニングが有効になり、ハートビート間隔が 1h に設定されます。
• API キー プロファイルを使用する場合: cache-ttl プルーニングが有効になり、ハートビート間隔が 30m、Anthropic モデルの cacheRetention がデフォルトで "short" に設定されます。
• これらの値を構成ファイルで明示的に設定している場合、OpenClaw はそれらの値を上書きしません。

​

導入のメリット (コストとキャッシュ挙動)

• なぜプルーニングが必要か: Anthropic のプロンプトキャッシュは TTL（有効期間）内でのみ有効です。セッションが TTL を超えてアイドル状態になると、次にリクエストを送る際に、事前にトリミングを行わない限りプロンプト全体が再キャッシュ（課金対象）されてしまいます。
• コスト削減効果: TTL 経過後の最初の回において、プルーニングにより cacheWrite のサイズを削減できます。
• TTL リセットの意味: プルーニングが実行されるとキャッシュの有効期間がリセットされるため、その後の連続したリクエストでは、履歴全体を再キャッシュすることなく、新しくキャッシュされたプロンプトを再利用できます。
• 注意点: プルーニング自体がトークンを増やしたり、コストを「二重に」発生させたりすることはありません。あくまで TTL 経過後の最初のリクエストでキャッシュされる内容を調整するだけです。

​

削減の対象となるもの

• toolResult メッセージ（ツールの実行結果）のみが対象です。
• ユーザーやアシスタントのメッセージが変更されることは ありません。
• 直近の keepLastAssistants 件のアシスタントメッセージは保護され、それ以降のツール結果はプルーニングされません。
• 基準を満たす十分な数のアシスタントメッセージがない場合、プルーニングはスキップされます。
• 画像ブロック を含むツールの結果は、スキップ（トリミングや消去の対象外）されます。

​

コンテキストウィンドウの推定

1. models.providers.*.models[].contextWindow の上書き設定。
2. モデルカタログに定義された contextWindow。
3. デフォルト値の 200000 トークン。

​

モード

​

cache-ttl

• 直前の Anthropic 呼び出しから ttl (デフォルト 5m) 以上経過している場合にのみ実行されます。
• 実行時の挙動: 後述の「ソフトトリム」と「ハードクリア」を行います。

​

ソフトプルーニング vs ハードプルーニング

• ソフトトリム (Soft-trim): サイズ超過したツール結果に対して行われます。
  • 先頭と末尾を残して中間を ... で置き換え、元のサイズを記した注釈を付記します。
  • 画像ブロックを含む結果はスキップされます。
• ハードクリア (Hard-clear): ツール結果全体を hardClear.placeholder に置き換えます。

​

対象ツールの選択

• tools.allow / tools.deny では * ワイルドカードを使用できます。
• 拒否（deny）設定が優先されます。
• 一致判定は大文字小文字を区別しません。
• 許可リストが空の場合は、すべてのツールが対象となります。

​

他の制限機能との関係

• 組み込みツールは既に自身の出力を切り捨てる機能を備えています。セッションプルーニングは、長時間のチャットによってモデルのコンテキストにツール出力が過剰に蓄積されるのを防ぐための追加のレイヤーです。
• 圧縮（Compaction）とは別の機能です。圧縮は内容を要約して履歴ファイルを 書き換え ますが、プルーニングはリクエストごとの一時的な処理です。詳細は 圧縮（コンパクション） を参照してください。

​

デフォルト設定 (有効時)

• ttl: "5m"
• keepLastAssistants: 3
• softTrimRatio: 0.3
• hardClearRatio: 0.5
• minPrunableToolChars: 50000
• softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }
• hardClear: { enabled: true, placeholder: "[古いツールの実行結果が消去されました]" }

​

構成例

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

{
  agents: { defaults: { contextPruning: { mode: "cache-ttl", ttl: "5m" } } },
}

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        tools: { allow: ["exec", "read"], deny: ["*image*"] },
      },
    },
  },
}