セッションの剪定

セッションプルーニングは、各 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.*）

関連項目

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