OpenClaw Session Management: Daten effektiv verwalten

Die Quelle der Wahrheit: Das Gateway

OpenClaw ist um einen einzelnen Gateway-Prozess herum aufgebaut, der den Session-Status verwaltet.

• UIs (macOS-App, Web-Control-UI, TUI, CLI) sollten das Gateway nach Session-Listen und Token-Anzahlen abfragen.
• Im Remote-Modus liegen die Session-Dateien auf dem Remote-Host; ein Blick in deine lokalen Mac-Dateien zeigt also nicht das an, was das Gateway tatsächlich nutzt.

Zwei Persistenz-Ebenen

OpenClaw speichert Sessions auf zwei Ebenen:

1. Session-Store (sessions.json)

   • Key/Value-Map (sessionKey -> SessionEntry), die klein, veränderbar und sicher zu bearbeiten ist.
   • Trackt Session-Metadaten wie die aktuelle Session-ID, letzte Aktivität, Toggles oder Token-Counter.

2. Transcript (<sessionId>.jsonl)

   • Append-only Transcript mit Baumstruktur (id + parentId), das Konversationen, Tool-Calls und Compaction-Zusammenfassungen speichert.
   • Wird genutzt, um den Model-Kontext für zukünftige Turns wiederherzustellen.

Speicherorte auf der Festplatte

Pro Agent auf dem Gateway-Host:

• Store: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transcripts: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
• Telegram-Topic-Sessions: .../<sessionId>-topic-<threadId>.jsonl
• Konfigurations-Pfad: src/config/sessions.ts

Store-Wartung und Disk-Steuerung

Die Session-Persistenz verfügt über automatische Wartungsfunktionen (session.maintenance) für sessions.json und Transcript-Artefakte:

• mode: warn (Standard) oder enforce
• pruneAfter: Altersschwellenwert für veraltete Einträge (Standard 30d)
• maxEntries: Obergrenze für Einträge in der sessions.json (Standard 500)
• rotateBytes: sessions.json rotieren, wenn sie zu groß wird (Standard 10mb)
• resetArchiveRetention: Aufbewahrungsdauer für *.reset.<timestamp> Transcript-Archive (Standard: wie pruneAfter; false deaktiviert die Bereinigung)
• maxDiskBytes: Optionales Budget für das Sessions-Verzeichnis
• highWaterBytes: Optionaler Zielwert nach der Bereinigung (Standard 80% von maxDiskBytes)

Reihenfolge der Bereinigung beim Disk-Budget (mode: "enforce"):

1. Zuerst die ältesten archivierten oder verwaisten Transcript-Artefakte entfernen.
2. Falls immer noch über dem Zielwert, die ältesten Session-Einträge samt Transcript-Dateien löschen, bis die Nutzung bei oder unter highWaterBytes liegt.

Im mode: "warn" meldet OpenClaw potenzielle Löschungen, verändert aber den Store oder die Dateien nicht.

Wartung manuell ausführen:

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

Cron-Sessions und Run-Logs

Isolierte Cron-Runs erstellen ebenfalls Session-Einträge und Transkripte. Dafür gibt es spezielle Einstellungen zur Aufbewahrung:

• cron.sessionRetention (Standard 24h) löscht alte isolierte Cron-Run-Sessions aus dem Session-Store (false deaktiviert dies).
• cron.runLog.maxBytes + cron.runLog.keepLines bereinigen die ~/.openclaw/cron/runs/<jobId>.jsonl Dateien (Standardwerte: 2_000_000 Bytes und 2000 Zeilen).

---

Session-Keys (sessionKey)

Ein sessionKey legt fest, in welchem Conversation Bucket du dich befindest (Routing + Isolation).

Häufige Muster sind:

• Haupt-Chat/Direkt-Chat (pro Agent): agent:<agentId>:<mainKey> (Standard ist main)
• Gruppe: agent:<agentId>:<channel>:group:<id>
• Raum/Kanal (Discord/Slack): agent:<agentId>:<channel>:channel:<id> oder ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (außer wenn überschrieben)

Die offiziellen Regeln findest du unter /concepts/session.

---

Session-IDs (sessionId)

Jeder sessionKey zeigt auf eine aktuelle sessionId (die Transkript-Datei, in der die Konversation fortgeführt wird).

Hier sind die Faustregeln:

