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.

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

1. Wait for the cache TTL to expire (default 5 minutes).
2. Find old tool results for normal pruning (conversation text is left alone).
3. Soft-trim oversized results -- keep the head and tail, insert
   text

   Copy

   ...
   .
4. Hard-clear the rest -- replace with a placeholder.
5. Reset the TTL so follow-up requests reuse the fresh cache.

Legacy image cleanup

OpenClaw also builds a separate idempotent replay view for sessions that persist raw image blocks or prompt-hydration media markers in history.

• It preserves the 3 most recent completed turns byte-for-byte so prompt cache prefixes for recent follow-ups stay stable.
• In the replay view, older already-processed image blocks from
  text

  Copy

  user
  or
  text

  Copy

  toolResult
  history can be replaced with
  text

  Copy

  [image data removed - already processed by model]
  .
• Older textual media references such as
  text

  Copy

  [media attached: ...]
  ,
  text

  Copy

  [Image: source: ...]
  , and
  text

  Copy

  media://inbound/...
  can be replaced with
  text

  Copy

  [media reference removed - already processed by model]
  . Current-turn attachment markers stay intact so vision models can still hydrate fresh images.
• The raw session transcript is not rewritten, so history viewers can still render the original message entries and their images.
• This is separate from normal cache-TTL pruning. It exists to stop repeated image payloads or stale media refs from busting prompt caches on later turns.

Smart defaults

OpenClaw auto-enables pruning for Anthropic profiles:

If you set explicit values, OpenClaw does not override them.

Enable or disable

Pruning is off by default for non-Anthropic providers. To enable:

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

To disable: set

Pruning vs compaction

They complement each other -- pruning keeps tool output lean between compaction cycles.

Further reading

• Compaction -- summarization-based context reduction
• Gateway Configuration -- all pruning config knobs (
  text

  Copy

  contextPruning.*
  )

Related

• Session management
• Session tools
• Context engine