LLMのコンテキスト管理を最適化する：Session Pruningの導入ガイド

チャットが長くなってくると、過去のツール実行結果がコンテキストを圧迫し、トークンコストが増大してしまうことがあります。特にキャッシュの有効期限が切れた後のリクエストでは、膨大な履歴を再度キャッシュし直す必要があり、効率が悪くなりがちです。

こうした課題を解決するのが Session Pruning です。この機能は、LLMへのリクエスト直前にインメモリのコンテキストから古いツールの実行結果をトリミングし、常に最適な状態を維持します。なお、ディスク上のセッション履歴（*.jsonl）は書き換えないため、データが失われる心配もありません。

必要なもの

Anthropic API または OpenRouter を介した Anthropic モデルの利用
mode: "cache-ttl" の有効化（推奨）

クイックスタート

Session Pruning を使い始めるための最小限の設定手順です。

1. 機能を有効化する

デフォルトでは off になっているため、設定ファイルで cache-ttl モードを有効にします。これにより、前回の Anthropic API 呼び出しから特定の時間が経過した場合に pruning が実行されます。

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

2. 特定のツールに限定する

すべてのツールではなく、特定のツールの出力のみを pruning の対象にすることも可能です。

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

3. キャッシュ効率とコストの改善

Session Pruning を導入すると、以下のメリットがあります。

キャッシュ書き込みコストの削減: ttl が切れた後の最初のリクエストにおいて、送信される toolResult が削減されているため、キャッシュの書き込みサイズが小さくなります。
TTL のリセット: pruning が実行されるとキャッシュウィンドウがリセットされます。その後のリクエストでは、新しくキャッシュされたプロンプトを再利用できるため、効率的です。

仕様の詳細

Pruning の対象

toolResult メッセージのみが対象です。
ユーザーやアシスタントの発言は変更されません。
直近の keepLastAssistants（デフォルト 3）で指定されたアシスタントメッセージより後のツール結果は保護されます。
画像ブロック（image blocks）を含むツール結果は、削除もトリミングもされません。

2つのトリミング方式

Soft-trim: サイズの大きいツール結果の一部を保持し、中間を ... で省略します。
Hard-clear: ツール結果全体を hardClear.placeholder（例: [Old tool result content cleared]）に置き換えます。

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

Pruning は、以下の優先順位で解決されたコンテキストウィンドウのサイズに基づいて計算されます。

models.providers.*.models[].contextWindow の上書き設定
モデル定義内の contextWindow
デフォルト値の 200000 トークン
agents.defaults.contextTokens が設定されている場合は、それが最小キャップとして適用されます。

トラブルシューティング

Pruning が実行されない

アシスタントのメッセージ数が不足している場合、保護すべき範囲（keepLastAssistants）を確定できないため、pruning はスキップされます。

画像が含まれるツール結果が消えない

画像ブロックを含む toolResult は、意図的に pruning の対象外となっています。これは、視覚情報の欠落を防ぐための仕様です。

設定が反映されない

OAuth プロファイルや API key プロファイルには、それぞれ 1h や 30m といったデフォルトの heartbeat 設定があります。これらを明示的に設定している場合、OpenClaw はそれらの値を上書きしません。

さらに詳しい設定やトラブルシューティングが必要な場合は、AI Setup Assistant をご利用ください。

次のステップ

Gateway Configuration: Gateway の詳細な設定方法を確認する
/concepts/compaction: 永続的な履歴の要約（Compaction）について学ぶ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。