セッションのプルーニング

セッションプルーニングは、各 LLM 呼び出しの前にコンテキストから古いツール結果を削減します。通常の会話テキストを書き換えることなく、蓄積されたツール出力（実行結果、ファイルの読み取り結果、検索結果）によるコンテキストの肥大化を抑えます。

重要な理由

長時間のセッションではツール出力が蓄積し、コンテキストウィンドウが膨らみます。これによりコストが増加し、必要以上に早くCompactionを余儀なくされる場合があります。

プルーニングは、特に Anthropic のプロンプトキャッシュで有効です。キャッシュの TTL が期限切れになると、次のリクエストでプロンプト全体が再キャッシュされます。プルーニングによってキャッシュ書き込みサイズが削減され、コストが直接低下します。

仕組み

プルーニングは cache-ttl モードで実行され、時間チェックとコンテキストサイズチェックの両方を条件とします。

1. キャッシュの TTL が期限切れになるまで待ちます（手動で設定した場合のデフォルトは 5 分。Anthropic の自動デフォルトについてはスマートデフォルトを参照してください）。TTL が経過するまでは、近接するターンでプロンプトキャッシュを再利用できるよう、プルーニングは完全にスキップされます。
2. TTL の経過後、モデルのコンテキストウィンドウに対するコンテキスト全体のサイズを推定します。比率が softTrimRatio（デフォルトは 0.3）未満の場合、プルーニングをスキップし、TTL クロックを動作させ続けます。
3. 比率を超える大きなツール結果をソフトトリミングします。先頭と末尾を保持し（デフォルトではそれぞれ 1500 文字、合計で最大 4000 文字）、その間に ... を挿入します。
4. 比率が引き続き hardClearRatio（デフォルトは 0.5）以上で、プルーニング可能なツールコンテンツが少なくとも minPrunableToolChars（デフォルトは 50,000）残っている場合、それらの結果を完全に消去します。コンテンツをプレースホルダー（デフォルトは [Old tool result content cleared]）に置き換えます。
5. プルーニングによって実際にコンテキストが変更された場合にのみ TTL クロックをリセットし、後続のリクエストで新しいキャッシュを再利用できるようにします。

しきい値に関係なく、2 つの安全規則が適用されます。直近の keepLastAssistants 件のアシスタントターン（デフォルトは 3）はプルーニングされず、セッションの最初のユーザーメッセージより前にあるものもプルーニングされません（SOUL.md/USER.md のようなブートストラップ読み取りを保護します）。

対象となるのは toolResult メッセージのみで、通常の会話テキストは変更されません。プルーニング可能なツール名の範囲を指定するには agents.defaults.contextPruning.tools.{allow,deny} を使用します。

レガシー画像のクリーンアップ

OpenClaw は、未加工の画像ブロックやプロンプトハイドレーション用メディアマーカーを履歴に保持するセッション向けに、独立した冪等なリプレイビューも構築します。

• 直近の完了済み 3 ターンをバイト単位でそのまま保持し、直近のフォローアップに使用されるプロンプトキャッシュのプレフィックスを安定させます。この数には画像を含むターンだけでなく、完了したすべてのターンが含まれるため、テキストのみのターンも対象枠を消費します。
• リプレイビューでは、user または toolResult の履歴にある、すでに処理済みの古い画像ブロックが [image data removed - already processed by model] に置き換えられます。
• [media attached: ...]、[Image: source: ...]、media://inbound/... などの古いテキスト形式のメディア参照は、[media reference removed - already processed by model] に置き換えられます。現在のターンの添付ファイルマーカーはそのまま保持されるため、ビジョンモデルは新しい画像を引き続きハイドレートできます。
• 未加工のセッショントランスクリプトは書き換えられないため、履歴ビューアーでは元のメッセージエントリとその画像を引き続き表示できます。
• これは、前述の通常のキャッシュ TTL プルーニングとは別の処理です。後続のターンで、繰り返される画像ペイロードや古いメディア参照によってプロンプトキャッシュが無効化されるのを防ぐために存在します。

スマートデフォルト

バンドルされている Anthropic Plugin は、Anthropic（または Claude CLI）の認証プロファイルを初めて解決するときに、プルーニングと Heartbeat の頻度を自動設定します。ただし、まだ明示的に設定していないフィールドのみが対象です。

agents.defaults.contextPruning.mode または agents.defaults.heartbeat.every を自分で設定した場合、OpenClaw はそれらを上書きしません。この自動デフォルトは Anthropic 系の認証に対してのみ適用されます。他のプロバイダーでは、設定しない限りプルーニングは off になります。

有効化または無効化

Anthropic 以外のプロバイダーでは、プルーニングはデフォルトで無効です。有効にするには、次のように設定します。

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

無効にするには、mode: "off" を設定します。

プルーニングと Compaction の比較

両者は相互に補完します。プルーニングは、Compaction の実行サイクル間でツール出力を簡潔に保ちます。

関連資料

• Compaction：要約に基づくコンテキスト削減
• Gateway の設定：プルーニングに関するすべての設定項目（contextPruning.*）

関連項目

• セッション管理
• セッションツール
• コンテキストエンジン