​

Session-Management & Kompaktierung (Deep Dive)

• Session-Routing (wie eingehende Nachrichten einem sessionKey zugeordnet werden)
• Session-Store (sessions.json) und was er erfasst
• Transkript-Persistenz (*.jsonl) und ihre Struktur
• Transkript-Hygiene (anbieter­spezifische Korrekturen vor Läufen)
• Kontextlimits (Kontextfenster vs. erfasste Tokens)
• Kompaktierung (manuell + Auto-Kompaktierung) und wo Vorarbeiten vor der Kompaktierung einzuhängen sind
• Stilles Housekeeping (z. B. Speicher-Schreibvorgänge, die keine nutzer­sichtbare Ausgabe erzeugen sollen)

• /concepts/session
• /concepts/compaction
• /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ählungen 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)
   • Key/Value-Map: sessionKey -> SessionEntry
   • Klein, veränderlich, sicher zu bearbeiten (oder Einträge zu löschen)
   • Erfasst Session-Metadaten (aktuelle Session-ID, letzte Aktivität, Toggles, Token-Zähler usw.)
2. Transkript (<sessionId>.jsonl)
   • Append-only-Transkript mit Baumstruktur (Einträge haben id + parentId)
   • Speichert die eigentliche Konversation + Tool-Aufrufe + Kompaktierungszusammenfassungen
   • Wird verwendet, um den Modellkontext für zukünftige Turns neu aufzubauen

​

Ablageorte auf Datenträger

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

​

Session-Schlüssel (sessionKey)

• Haupt-/Direktchat (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)

• Reset (/new, /reset) erstellt eine neue sessionId für diesen sessionKey.
• Täglicher Reset (Standard 4:00 Uhr Ortszeit auf dem Gateway-Host) erstellt eine neue sessionId bei der nächsten Nachricht nach der Reset-Grenze.
• Leerlaufablauf (session.reset.idleMinutes oder legacy session.idleMinutes) erstellt eine neue sessionId, wenn nach dem Leerlauffenster eine Nachricht eintrifft. Wenn täglich + Leerlauf beide konfiguriert sind, gewinnt der zuerst ablaufende.

​

Schema des Session-Stores (sessions.json)

• sessionId: aktuelle Transkript-ID (Dateiname wird hiervon abgeleitet, sofern sessionFile nicht gesetzt ist)
• updatedAt: Zeitstempel der letzten Aktivität
• sessionFile: optionale explizite Überschreibung des Transkriptpfads
• chatType: direct | group | room (hilft UIs und der Sende-Policy)
• provider, subject, room, space, displayName: Metadaten für Gruppen-/Kanalbeschriftung
• Toggles:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (Override pro Session)
• Modellauswahl:
  • providerOverride, modelOverride, authProfileOverride
• Token-Zähler (Best-Effort / anbieterabhängig):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: wie oft die Auto-Kompaktierung für diesen Session-Schlüssel abgeschlossen wurde
• memoryFlushAt: Zeitstempel des letzten Pre-Kompaktions-Memory-Flush
• memoryFlushCompactionCount: Kompaktierungszähler beim letzten Flush

​

Transkriptstruktur (*.jsonl)

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

• message: user/assistant/toolResult-Nachrichten
• custom_message: von Extensions injizierte Nachrichten, die in den Modellkontext eingehen (können in der UI verborgen sein)
• custom: Extension-Status, der nicht in den Modellkontext eingeht
• compaction: persistierte Kompaktierungszusammenfassung mit firstKeptEntryId und tokensBefore
• branch_summary: persistierte Zusammenfassung beim Navigieren eines Baumzweigs

​

Kontextfenster vs. erfasste Tokens

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

• Das Kontextfenster stammt aus dem Modellkatalog (und kann per Konfiguration überschrieben werden).
• contextTokens im Store ist ein Laufzeit-Schätzwert für Reporting; behandeln Sie ihn nicht als strikte Garantie.

​

Kompaktierung: was sie ist

• Die Kompaktierungszusammenfassung
• Nachrichten nach firstKeptEntryId

​

Wann Auto-Kompaktierung stattfindet (Pi-Runtime)

1. Overflow-Recovery: Das Modell liefert einen Kontext-Overflow-Fehler → komprimieren → erneut versuchen.
2. Schwellenwert-Wartung: nach einem erfolgreichen Turn, wenn:

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

​

Kompaktierungseinstellungen (reserveTokens, keepRecentTokens)

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

• Wenn compaction.reserveTokens < reserveTokensFloor, erhöht OpenClaw diesen.
• Standard-Mindestwert sind 20000 Tokens.
• Setzen Sie agents.defaults.compaction.reserveTokensFloor: 0, um den Mindestwert zu deaktivieren.
• Ist er bereits höher, lässt OpenClaw ihn unverändert.

​

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 Assistent beginnt seine Ausgabe mit NO_REPLY, um „keine Antwort an den Nutzer ausliefern“ zu signalisieren.
• OpenClaw entfernt/unterdrückt dies in der Auslieferungsschicht.

​

Pre-Kompaktions-„Memory-Flush“ (implementiert)

1. Überwachen der Session-Kontextnutzung.
2. Beim Überschreiten einer „Soft-Schwelle“ (unterhalb von Pis Kompaktierungsschwelle) einen stillen „Jetzt Speicher schreiben“-Befehl an den Agenten ausführen.
3. NO_REPLY verwenden, sodass der Nutzer nichts sieht.

• enabled (Standard: true)
• softThresholdTokens (Standard: 4000)
• prompt (User-Nachricht 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 zur Unterdrückung der Auslieferung.
• Der Flush läuft einmal pro Kompaktierungszyklus (nachverfolgt in sessions.json).
• Der Flush läuft nur für eingebettete Pi-Sessions (CLI-Backends überspringen ihn).
• Der Flush wird übersprungen, wenn der Session-Workspace schreibgeschützt ist (workspaceAccess: "ro" oder "none").
• Siehe Memory für das Layout der Workspace-Dateien und Schreibmuster.

​

Checkliste zur Fehlerbehebung

• Session-Schlüssel falsch? Beginnen Sie mit /concepts/session und bestätigen Sie den sessionKey in /status.
• Store vs. Transkript inkonsistent? Bestätigen Sie den Gateway-Host und den Store-Pfad aus openclaw status.
• Kompaktierungs-Spam? Prüfen Sie:
  • Modell-Kontextfenster (zu klein)
  • Kompaktierungseinstellungen (reserveTokens zu hoch für das Modellfenster kann frühere Kompaktierung verursachen)
  • Tool-Result-Aufblähung: Session-Pruning aktivieren/feinjustieren
• Stille Turns lecken? Bestätigen Sie, dass die Antwort mit NO_REPLY (exaktes Token) beginnt und Sie eine Build-Version mit dem Streaming-Unterdrückungs-Fix verwenden.