Session Pruning: So hältst du deinen Context sauber und sparst Kosten

Kennst du das? Du arbeitest an einer langen Session und die Kosten für die API schießen in die Höhe, nur weil alte Tool-Ausgaben den Context verstopfen. Irgendwann wird das Ganze träge und teuer, obwohl die alten Daten für die aktuelle Antwort gar nicht mehr wichtig sind.

Session Pruning löst genau dieses Problem. Es entfernt alte toolResult Nachrichten aus dem in-memory Context, kurz bevor der LLM-Call erfolgt. Deine Session-Historie auf der Festplatte (*.jsonl) bleibt dabei völlig unberührt.

Voraussetzungen

• Anthropic API oder OpenRouter Anthropic Modelle
• Gateway Konfiguration
• Aktiver cache-ttl Modus
• Passendes ttl Setting

Schnellstart

In nur zwei Schritten aktivierst du das Pruning für deine Anthropic-Modelle. Der Fokus liegt hier auf dem cache-ttl Modus, der den Context basierend auf der Zeit seit dem letzten Call bereinigt.

1. Öffne deine Konfiguration.
2. Setze den mode auf "cache-ttl".

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

Wenn du das Pruning nur auf bestimmte Tools beschränken willst, kannst du Wildcards verwenden:

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

Funktionsweise und Vorteile

Session Pruning greift nur bei Anthropic API Calls. Es verbessert die Effizienz deiner Requests auf zwei Arten:

• Kostenreduzierung: Pruning verringert die cacheWrite Größe für den ersten Request, nachdem die TTL abgelaufen ist.
• Cache-Optimierung: Sobald das Pruning läuft, wird das TTL-Fenster zurückgesetzt. Nachfolgende Requests können den frisch gecachten Prompt wiederverwenden.
• Context-Management: Es verhindert, dass lang laufende Chats zu viele Tool-Ausgaben im Model-Context ansammeln.
• Sicherheit: User- und Assistant-Nachrichten werden niemals modifiziert oder gelöscht.

Soft vs. Hard Pruning

Das System unterscheidet zwischen zwei Arten der Kürzung:

• Soft-trim: Wird bei übergroßen Tool-Ergebnissen angewendet. Es behält den Anfang und das Ende (Head + Tail) und fügt einen Hinweis auf die ursprüngliche Größe ein.
• Hard-clear: Ersetzt das gesamte Tool-Ergebnis durch einen Platzhalter wie [Old tool result content cleared].

Wichtig: Tool-Ergebnisse, die image blocks enthalten, werden grundsätzlich übersprungen und niemals gekürzt.

Fehlerbehebung

Hier sind Lösungen für häufige Szenarien, die in der Dokumentation beschrieben werden:

• Pruning wird übersprungen: Das passiert, wenn nicht genügend Assistant-Nachrichten vorhanden sind, um den Schutz-Cutoff (keepLastAssistants) zu bestimmen.
• Bilder werden nicht gekürzt: Das ist beabsichtigt. Ergebnisse mit Bild-Daten werden immer ignoriert, um Datenverlust bei visuellen Aufgaben zu vermeiden.
• Werte werden nicht übernommen: Wenn du Profile mit OAuth oder setup-tokens nutzt, gelten Smart Defaults (z. B. 1h Heartbeat). Eigene explizite Werte in der Konfiguration werden jedoch nicht von OpenClaw überschrieben.

Brauchst du Hilfe bei der Einrichtung? Frag den AI Setup Assistant.

Nächste Schritte

• Gateway Configuration
• /concepts/compaction