​

Session-Management und Kompaktierung (Deep Dive)

• Session-Routing (wie eingehende Nachrichten einer sessionKey zugeordnet werden)
• Session-Store (sessions.json) und was er erfasst
• Persistenz von Transcripts (*.jsonl) und ihre Struktur
• Transcript-Hygiene (anbieterspezifische Korrekturen vor Ausführungen)
• Kontextgrenzen (Kontextfenster vs. erfasste Tokens)
• Kompaktierung (manuelle + automatische Kompaktierung) und wo Arbeiten vor der Kompaktierung eingehängt werden
• Stilles Housekeeping (z. B. Memory-Schreibvorgänge, die keine für Nutzer sichtbare Ausgabe erzeugen sollen)

• /concepts/session
• /concepts/compaction
• /concepts/memory
• /concepts/memory-search
• /concepts/session-pruning
• /reference/transcript-hygiene

​

Quelle der Wahrheit: das Gateway

• UIs (macOS-App, web Control UI, TUI) sollten das Gateway nach Session-Listen und Token-Zählwerten abfragen.
• Im Remote-Modus liegen Session-Dateien auf dem Remote-Host; ein „Prüfen Ihrer lokalen Mac-Dateien“ spiegelt nicht wider, was das Gateway verwendet.

​

Zwei Persistenzschichten

1. Session-Store (sessions.json)
   • Schlüssel/Wert-Zuordnung: sessionKey -> SessionEntry
   • Klein, veränderbar, sicher bearbeitbar (oder Einträge löschbar)
   • Erfasst Session-Metadaten (aktuelle Session-ID, letzte Aktivität, Umschalter, Token-Zählwerte usw.)
2. Transcript (<sessionId>.jsonl)
   • Append-only-Transcript mit Baumstruktur (Einträge haben id + parentId)
   • Speichert die eigentliche Unterhaltung + Tool-Aufrufe + Kompaktierungszusammenfassungen
   • Wird verwendet, um den Modellkontext für zukünftige Turns wiederaufzubauen

​

Speicherorte auf dem Datenträger

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

​

Store-Wartung und Datenträgerkontrollen

• mode: warn (Standard) oder enforce
• pruneAfter: Altersgrenze für veraltete Einträge (Standard 30d)
• maxEntries: Obergrenze für Einträge in sessions.json (Standard 500)
• rotateBytes: rotiert sessions.json, wenn es zu groß ist (Standard 10mb)
• resetArchiveRetention: Aufbewahrung für Transcript-Archive *.reset.<timestamp> (Standard: identisch zu pruneAfter; false deaktiviert die Bereinigung)
• maxDiskBytes: optionales Budget für das Sessions-Verzeichnis
• highWaterBytes: optionales Ziel nach der Bereinigung (Standard 80% von maxDiskBytes)

1. Entfernen Sie zuerst die ältesten archivierten oder verwaisten Transcript-Artefakte.
2. Wenn das Ziel weiterhin überschritten wird, entfernen Sie die ältesten Session-Einträge und ihre Transcript-Dateien.
3. Fahren Sie fort, bis die Nutzung bei oder unter highWaterBytes liegt.

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

​

Cron-Sessions und Run-Logs

• cron.sessionRetention (Standard 24h) entfernt alte isolierte Cron-Run-Sessions aus dem Session-Store (false deaktiviert dies).
• cron.runLog.maxBytes + cron.runLog.keepLines kürzen Dateien ~/.openclaw/cron/runs/<jobId>.jsonl (Standards: 2_000_000 Bytes und 2000 Zeilen).

​

Session-Schlüssel (sessionKey)

