---
read_when:
    - ツール出力によるコンテキストの増大を抑えたい場合
    - Anthropic のプロンプトキャッシュ最適化を理解したい場合
summary: コンテキストを簡潔に保ち、キャッシュを効率化するために古いツール結果を削減する
title: セッションの剪定
x-i18n:
    generated_at: "2026-07-11T22:11:54Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: dd5cb4582cb8d9d7265213abe1f5b5893634882b9f8b3ce1deef746293dd07db
    source_path: concepts/session-pruning.md
    workflow: 16
---

セッションプルーニングは、各 LLM 呼び出しの前にコンテキストから**古いツール結果**を削減します。通常の会話テキストを書き換えることなく、蓄積されたツール出力（実行結果、ファイル読み取り、検索結果）によるコンテキストの肥大化を抑えます。

<Info>
プルーニングはメモリ内でのみ行われ、ディスク上のセッショントランスクリプトは変更されません。完全な履歴は常に保持されます。
</Info>

## 重要な理由

長時間のセッションではツール出力が蓄積し、コンテキストウィンドウを圧迫します。これによりコストが増加し、必要以上に早く[Compaction](/ja-JP/concepts/compaction)が発生する可能性があります。

プルーニングは、特に**Anthropic のプロンプトキャッシュ**で効果的です。キャッシュの TTL が期限切れになると、次のリクエストでプロンプト全体が再度キャッシュされます。プルーニングによってキャッシュへの書き込みサイズが減少し、コストを直接削減できます。

## 仕組み

プルーニングは `cache-ttl` モードで実行され、時間とコンテキストサイズの両方のチェックによって制御されます。

1. キャッシュ TTL が期限切れになるまで待ちます（手動設定時のデフォルトは 5 分。Anthropic の自動デフォルトについては[スマートデフォルト](#smart-defaults)を参照）。TTL が経過する前はプルーニングを完全にスキップし、時間的に近いターンでプロンプトキャッシュを再利用できるようにします。
2. TTL の経過後、モデルのコンテキストウィンドウに対するコンテキスト全体のサイズを推定します。比率が `softTrimRatio`（デフォルト 0.3）未満の場合は、プルーニングをスキップして TTL の計時を継続します。
3. 比率を超える大きなツール結果を**ソフトトリミング**します。先頭と末尾を保持し（デフォルトでは各 1500 文字、合計最大 4000 文字）、その間に `...` を挿入します。
4. 比率が依然として `hardClearRatio`（デフォルト 0.5）以上で、プルーニング可能なツールコンテンツが `minPrunableToolChars`（デフォルト 50,000）文字以上残っている場合、それらの結果を**完全に消去**します。コンテンツはプレースホルダー（デフォルト `[Old tool result content cleared]`）に置き換えられます。
5. プルーニングによって実際にコンテキストが変更された場合にのみ TTL の計時をリセットし、後続のリクエストで新しいキャッシュを再利用できるようにします。

しきい値にかかわらず、2 つの安全規則が適用されます。直近の `keepLastAssistants` 回のアシスタントターン（デフォルト 3）は決してプルーニングされず、セッションの最初のユーザーメッセージより前の内容も一切プルーニングされません（`SOUL.md`/`USER.md` などの初期読み取りを保護します）。

対象となるのは `toolResult` メッセージのみで、通常の会話テキストには変更を加えません。プルーニング可能なツール名の範囲を指定するには、`agents.defaults.contextPruning.tools.{allow,deny}` を使用します。

## 従来の画像クリーンアップ

OpenClaw は、未加工の画像ブロックまたはプロンプトハイドレーション用メディアマーカーを履歴に保持するセッション向けに、独立した冪等なリプレイビューも構築します。

- **直近 3 回の完了済みターン**をバイト単位でそのまま保持し、直近の後続リクエストでプロンプトキャッシュのプレフィックスが安定するようにします。この数には画像を含むターンだけでなく、すべての完了済みターンが含まれるため、テキストのみのターンも対象枠を消費します。
- リプレイビューでは、`user` または `toolResult` の履歴にある、すでに処理済みの古い画像ブロックを `[image data removed - already processed by model]` に置き換えます。
- `[media attached: ...]`、`[Image: source: ...]`、`media://inbound/...` などの古いテキスト形式のメディア参照は、`[media reference removed - already processed by model]` に置き換えられます。現在のターンの添付マーカーはそのまま保持されるため、ビジョンモデルは新しい画像を引き続きハイドレーションできます。
- 未加工のセッショントランスクリプトは書き換えられないため、履歴ビューアーでは元のメッセージエントリと画像を引き続き表示できます。
- これは、前述の通常のキャッシュ TTL プルーニングとは別の処理です。後続ターンで画像ペイロードや古いメディア参照が繰り返し使用され、プロンプトキャッシュが無効になるのを防ぐために存在します。

## スマートデフォルト

バンドルされている Anthropic Plugin は、Anthropic（または Claude CLI）の認証プロファイルを初めて解決するときに、プルーニングと Heartbeat の間隔を自動設定します。ただし、まだ明示的に設定していないフィールドのみが対象です。

| 認証方式                                       | `contextPruning.mode` | `contextPruning.ttl` | `heartbeat.every` |
| ---------------------------------------------- | --------------------- | -------------------- | ----------------- |
| OAuth/トークン（Claude CLI の再利用を含む）    | `cache-ttl`           | `1h`                 | `1h`              |
| API キー                                       | `cache-ttl`           | `1h`                 | `30m`             |

`agents.defaults.contextPruning.mode` または `agents.defaults.heartbeat.every` を自分で設定した場合、OpenClaw はそれらを上書きしません。この自動デフォルトは Anthropic 系の認証に対してのみ適用されます。他のプロバイダーでは、明示的に設定しない限りプルーニングは `off` になります。

## 有効化または無効化

Anthropic 以外のプロバイダーでは、プルーニングはデフォルトで無効です。有効にするには、次のように設定します。

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

無効にするには、`mode: "off"` を設定します。

## プルーニングと Compaction の比較

|              | プルーニング         | Compaction              |
| ------------ | -------------------- | ----------------------- |
| **処理内容** | ツール結果を削減     | 会話を要約              |
| **保存**     | なし（リクエスト単位） | あり（トランスクリプト内） |
| **範囲**     | ツール結果のみ       | 会話全体                |

両者は相互に補完します。プルーニングは、Compaction サイクルの間にツール出力を簡潔に保ちます。

## 関連資料

- [Compaction](/ja-JP/concepts/compaction)：要約に基づくコンテキスト削減
- [Gateway の設定](/ja-JP/gateway/configuration)：すべてのプルーニング設定項目（`contextPruning.*`）

## 関連項目

- [セッション管理](/ja-JP/concepts/session)
- [セッションツール](/ja-JP/concepts/session-tool)
- [コンテキストエンジン](/ja-JP/concepts/context-engine)