セッションプルーニング

セッションプルーニングは、各LLM呼び出しの直前にメモリ内コンテキストから古いツール結果をトリミングします。ディスク上のセッション履歴（*.jsonl）を書き換えることはありません。

実行タイミング

  • mode: "cache-ttl"が有効で、そのセッションの最後のAnthropic呼び出しがttlより古い場合。
  • そのリクエストでモデルに送信されるメッセージにのみ影響します。
  • Anthropic API呼び出し（およびOpenRouter Anthropicモデル）でのみアクティブです。
  • 最良の結果を得るには、ttlをモデルのcacheControlTtlに合わせてください。
  • プルーニング後、TTLウィンドウがリセットされるため、後続のリクエストはttlが再び期限切れになるまでキャッシュを保持します。

スマートデフォルト（Anthropic）

  • OAuthまたはセットアップトークンプロファイル：cache-ttlプルーニングを有効にし、ハートビートを1hに設定。
  • APIキープロファイル：cache-ttlプルーニングを有効にし、ハートビートを30mに設定し、AnthropicモデルのデフォルトcacheControlTtlを1hに設定。
  • これらの値のいずれかを明示的に設定した場合、OpenClawはそれらを上書きしません。

これにより改善される点（コスト + キャッシュ動作）

  • プルーニングの理由： AnthropicプロンプトキャッシュはTTL内でのみ適用されます。セッションがTTLを超えてアイドル状態になると、次のリクエストは最初にトリミングしない限り、フルプロンプトを再キャッシュします。
  • コストが安くなる部分： プルーニングにより、TTL期限切れ後の最初のリクエストのcacheWriteサイズが削減されます。
  • TTLリセットが重要な理由： プルーニングが実行されると、キャッシュウィンドウがリセットされるため、フォローアップリクエストは完全な履歴を再キャッシュする代わりに、新しくキャッシュされたプロンプトを再利用できます。
  • 実行しないこと： プルーニングはトークンを追加したり、コストを「二重」にしたりしません。TTL後の最初のリクエストでキャッシュされる内容を変更するだけです。

プルーニング可能な対象

  • toolResultメッセージのみ。
  • ユーザー + アシスタントメッセージは決して変更されません。
  • 最後のkeepLastAssistants個のアシスタントメッセージは保護されます。そのカットオフ後のツール結果はプルーニングされません。
  • カットオフを確立するのに十分なアシスタントメッセージがない場合、プルーニングはスキップされます。
  • 画像ブロックを含むツール結果はスキップされます（トリミング/クリアされません）。

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

プルーニングは推定コンテキストウィンドウ（文字 ≈ トークン × 4）を使用します。ウィンドウサイズは次の順序で解決されます：

  1. モデル定義のcontextWindow（モデルレジストリから）。
  2. models.providers.*.models[].contextWindowオーバーライド。
  3. agents.defaults.contextTokens。
  4. デフォルト200000トークン。

モード

cache-ttl

  • 最後のAnthropic呼び出しがttl（デフォルト5m）より古い場合にのみプルーニングが実行されます。
  • 実行時：以前と同じソフトトリム + ハードクリア動作。

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

  • ソフトトリム：サイズの大きなツール結果のみ。
    • 先頭 + 末尾を保持し、...を挿入し、元のサイズを記したメモを追加します。
    • 画像ブロックを含む結果はスキップします。
  • ハードクリア：ツール結果全体をhardClear.placeholderに置き換えます。

ツール選択

  • tools.allow / tools.denyは*ワイルドカードをサポートします。
  • 拒否が優先されます。
  • マッチングは大文字小文字を区別しません。
  • 空の許可リスト => すべてのツールが許可されます。

他の制限との相互作用

  • 組み込みツールは既に独自の出力を切り詰めています。セッションプルーニングは、長時間実行されるチャットがモデルコンテキストに過度のツール出力を蓄積するのを防ぐ追加レイヤーです。
  • コンパクションは別物です：コンパクションは要約して永続化し、プルーニングはリクエストごとに一時的です。/concepts/compactionを参照してください。

デフォルト（有効時）

  • ttl: "5m"
  • keepLastAssistants: 3
  • softTrimRatio: 0.3
  • hardClearRatio: 0.5
  • minPrunableToolChars: 50000
  • softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }
  • hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

例

デフォルト（オフ）：

{
  agent: {
    contextPruning: { mode: "off" }
  }
}

TTL認識プルーニングを有効化：

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

特定のツールにプルーニングを制限：

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

設定リファレンスを参照：Gateway Configuration

← ドキュメントに戻る