> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

# セッションプルーニング (削減)

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

セッションプルーニングは、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` 件のアシスタントメッセージは保護され、それ以降のツール結果はプルーニングされません。
* 基準を満たす十分な数のアシスタントメッセージがない場合、プルーニングはスキップされます。
* **画像ブロック** を含むツールの結果は、スキップ（トリミングや消去の対象外）されます。

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

プルーニングでは推定されたコンテキストウィンドウサイズ（文字数 ≈ トークン数 × 4）を使用します。基準となるウィンドウサイズは以下の優先順位で決定されます:

1. `models.providers.*.models[].contextWindow` の上書き設定。
2. モデルカタログに定義された `contextWindow`。
3. デフォルト値の `200000` トークン。

`agents.defaults.contextTokens` が設定されている場合、解決されたウィンドウサイズの上限（最小値）として扱われます。

## モード

### cache-ttl

* 直前の Anthropic 呼び出しから `ttl` (デフォルト `5m`) 以上経過している場合にのみ実行されます。
* 実行時の挙動: 後述の「ソフトトリム」と「ハードクリア」を行います。

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

* **ソフトトリム (Soft-trim)**: サイズ超過したツール結果に対して行われます。
  * 先頭と末尾を残して中間を `...` で置き換え、元のサイズを記した注釈を付記します。
  * 画像ブロックを含む結果はスキップされます。
* **ハードクリア (Hard-clear)**: ツール結果全体を `hardClear.placeholder` に置き換えます。

## 対象ツールの選択

* `tools.allow` / `tools.deny` では `*` ワイルドカードを使用できます。
* 拒否（deny）設定が優先されます。
* 一致判定は大文字小文字を区別しません。
* 許可リストが空の場合は、すべてのツールが対象となります。

## 他の制限機能との関係

* 組み込みツールは既に自身の出力を切り捨てる機能を備えています。セッションプルーニングは、長時間のチャットによってモデルのコンテキストにツール出力が過剰に蓄積されるのを防ぐための追加のレイヤーです。
* 圧縮（Compaction）とは別の機能です。圧縮は内容を要約して履歴ファイルを **書き換え** ますが、プルーニングはリクエストごとの一時的な処理です。詳細は [圧縮（コンパクション）](/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: "[古いツールの実行結果が消去されました]" }`

## 構成例

デフォルト（オフ）:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}
```

TTL を考慮したプルーニングを有効化:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: { defaults: { contextPruning: { mode: "cache-ttl", ttl: "5m" } } },
}
```

特定のツールに限定してプルーニングを行う:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        tools: { allow: ["exec", "read"], deny: ["*image*"] },
      },
    },
  },
}
```

構成リファレンス: [ゲートウェイ構成](/gateway/configuration)