OpenClaw session pruning

Tool output is what actually fills a long session. Exec results, file reads and search output pile up until the window forces a compaction that would not otherwise be due. Pruning is the cheaper intervention: drop the old tool results from what the model sees, keep the conversation text and the transcript untouched, and keep the prompt cache useful. Here is how the two paths work.

Two paths, one setting

• Setting the pruning mode to the cache-lifetime option enables it, and the request's provider, endpoint and authentication decide where it runs; the full history is preserved either way, because client-side pruning keeps a stable projected view in memory and records it in a hidden transcript marker so the same view survives a gateway restart.
• Direct requests to Anthropic with an API key on the default endpoint delegate to server-side tool-result clearing: OpenClaw opens no client-side rounds and the server clears old results before the model sees them, with the trigger at the larger of fifty thousand input tokens or thirty percent of the window, the three most recent tool uses kept, a minimum clearance of the larger of twelve thousand five hundred tokens or five percent of the window, tool inputs preserved, and any tools excluded by policy left out.
• Clearing invalidates the prompt cache from the first cleared result, which is why the minimum clearance exists: it prevents an event that removes too few tokens to justify writing a new cache entry, and when clearing happens OpenClaw logs how many results and input tokens went.
• Every other eligible route prunes on the client in a gated ladder: wait for the cache lifetime to elapse, which each successful request refreshes and each failure does not; estimate context against the window and skip below roughly thirty percent usage; soft-trim results over four thousand characters to their first and last fifteen hundred; hard-clear them when usage is still at or above roughly fifty percent and at least fifty thousand characters of prunable tool content remain; then record the projection and reset the clock.

Only toolResult messages are eligible; normal conversation text is left alone.

The rules that never bend

Two safety rules apply regardless of thresholds: the last three assistant turns are never pruned, and nothing before the session's first user message is ever pruned, which protects the bootstrap reads that define the agent's personality and user profile. The thresholds and trim windows themselves are built-in behaviour rather than configuration; what you can configure is the mode, the cache lifetime, which tool names are prunable through an allow and deny pair, and whether hard clearing happens at all along with the placeholder it leaves behind. The lifetime gates new rounds, not the replay of previous projections, so old results keep their projected bytes through tool loops and restarts while the original text and non-text content stay in the transcript. Compaction drops projections for results that have left the active history, and starting a new session begins without the old projections.

Images and smart defaults

• A separate idempotent replay view handles sessions that keep raw image blocks or media markers in history: the three most recent completed turns are preserved byte for byte so recent cache prefixes stay stable, the window advances only when a new user turn begins, and older already-processed image blocks and textual media references are replaced with explicit removal markers while the raw transcript still renders the originals.
• The bundled Anthropic plugin auto-configures pruning and heartbeat cadence the first time it resolves a matching auth profile, and only for fields you have not set: token-based auth gets the cache-lifetime mode with a one-hour lifetime and a one-hour heartbeat, while API-key auth gets the same mode and lifetime with a thirty-minute heartbeat.
• Pruning is off by default for other providers, turning it on is two keys, and setting the mode back to off stops new rounds while existing projections keep replaying until compaction removes their results or the session is reset.

OpenClaw compaction is the heavier sibling that summarizes conversation and OpenClaw context explained the budget both of them defend.

Why it pairs with caching

Prompt caching rewards a stable prefix, and tool output is the least stable, least valuable part of that prefix. Pruning reduces what has to be cached and keeps later requests on the reduced version, which is why the client-side path waits for the cache lifetime before changing anything: pruning earlier would invalidate a cache entry that was still paying for itself. The same logic explains the image replay view, which exists to stop repeated image payloads and stale media references from busting the cache on later turns. Pruning and compaction complement each other, with pruning keeping tool output lean between compaction cycles. The OpenClaw exec tool produces most of the output being trimmed and The OpenClaw heartbeat shares the cadence defaults described above.

On Diali

On Diali the runtime configuration is generated from the dashboard and replaced at each release, so these defaults arrive with the runtime rather than being tuned by hand per customer. Hosted OpenClaw on Diali describes the hosted assistant and Diali pricing the plans it ships in.

• Tool results only; conversation text is never touched.
• Direct Anthropic keys clear server-side; everything else prunes locally.
• Recent turns and pre-first-message reads are always protected.