Session-Pruning

Session-Pruning kuerzt alte Tool-Ergebnisse im In-Memory-Kontext direkt vor jedem LLM-Aufruf. Die On-Disk-Sitzungshistorie (*.jsonl) wird dabei nicht veraendert.

Wann es laeuft

Wenn mode: "cache-ttl" aktiviert ist und der letzte Anthropic-Aufruf fuer die Session aelter als ttl ist.
Betrifft nur die Nachrichten, die dem Modell fuer diesen Request gesendet werden.
Nur aktiv bei Anthropic-API-Aufrufen (und OpenRouter-Anthropic-Modellen).
Fuer beste Ergebnisse sollte ttl auf die cacheRetention-Richtlinie deines Modells abgestimmt sein (short = 5min, long = 1h).
Nach einem Pruning-Lauf wird das TTL-Fenster zurueckgesetzt, sodass nachfolgende Requests den Cache behalten, bis ttl erneut ablaeuft.

Smarte Standardwerte (Anthropic)

OAuth oder Setup-Token-Profile: cache-ttl-Pruning aktivieren und Heartbeat auf 1h setzen.
API-Key-Profile: cache-ttl-Pruning aktivieren, Heartbeat auf 30m setzen und cacheRetention: "short" als Standard fuer Anthropic-Modelle.
Wenn du einen dieser Werte explizit setzt, ueberschreibt OpenClaw ihn nicht.

Was das verbessert (Kosten + Cache-Verhalten)

Warum prunen: Anthropics Prompt-Caching greift nur innerhalb des TTL. Wenn eine Session ueber das TTL hinaus idle ist, wird beim naechsten Request der volle Prompt neu gecacht — es sei denn, du trimmst ihn vorher.
Was guenstiger wird: Pruning reduziert die cacheWrite-Groesse fuer den ersten Request nach Ablauf des TTL.
Warum der TTL-Reset wichtig ist: Nach dem Pruning wird das Cache-Fenster zurueckgesetzt, sodass Folgeanfragen den frisch gecachten Prompt wiederverwenden koennen, statt die volle Historie erneut zu cachen.
Was es nicht tut: Pruning fuegt keine Tokens hinzu und “verdoppelt” keine Kosten; es aendert nur, was beim ersten Post-TTL-Request gecacht wird.

Was gepruned werden kann

Nur toolResult-Nachrichten.
User- und Assistant-Nachrichten werden nie veraendert.
Die letzten keepLastAssistants Assistant-Nachrichten sind geschuetzt; Tool-Ergebnisse nach diesem Cutoff werden nicht gepruned.
Wenn nicht genuegend Assistant-Nachrichten vorhanden sind, um den Cutoff zu bestimmen, wird das Pruning uebersprungen.
Tool-Ergebnisse mit Image-Blocks werden uebersprungen (nie getrimmt/geloescht).

Kontextfenster-Schaetzung

Pruning nutzt eine geschaetzte Kontextfenstergroesse (Zeichen ≈ Tokens x 4). Das Basis-Fenster wird in dieser Reihenfolge aufgeloest:

models.providers.*.models[].contextWindow-Override.
contextWindow aus der Modelldefinition (aus der Model-Registry).
Standard: 200000 Tokens.

Wenn agents.defaults.contextTokens gesetzt ist, wird es als Cap (Minimum) auf das aufgeloeste Fenster angewendet.

Modus

cache-ttl

Pruning laeuft nur, wenn der letzte Anthropic-Aufruf aelter als ttl ist (Standard 5m).
Wenn es laeuft: gleiches Soft-Trim + Hard-Clear-Verhalten wie bisher.

Soft- vs. Hard-Pruning

Soft-Trim: nur fuer uebergrosse Tool-Ergebnisse.
- Behaelt Anfang + Ende, fuegt ... ein und haengt eine Notiz mit der Originalgroesse an.
- Ueberspringt Ergebnisse mit Image-Blocks.
Hard-Clear: ersetzt das gesamte Tool-Ergebnis durch hardClear.placeholder.

Tool-Auswahl

tools.allow / tools.deny unterstuetzen *-Wildcards.
Deny gewinnt.
Matching ist case-insensitive.
Leere Allow-Liste => alle Tools erlaubt.

Zusammenspiel mit anderen Limits

Eingebaute Tools kuerzen ihren eigenen Output bereits; Session-Pruning ist eine zusaetzliche Ebene, die verhindert, dass langlebige Chats zu viel Tool-Output im Modellkontext ansammeln.
Kompaktierung ist separat: Kompaktierung fasst zusammen und persistiert, Pruning ist transient pro Request. Siehe /concepts/compaction.

Standardwerte (wenn aktiviert)

ttl: "5m"
keepLastAssistants: 3
softTrimRatio: 0.3
hardClearRatio: 0.5
minPrunableToolChars: 50000
softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }
hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

Beispiele

Standard (aus):

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

TTL-bewusstes Pruning aktivieren:

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

Pruning auf bestimmte Tools beschraenken:

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        tools: { allow: ["exec", "read"], deny: ["*image*"] },
      },
    },
  },
}

Siehe Config-Referenz: Gateway Configuration