Session Pruning
Session pruning trims old tool results from the context before each LLM
call. It reduces context bloat from accumulated tool outputs (exec results, file
reads, search results) without rewriting normal conversation text.
Pruning is in-memory only — it does not modify the on-disk session transcript.
Your full history is always preserved.
Why it matters
Long sessions accumulate tool output that inflates the context window. This
increases cost and can force compaction sooner than
necessary.
Pruning is especially valuable for Anthropic prompt caching. After the cache
TTL expires, the next request re-caches the full prompt. Pruning reduces the
cache-write size, directly lowering cost.
How it works
- Wait for the cache TTL to expire (default 5 minutes).
- Find old tool results for normal pruning (conversation text is left alone).
- Soft-trim oversized results — keep the head and tail, insert
....
- Hard-clear the rest — replace with a placeholder.
- Reset the TTL so follow-up requests reuse the fresh cache.
Legacy image cleanup
OpenClaw also runs a separate idempotent cleanup for older legacy sessions that
persisted raw image blocks in history.
- It preserves the 3 most recent completed turns byte-for-byte so prompt
cache prefixes for recent follow-ups stay stable.
- Older already-processed image blocks in
user or toolResult history can be
replaced with [image data removed - already processed by model].
- This is separate from normal cache-TTL pruning. It exists to stop repeated
image payloads from busting prompt caches on later turns.
Smart defaults
OpenClaw auto-enables pruning for Anthropic profiles:
| Profile type | Pruning enabled | Heartbeat |
|---|
| Anthropic OAuth/token auth (including Claude CLI reuse) | Yes | 1 hour |
| API key | Yes | 30 min |
Enable or disable
Pruning is off by default for non-Anthropic providers. To enable:
{
agents: {
defaults: {
contextPruning: { mode: "cache-ttl", ttl: "5m" },
},
},
}
mode: "off".
Pruning vs compaction
| Pruning | Compaction |
|---|
| What | Trims tool results | Summarizes conversation |
| Saved? | No (per-request) | Yes (in transcript) |
| Scope | Tool results only | Entire conversation |
Further reading