• Reset (/new, /reset) erzeugt eine neue sessionId für diesen sessionKey.
• Täglicher Reset (Standardmäßig um 4:00 Uhr Lokalzeit auf dem Gateway-Host) erstellt bei der nächsten Nachricht nach dem Reset-Zeitpunkt eine neue sessionId.
• Idle-Expiry (session.reset.idleMinutes oder veraltet session.idleMinutes) erstellt eine neue sessionId, wenn eine Nachricht nach Ablauf des Idle-Zeitfensters eingeht. Wenn sowohl der tägliche Reset als auch der Idle-Ablauf konfiguriert sind, gewinnt das Ereignis, das zuerst eintritt.
• Thread Parent Fork Guard (session.parentForkMaxTokens, Standard 100000) überspringt das Forking des Parent-Transkripts, wenn die Parent-Session bereits zu groß ist. Der neue Thread startet dann komplett neu. Setze den Wert auf 0, um das zu deaktivieren.

Technisches Detail: Die Entscheidung darüber fällt in der Funktion initSessionState() in src/auto-reply/reply/session.ts.

---

Session-Store-Schema (sessions.json)

Der Value-Typ im Store ist SessionEntry aus src/config/sessions.ts.

Wichtige Felder (nicht vollständig):

• sessionId: Die ID des aktuellen Transkripts (der Dateiname wird davon abgeleitet, außer sessionFile ist gesetzt).
• updatedAt: Zeitstempel der letzten Aktivität.
• sessionFile: Optionaler Pfad, um das Transkript explizit zu überschreiben.
• chatType: direct | group | room (hilft der UI und den Send-Policies).
• provider, subject, room, space, displayName: Metadaten für die Beschriftung von Gruppen und Kanälen.
• Toggles:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (Override pro Session)
• Modellauswahl:
  • providerOverride, modelOverride, authProfileOverride
• Token-Counter (Best-Effort / abhängig vom Provider):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: Wie oft die Auto-Compaction für diesen Session-Key abgeschlossen wurde.
• memoryFlushAt: Zeitstempel des letzten Memory-Flushs vor der Compaction.
• memoryFlushCompactionCount: Stand des Compaction-Counters beim letzten Flush.

Du kannst den Store zwar manuell bearbeiten, aber das Gateway hat das Sagen: Es kann Einträge überschreiben oder neu laden, während die Sessions laufen.

AI Setup Assistant

Transkript-Struktur (*.jsonl)

Transkripte werden vom SessionManager von @mariozechner/pi-coding-agent verwaltet.

Die Datei ist im JSONL-Format aufgebaut:

• Erste Zeile: Session-Header (type: "session", enthält id, cwd, timestamp, optional parentSession)
• Danach: Session-Einträge mit id + parentId (Baumstruktur)

Wichtige Eintragstypen:

• message: Nachrichten von User, Assistant oder ToolResult
• custom_message: Von Extensions eingefügte Nachrichten, die in den Model-Context einfließen (können in der UI ausgeblendet werden)
• custom: Extension-Status, der nicht in den Model-Context einfließt
• compaction: Gespeicherte Zusammenfassung der Komprimierung mit firstKeptEntryId und tokensBefore
• branch_summary: Gespeicherte Zusammenfassung beim Navigieren in einem Branch des Baums

OpenClaw korrigiert Transkripte absichtlich nicht; das Gateway nutzt den SessionManager, um sie zu lesen und zu schreiben.

Context Windows vs. getrackte Token

Zwei verschiedene Konzepte sind hier wichtig:

1. Model Context Window: Harte Obergrenze pro Model (Token, die für das Model sichtbar sind)
2. Session Store Counter: Fortlaufende Statistiken, die in die sessions.json geschrieben werden (genutzt für /status und Dashboards)

Wenn du Limits anpasst:

• Das Context Window stammt aus dem Model-Katalog (und kann via Config überschrieben werden).
• contextTokens im Store ist ein Schätzwert zur Laufzeit für das Reporting; betrachte diesen Wert nicht als strikte Garantie.

Weitere Informationen findest du unter /token-use.

Compaction: Was das ist

Compaction fasst ältere Unterhaltungen in einem dauerhaften compaction-Eintrag im Transcript zusammen und lässt die aktuellen Nachrichten unverändert.

Nach der Compaction sehen zukünftige Turns:

• Die Compaction-Zusammenfassung
• Nachrichten nach der firstKeptEntryId

Compaction ist persistent (anders als Session Pruning). Schau dir dazu /concepts/session-pruning an.

Wann Auto-Compaction passiert (Pi-Runtime)

Im eingebetteten Pi-Agent wird Auto-Compaction in zwei Fällen ausgelöst:

1. Overflow recovery: Das Model gibt einen Context-Overflow-Fehler zurück → Compact → Retry.
2. Threshold maintenance: Nach einem erfolgreichen Turn, wenn:

contextTokens > contextWindow - reserveTokens

Dabei gilt:

• contextWindow ist das Context Window des Models
• reserveTokens ist der Puffer, der für Prompts und den nächsten Model-Output reserviert ist

Das ist die Logik der Pi-Runtime (OpenClaw verarbeitet die Events, aber Pi entscheidet, wann die Compaction stattfindet).