• Haupt-/Direkt-Chat (pro Agent): agent:<agentId>:<mainKey> (Standard 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> (sofern nicht überschrieben)

​

Session-IDs (sessionId)

• Zurücksetzen (/new, /reset) erstellt eine neue sessionId für diesen sessionKey.
• Tägliches Zurücksetzen (standardmäßig 4:00 Uhr lokale Zeit auf dem Gateway-Host) erstellt bei der nächsten Nachricht nach der Reset-Grenze eine neue sessionId.
• Idle-Ablauf (session.reset.idleMinutes oder Legacy-session.idleMinutes) erstellt eine neue sessionId, wenn nach dem Inaktivitätsfenster eine Nachricht eintrifft. Wenn täglich + idle beide konfiguriert sind, gilt, was zuerst abläuft.
• Fork-Schutz für Thread-Parent (session.parentForkMaxTokens, Standard 100000) überspringt das Forken des Parent-Transcripts, wenn die Parent-Session bereits zu groß ist; der neue Thread beginnt frisch. Setzen Sie 0, um dies zu deaktivieren.

​

Schema des Session-Stores (sessions.json)

• sessionId: aktuelle Transcript-ID (Dateiname wird daraus abgeleitet, sofern sessionFile nicht gesetzt ist)
• updatedAt: Zeitstempel der letzten Aktivität
• sessionFile: optionale explizite Überschreibung des Transcript-Pfads
• chatType: direct | group | room (hilft UIs und Sende-Richtlinien)
• provider, subject, room, space, displayName: Metadaten für Gruppen-/Kanallabels
• Umschalter:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (Überschreibung pro Session)
• Modellauswahl:
  • providerOverride, modelOverride, authProfileOverride
• Token-Zählwerte (Best-Effort / anbieterabhängig):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: wie oft die automatische Kompaktierung für diesen Session-Schlüssel abgeschlossen wurde
• memoryFlushAt: Zeitstempel des letzten Memory-Flushs vor der Kompaktierung
• memoryFlushCompactionCount: Kompaktierungszähler, als der letzte Flush ausgeführt wurde

​

Transcript-Struktur (*.jsonl)

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

• message: Nutzer-/Assistant-/toolResult-Nachrichten
• custom_message: von Erweiterungen eingefügte Nachrichten, die in den Modellkontext eingehen (können in der UI verborgen sein)
• custom: Erweiterungsstatus, der nicht in den Modellkontext eingeht
• compaction: persistierte Kompaktierungszusammenfassung mit firstKeptEntryId und tokensBefore
• branch_summary: persistierte Zusammenfassung beim Navigieren in einem Baumzweig

​

Kontextfenster vs. erfasste Tokens

1. Kontextfenster des Modells: harte Obergrenze pro Modell (Tokens, die für das Modell sichtbar sind)
2. Zählwerte im Session-Store: rollierende Statistiken, die in sessions.json geschrieben werden (verwendet für /status und Dashboards)

• Das Kontextfenster kommt aus dem Modellkatalog (und kann per Konfiguration überschrieben werden).
• contextTokens im Store ist ein Laufzeitschätzwert/Berichtswert; behandeln Sie es nicht als strikte Garantie.

​

Kompaktierung: was das ist

• Die Kompaktierungszusammenfassung
• Nachrichten nach firstKeptEntryId

​

Chunk-Grenzen bei der Kompaktierung und Tool-Paarung

• Wenn die tokenbasierte Aufteilung zwischen einem Tool-Aufruf und seinem Ergebnis landet, verschiebt OpenClaw die Grenze auf die Assistant-Nachricht mit dem Tool-Aufruf, statt das Paar zu trennen.
• Wenn ein nachlaufender toolResult-Block den Chunk sonst über das Ziel hinausschieben würde, bewahrt OpenClaw diesen ausstehenden Tool-Block und lässt den nicht zusammengefassten Tail intakt.
• Abgebrochene/fehlerhafte Tool-Aufruf-Blöcke halten eine ausstehende Aufteilung nicht offen.

​

Wann automatische Kompaktierung erfolgt (Pi-Laufzeit)

1. Overflow-Wiederherstellung: Das Modell gibt einen Kontext-Overflow-Fehler zurück (request_too_large, context length exceeded, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, ollama error: context length exceeded und ähnliche anbietergeformte Varianten) → kompaktieren → erneut versuchen.
2. Schwellwert-Wartung: nach einem erfolgreichen Turn, wenn:

• contextWindow ist das Kontextfenster des Modells
• reserveTokens ist der reservierte Puffer für Prompts + die nächste Modellausgabe

​

Einstellungen für Kompaktierung (reserveTokens, keepRecentTokens)

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

• Wenn compaction.reserveTokens < reserveTokensFloor ist, erhöht OpenClaw diesen Wert.
• Die Standarduntergrenze ist 20000 Tokens.
• Setzen Sie agents.defaults.compaction.reserveTokensFloor: 0, um die Untergrenze zu deaktivieren.
• Wenn der Wert bereits höher ist, lässt OpenClaw ihn unverändert.

​

Austauschbare Kompaktierungsanbieter

• provider: ID eines registrierten Kompaktierungsanbieter-Plugins. Nicht setzen für Standard-LLM-Zusammenfassung.
• Das Setzen von provider erzwingt mode: "safeguard".
• Anbieter erhalten dieselben Kompaktierungsanweisungen und dieselbe Richtlinie zur Beibehaltung von Identifikatoren wie der integrierte Pfad.
• Die Safeguard-Funktion bewahrt weiterhin Kontext des Suffixes aktueller Turns und getrennter Turns nach der Anbieterausgabe.
• Wenn der Anbieter fehlschlägt oder ein leeres Ergebnis zurückgibt, fällt OpenClaw automatisch auf die integrierte LLM-Zusammenfassung zurück.
• Abort-/Timeout-Signale werden erneut ausgelöst (nicht unterdrückt), um die Abbruchanforderung des Aufrufers zu respektieren.

​

Für Nutzer sichtbare Oberflächen

• /status (in jeder Chat-Session)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Verbose-Modus: 🧹 Auto-compaction complete + Kompaktierungszähler

​

Stilles Housekeeping (NO_REPLY)

• Der Assistant beginnt seine Ausgabe mit dem exakten stillen Token NO_REPLY / no_reply, um „keine Antwort an den Nutzer ausliefern“ anzuzeigen.
• OpenClaw entfernt/unterdrückt dies in der Zustellungsschicht.
• Die Unterdrückung des exakten stillen Tokens ist nicht case-sensitive, daher zählen NO_REPLY und no_reply beide, wenn die gesamte Payload nur aus dem stillen Token besteht.
• Dies ist nur für echte Hintergrund-/Nicht-Zustellungs-Turns gedacht; es ist keine Abkürzung für gewöhnliche, umsetzbare Nutzeranfragen.

​

„Memory Flush“ vor der Kompaktierung (implementiert)

1. Überwachen Sie die Nutzung des Session-Kontexts.
2. Wenn sie einen „weichen Schwellwert“ überschreitet (unterhalb des Kompaktierungsschwellwerts von Pi), führen Sie eine stille Direktive „write memory now“ für den Agenten aus.
3. Verwenden Sie das exakte stille Token NO_REPLY / no_reply, damit der Nutzer nichts sieht.

• enabled (Standard: true)
• softThresholdTokens (Standard: 4000)
• prompt (Nutzernachricht für den Flush-Turn)
• systemPrompt (zusätzlicher System-Prompt, der für den Flush-Turn angehängt wird)

• Der Standard-Prompt/System-Prompt enthält einen NO_REPLY-Hinweis, um die Zustellung zu unterdrücken.
• Der Flush wird einmal pro Kompaktierungszyklus ausgeführt (erfasst in sessions.json).
• Der Flush wird nur für eingebettete Pi-Sessions ausgeführt (CLI-Backends überspringen ihn).
• Der Flush wird übersprungen, wenn der Session-Workspace schreibgeschützt ist (workspaceAccess: "ro" oder "none").
• Unter Memory finden Sie das Dateilayout des Workspace und die Schreibmuster.

​

Checkliste zur Fehlerbehebung

• Session-Schlüssel falsch? Beginnen Sie mit /concepts/session und prüfen Sie den sessionKey in /status.
• Store stimmt nicht mit Transcript überein? Prüfen Sie den Gateway-Host und den Store-Pfad aus openclaw status.
• Kompaktierungs-Spam? Prüfen Sie:
  • Kontextfenster des Modells (zu klein)
  • Kompaktierungseinstellungen (reserveTokens zu hoch für das Modellfenster kann frühere Kompaktierung verursachen)
  • Aufblähung durch Tool-Ergebnisse: Aktivieren/optimieren Sie Session-Pruning
• Stille Turns lecken? Prüfen Sie, ob die Antwort mit NO_REPLY beginnt (case-insensitive, exaktes Token) und ob Sie eine Build-Version mit dem Fix zur Streaming-Unterdrückung verwenden.