セッションプルーニング

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

実行タイミング

  • 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件のアシスタントメッセージは保護される。そのカットオフ以降のツール結果はプルーニングされない。
  • カットオフを確立するのに十分なアシスタントメッセージがない場合、プルーニングはスキップされる。
  • 画像ブロックを含むツール結果はスキップされる（トリミング/クリアされない）。

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

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

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

agents.defaults.contextTokensが設定されている場合、解決されたウィンドウに対する上限（min）として扱われます。

モード

cache-ttl

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

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

  • ソフトトリム：サイズが大きいツール結果のみ対象。
    • 先頭と末尾を保持し、...を挿入、元のサイズを示す注記を追加。
    • 画像ブロックを含む結果はスキップ。
  • ハードクリア：ツール結果全体をhardClear.placeholderで置換。

ツール選択

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

他の制限との関係

  • 組み込みツールはすでに自身の出力をトランケートしている。セッションプルーニングは、長時間のチャットでモデルコンテキストにツール出力が蓄積しすぎるのを防ぐ追加レイヤー。
  • コンパクションは別機能：コンパクションは要約して永続化するが、プルーニングはリクエストごとの一時的な処理。/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]" }

設定例

デフォルト（オフ）：

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

TTL対応プルーニングを有効化：

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

特定のツールに限定してプルーニング：

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

設定リファレンス：Gateway Configuration

arrow_back
前へ
Session
次へ
Session Tool
arrow_forward