Session-Management & Compaction (Deep Dive)
Dieses Dokument erklaert, wie OpenClaw Sessions durchgaengig verwaltet: Session-Routing, Session-Store (sessions.json), Transkript-Persistenz (*.jsonl), Transkript-Hygiene, Kontextlimits, Compaction (manuell + automatisch) und stilles Housekeeping.
Fuer einen uebergeordneten Ueberblick, starte mit: /concepts/session, /concepts/compaction, /concepts/session-pruning, /reference/transcript-hygiene
Source of Truth: das Gateway
OpenClaw ist um einen einzelnen Gateway-Prozess herum aufgebaut, der den Session-Zustand besitzt.
Zwei Persistenzschichten
- Session-Store (
sessions.json): Key/Value-Map:sessionKey -> SessionEntry. Klein, aenderbar, sicher zu bearbeiten. - Transkript (
<sessionId>.jsonl): Append-Only-Transkript mit Baumstruktur (Eintraege habenid+parentId).
On-Disk-Speicherorte
Pro Agent auf dem Gateway-Host: ~/.openclaw/agents/<agentId>/sessions/sessions.json und ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl.
Session-Keys und Session-IDs
Session-Keys identifizieren welchen Konversations-Bucket du nutzt. Session-IDs zeigen auf die aktuelle Transkriptdatei. Reset (/new, /reset) erstellt eine neue sessionId. Taeglicher Reset (Standard 4:00 lokal) und Idle-Ablauf werden ebenfalls unterstuetzt.
Compaction
Compaction fasst aeltere Konversation in einen persistierten compaction-Eintrag im Transkript zusammen und behaelt juengste Nachrichten intakt. Auto-Compaction triggert bei Overflow-Recovery und Threshold-Maintenance.
Pre-Compaction “Memory Flush”
Vor der Auto-Compaction laeuft ein stiller agentischer Turn, der dauerhaften Zustand auf Disk schreibt, damit Compaction kritischen Kontext nicht loeschen kann. Konfigurierbar via agents.defaults.compaction.memoryFlush.
Stilles Housekeeping (NO_REPLY)
Assistenten-Ausgabe die mit NO_REPLY beginnt unterdrueckt die Zustellung an den Benutzer.