Session Pruning

Session Pruning kürzt alte Tool-Ergebnisse aus dem Arbeitsspeicher-Context direkt vor jedem LLM-Aufruf. Es schreibt nicht die Session-Historie auf der Festplatte (*.jsonl) um.

Wann es läuft

  • Wenn mode: "cache-ttl" aktiviert ist und der letzte Anthropic-Aufruf für die Session älter als ttl ist.
  • Betrifft nur die Nachrichten, die für diese Anfrage an das Modell gesendet werden.
  • Nur aktiv bei Anthropic API-Aufrufen (und OpenRouter Anthropic-Modellen).
  • Für beste Ergebnisse sollte ttl mit deinem Modell-cacheControlTtl übereinstimmen.
  • Nach einem Pruning wird das TTL-Fenster zurückgesetzt, sodass nachfolgende Anfragen den Cache behalten, bis ttl erneut abläuft.

Smarte Standardwerte (Anthropic)

  • OAuth- oder Setup-Token-Profile: aktivieren cache-ttl Pruning und setzen Heartbeat auf 1h.
  • API-Key-Profile: aktivieren cache-ttl Pruning, setzen Heartbeat auf 30m und cacheControlTtl standardmäßig auf 1h bei Anthropic-Modellen.
  • Wenn du einen dieser Werte explizit setzt, überschreibt OpenClaw sie nicht.

Was das verbessert (Kosten + Cache-Verhalten)

  • Warum Pruning: Anthropic Prompt-Caching gilt nur innerhalb der TTL. Wenn eine Session über die TTL hinaus inaktiv ist, cached die nächste Anfrage den gesamten Prompt neu — es sei denn, du kürzt ihn vorher.
  • Was günstiger wird: Pruning reduziert die cacheWrite-Größe für die erste Anfrage nach Ablauf der TTL.
  • Warum das TTL-Reset wichtig ist: Nach dem Pruning wird das Cache-Fenster zurückgesetzt, sodass Folgeanfragen den frisch gecachten Prompt wiederverwenden können, anstatt die gesamte Historie erneut zu cachen.
  • Was es nicht tut: Pruning fügt keine Tokens hinzu oder „verdoppelt” Kosten; es ändert nur, was bei der ersten Anfrage nach TTL-Ablauf gecacht wird.

Was gekürzt werden kann

  • Nur toolResult-Nachrichten.
  • User- und Assistant-Nachrichten werden nie verändert.
  • Die letzten keepLastAssistants Assistant-Nachrichten sind geschützt; Tool-Ergebnisse nach diesem Cutoff werden nicht gekürzt.
  • Wenn nicht genug Assistant-Nachrichten vorhanden sind, um den Cutoff festzulegen, wird Pruning übersprungen.
  • Tool-Ergebnisse mit Image-Blöcken werden übersprungen (nie gekürzt/gelöscht).

Context-Window-Schätzung

Pruning verwendet ein geschätztes Context-Window (Zeichen ≈ Tokens × 4). Das Basis-Window wird in dieser Reihenfolge ermittelt:

  1. models.providers.*.models[].contextWindow Override.
  2. Modell-Definition contextWindow (aus der Model-Registry).
  3. Standard 200000 Tokens.

Wenn agents.defaults.contextTokens gesetzt ist, wird es als Obergrenze (min) für das ermittelte Window behandelt.

Modus

cache-ttl

  • Pruning läuft nur, wenn der letzte Anthropic-Aufruf älter als ttl ist (Standard 5m).
  • Wenn es läuft: gleiches Soft-Trim + Hard-Clear-Verhalten wie zuvor.

Soft vs. Hard Pruning

  • Soft-Trim: nur für übergroße Tool-Ergebnisse.
    • Behält Anfang + Ende, fügt ... ein und hängt eine Notiz mit der Originalgröße an.
    • Überspringt Ergebnisse mit Image-Blöcken.
  • Hard-Clear: ersetzt das gesamte Tool-Ergebnis durch hardClear.placeholder.

Tool-Auswahl

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

Zusammenspiel mit anderen Limits

  • Eingebaute Tools kürzen ihre eigene Ausgabe bereits; Session Pruning ist eine zusätzliche Schicht, die verhindert, dass lang laufende Chats zu viel Tool-Ausgabe im Model-Context ansammeln.
  • Compaction ist separat: Compaction fasst zusammen und persistiert, Pruning ist transient pro Anfrage. Siehe 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):

{
  agent: {
    contextPruning: { mode: "off" },
  },
}

TTL-basiertes Pruning aktivieren:

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

Pruning auf bestimmte Tools beschränken:

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

Siehe Konfigurationsreferenz: Gateway-Konfiguration