Compaction-Einstellungen (reserveTokens, keepRecentTokens)

Die Compaction-Einstellungen von Pi findest du direkt in den Pi-Settings:

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

OpenClaw erzwingt zusätzlich eine Sicherheitsuntergrenze (Safety Floor) für Embedded-Runs:

• Wenn compaction.reserveTokens < reserveTokensFloor ist, hebt OpenClaw den Wert automatisch an.
• Der Standard-Floor liegt bei 20000 Tokens.
• Setze agents.defaults.compaction.reserveTokensFloor: 0, um diesen Floor zu deaktivieren.
• Falls der Wert bereits höher eingestellt ist, lässt OpenClaw ihn unverändert.

Der Grund dafür: Du solltest genug Headroom für “Housekeeping”-Aufgaben über mehrere Turns einplanen (wie das Schreiben in den Memory), bevor Compaction unumgänglich wird.

Die Implementierung findest du in ensurePiCompactionReserveTokens() in src/agents/pi-settings.ts (aufgerufen durch src/agents/pi-embedded-runner.ts).

Sichtbare Oberflächen für Nutzer

Du kannst die Compaction und den Session-Status über folgende Wege überwachen:

• /status (innerhalb jeder Chat-Session)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Verbose-Mode: 🧹 Auto-compaction complete + Compaction-Count

Stille Hintergrundaufgaben (NO_REPLY)

OpenClaw unterstützt „stille“ Durchläufe für Hintergrundaufgaben, bei denen du keine Zwischenergebnisse sehen sollst.

Konvention:

• Der Assistant beginnt seine Ausgabe mit NO_REPLY, um zu signalisieren: „Sende keine Antwort an den User“.
• OpenClaw filtert diesen Teil in der Delivery-Ebene heraus.

Seit Version 2026.1.10 unterdrückt OpenClaw zudem das Draft/Typing Streaming, wenn ein Chunk mit NO_REPLY beginnt. So verhinderst du, dass Teilergebnisse während stiller Operationen sichtbar werden.

---

Memory-Flush vor der Compaction (implementiert)

Ziel: Bevor die automatische Compaction greift, wird ein stiller Agent-Durchlauf gestartet. Dieser schreibt den aktuellen Status dauerhaft auf die Festplatte (z. B. nach memory/YYYY-MM-DD.md im Agent-Workspace). So stellst du sicher, dass die Compaction keinen kritischen Kontext löscht.

OpenClaw nutzt dafür den Pre-Threshold Flush Ansatz:

1. Das System überwacht die Kontext-Nutzung der Session und sendet bei Erreichen eines „Soft Threshold“ (unterhalb des Compaction-Limits von Pi) eine stille Anweisung zum Speichern.
2. Durch die Verwendung von NO_REPLY bleibt dieser gesamte Vorgang für dich unsichtbar.

Konfiguration (agents.defaults.compaction.memoryFlush):

• enabled (Standard: true)
• softThresholdTokens (Standard: 4000)
• prompt (User-Message für den Flush-Durchlauf)
• systemPrompt (Zusätzlicher System-Prompt für den Flush-Durchlauf)

Hinweise:

• Die Standard-Prompts enthalten bereits einen NO_REPLY Hinweis zur Unterdrückung der Ausgabe.
• Der Flush wird einmal pro Compaction-Zyklus ausgeführt und in der sessions.json getrackt.
• Diese Funktion ist für eingebettete Pi-Sessions reserviert; CLI-Backends überspringen diesen Schritt.
• Bei schreibgeschützten Workspaces (workspaceAccess: "ro" oder "none") wird der Flush deaktiviert.
• Details zum Datei-Layout findest du unter Memory.

Pi bietet zwar einen session_before_compact Hook in der Extension-API an, aber die Flush-Logik von OpenClaw läuft aktuell direkt über das Gateway.

---

Checkliste zur Fehlerbehebung

• Session-Key inkorrekt? Prüfe /concepts/session und vergleiche den sessionKey in /status.
• Abweichungen zwischen Store und Transcript? Kontrolliere den Gateway-Host und den Store-Pfad mit dem Befehl openclaw status.
• Zu häufige Compaction? Überprüfe folgende Punkte:
  • Das Context Window des Models ist zu klein oder die reserveTokens sind im Verhältnis dazu zu hoch angesetzt.
  • Tool-Result-Bloat: Aktiviere das Session Pruning oder passe die entsprechenden Parameter an.
• Stille Durchläufe werden angezeigt? Stelle sicher, dass die Antwort exakt mit dem Token NO_REPLY beginnt und du eine Version nutzt, die den Fix für die Streaming-Unterdrückung enthält.

AI Setup Assistant

Nächste Schritte

• Memory
• Sessions