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

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

実行時¶

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

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

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

改善される点（コスト + キャッシュ挙動）¶

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

剪定できるもの¶

• toolResult メッセージのみ。
• ユーザーおよびアシスタントのメッセージは 決して 変更されません。
• 直近の keepLastAssistants 件のアシスタントメッセージは保護されます。このカットオフ以降のツール結果はプルーニングされません。
• カットオフを確立するのに十分なアシスタントメッセージがない場合、プルーニングはスキップされます。
• 画像ブロック を含むツール結果はスキップされます（トリミングやクリアは行われません）。

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

剪定は推定されたコンテキストウィンドウを使用します (chars tokens × 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 が優先されます。
• マッチングは大文字小文字を区別しません。
• 許可リストが空の場合、すべてのツールが許可されます。

他の制限との相互作用¶

• 組み込みツールはすでに自身の出力を切り詰めます。セッションプルーニングは、長時間実行されるチャットでモデルコンテキストに過剰なツール出力が蓄積するのを防ぐための追加レイヤーです。
• Compaction is separate: compaction summalies and persists, pruning is transparent per request. /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