Session-Verwaltung

OpenClaw behandelt eine Direct-Chat-Session pro Agent als primär. Direct Chats werden zu agent:<agentId>:<mainKey> (Standard: main) zusammengefasst, während Gruppen- und Channel-Chats eigene Keys bekommen. session.mainKey wird berücksichtigt.

Mit session.dmScope steuerst du, wie Direktnachrichten gruppiert werden:

  • main (Standard): Alle DMs teilen sich die Haupt-Session für Kontinuität.
  • per-peer: Isolierung nach Absender-ID über alle Channels hinweg.
  • per-channel-peer: Isolierung nach Channel + Absender (empfohlen für Multi-User-Postfächer).
  • per-account-channel-peer: Isolierung nach Account + Channel + Absender (empfohlen für Multi-Account-Postfächer). Mit session.identityLinks kannst du Provider-präfixierte Peer-IDs auf eine kanonische Identität mappen, sodass dieselbe Person bei per-peer, per-channel-peer oder per-account-channel-peer eine gemeinsame DM-Session über alle Channels hinweg nutzt.

Gateway ist die Quelle der Wahrheit

Der gesamte Session-Status gehört dem Gateway (dem „Master”-OpenClaw). UI-Clients (macOS-App, WebChat usw.) müssen das Gateway nach Session-Listen und Token-Zählern abfragen, anstatt lokale Dateien zu lesen.

  • Im Remote-Modus liegt der Session-Store, der dich interessiert, auf dem Remote-Gateway-Host, nicht auf deinem Mac.
  • Token-Zähler in UIs stammen aus den Store-Feldern des Gateways (inputTokens, outputTokens, totalTokens, contextTokens). Clients parsen keine JSONL-Transkripte, um Summen zu „korrigieren”.

Wo der Status gespeichert wird

  • Auf dem Gateway-Host:
    • Store-Datei: ~/.openclaw/agents/<agentId>/sessions/sessions.json (pro Agent).
  • Transkripte: ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl (Telegram-Topic-Sessions nutzen .../<SessionId>-topic-<threadId>.jsonl).
  • Der Store ist eine Map sessionKey -> { sessionId, updatedAt, ... }. Einträge löschen ist sicher; sie werden bei Bedarf neu erstellt.
  • Gruppeneinträge können displayName, channel, subject, room und space enthalten, um Sessions in UIs zu beschriften.
  • Session-Einträge enthalten origin-Metadaten (Label + Routing-Hinweise), damit UIs erklären können, woher eine Session stammt.
  • OpenClaw liest keine Legacy-Pi/Tau-Session-Ordner.

Session Pruning

OpenClaw entfernt standardmäßig alte Tool-Ergebnisse aus dem In-Memory-Context direkt vor LLM-Aufrufen. Das schreibt die JSONL-History nicht um. Siehe Session Pruning.

Pre-Compaction Memory Flush

Wenn eine Session sich der Auto-Compaction nähert, kann OpenClaw einen stillen Memory Flush-Turn ausführen, der das Modell daran erinnert, dauerhafte Notizen auf die Festplatte zu schreiben. Das läuft nur, wenn der Workspace beschreibbar ist. Siehe Memory und Compaction.

Mapping von Transports zu Session Keys

  • Direct Chats folgen session.dmScope (Standard: main).
    • main: agent:<agentId>:<mainKey> (Kontinuität über Geräte/Channels hinweg).
      • Mehrere Telefonnummern und Channels können auf denselben Agent-Main-Key mappen; sie fungieren als Transports in eine Konversation.
    • per-peer: agent:<agentId>:dm:<peerId>.
    • per-channel-peer: agent:<agentId>:<channel>:dm:<peerId>.
    • per-account-channel-peer: agent:<agentId>:<channel>:<accountId>:dm:<peerId> (accountId ist standardmäßig default).
    • Wenn session.identityLinks eine Provider-präfixierte Peer-ID matcht (z.B. telegram:123), ersetzt der kanonische Key <peerId>, sodass dieselbe Person eine Session über alle Channels teilt.
  • Gruppen-Chats isolieren den Status: agent:<agentId>:<channel>:group:<id> (Rooms/Channels nutzen agent:<agentId>:<channel>:channel:<id>).
    • Telegram-Forum-Topics hängen :topic:<threadId> an die Gruppen-ID für Isolierung an.
    • Legacy-group:<id>-Keys werden für Migration weiterhin erkannt.
  • Inbound-Contexts können weiterhin group:<id> verwenden; der Channel wird aus Provider abgeleitet und zur kanonischen Form agent:<agentId>:<channel>:group:<id> normalisiert.
  • Andere Quellen:
    • Cron-Jobs: cron:<job.id>
    • Webhooks: hook:<uuid> (außer explizit vom Hook gesetzt)
    • Node-Runs: node-<nodeId>

Lebenszyklus

  • Reset-Policy: Sessions werden wiederverwendet, bis sie ablaufen. Der Ablauf wird bei der nächsten eingehenden Nachricht geprüft.
  • Täglicher Reset: Standard ist 4:00 Uhr Ortszeit auf dem Gateway-Host. Eine Session ist veraltet, sobald ihr letztes Update vor der letzten täglichen Reset-Zeit liegt.
  • Idle-Reset (optional): idleMinutes fügt ein gleitendes Idle-Fenster hinzu. Wenn sowohl täglicher als auch Idle-Reset konfiguriert sind, erzwingt der zuerst ablaufende eine neue Session.
  • Legacy Idle-Only: Wenn du session.idleMinutes ohne session.reset/resetByType-Config setzt, bleibt OpenClaw aus Kompatibilitätsgründen im Idle-Only-Modus.
  • Per-Type-Overrides (optional): Mit resetByType kannst du die Policy für dm-, group- und thread-Sessions überschreiben (thread = Slack/Discord-Threads, Telegram-Topics, Matrix-Threads, wenn vom Connector bereitgestellt).
  • Per-Channel-Overrides (optional): resetByChannel überschreibt die Reset-Policy für einen Channel (gilt für alle Session-Typen dieses Channels und hat Vorrang vor reset/resetByType).
  • Reset-Trigger: Exaktes /new oder /reset (plus Extras in resetTriggers) starten eine neue Session-ID und leiten den Rest der Nachricht weiter. /new <model> akzeptiert einen Model-Alias, provider/model oder Provider-Namen (Fuzzy-Match), um das neue Session-Modell zu setzen. Wenn /new oder /reset allein gesendet wird, führt OpenClaw einen kurzen „Hallo”-Begrüßungs-Turn aus, um den Reset zu bestätigen.
  • Manueller Reset: Lösche bestimmte Keys aus dem Store oder entferne das JSONL-Transkript; die nächste Nachricht erstellt sie neu.
  • Isolierte Cron-Jobs erstellen immer eine neue sessionId pro Run (keine Idle-Wiederverwendung).

Send Policy (optional)

Blockiere die Zustellung für bestimmte Session-Typen, ohne einzelne IDs aufzulisten.

{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } },
      ],
      default: "allow",
    },
  },
}

Runtime-Override (nur Owner):

  • /send on → für diese Session erlauben
  • /send off → für diese Session verweigern
  • /send inherit → Override löschen und Config-Regeln verwenden Sende diese als eigenständige Nachrichten, damit sie registriert werden.

Konfiguration (optionales Beispiel)

// ~/.openclaw/openclaw.json
{
  session: {
    scope: "per-sender", // Gruppen-Keys getrennt halten
    dmScope: "main", // DM-Kontinuität (setze per-channel-peer/per-account-channel-peer für geteilte Postfächer)
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      // Standards: mode=daily, atHour=4 (Gateway-Host-Ortszeit).
      // Wenn du auch idleMinutes setzt, gewinnt der zuerst ablaufende.
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      dm: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    mainKey: "main",
  },
}

Inspektion

  • openclaw status — zeigt Store-Pfad und aktuelle Sessions.
  • openclaw sessions --json — gibt alle Einträge aus (filtern mit --active <minutes>).
  • openclaw gateway call sessions.list --params '{}' — Sessions vom laufenden Gateway abrufen (nutze --url/--token für Remote-Gateway-Zugriff).
  • Sende /status als eigenständige Nachricht im Chat, um zu sehen, ob der Agent erreichbar ist, wie viel Session-Context verwendet wird, aktuelle Thinking/Verbose-Toggles und wann deine WhatsApp-Web-Credentials zuletzt aktualisiert wurden (hilft, Relink-Bedarf zu erkennen).
  • Sende /context list oder /context detail, um zu sehen, was im System-Prompt und den injizierten Workspace-Dateien ist (und die größten Context-Verbraucher).
  • Sende /stop als eigenständige Nachricht, um den aktuellen Run abzubrechen, wartende Followups für diese Session zu löschen und alle von ihr gestarteten Sub-Agent-Runs zu stoppen (die Antwort enthält die Anzahl der gestoppten).
  • Sende /compact (optionale Anweisungen) als eigenständige Nachricht, um älteren Context zusammenzufassen und Fensterplatz freizugeben. Siehe Compaction.
  • JSONL-Transkripte können direkt geöffnet werden, um vollständige Turns zu überprüfen.

Tipps

  • Halte den primären Key für 1:1-Traffic reserviert; lass Gruppen ihre eigenen Keys behalten.
  • Beim automatisierten Aufräumen lösche einzelne Keys statt des gesamten Stores, um Context anderswo zu erhalten.

Session Origin Metadata

Jeder Session-Eintrag speichert (best-effort), woher er stammt, in origin:

  • label: Menschenlesbares Label (aufgelöst aus Konversations-Label + Gruppen-Subject/Channel)
  • provider: Normalisierte Channel-ID (inklusive Extensions)
  • from/to: Rohe Routing-IDs aus dem Inbound-Envelope
  • accountId: Provider-Account-ID (bei Multi-Account)
  • threadId: Thread/Topic-ID, wenn der Channel das unterstützt Die Origin-Felder werden für Direktnachrichten, Channels und Gruppen befüllt. Wenn ein Connector nur das Delivery-Routing aktualisiert (z.B. um eine DM-Main-Session frisch zu halten), sollte er trotzdem Inbound-Context bereitstellen, damit die Session ihre Erklärungs-Metadaten behält. Extensions können das tun, indem sie ConversationLabel, GroupSubject, GroupChannel, GroupSpace und SenderName im Inbound-Context senden und recordSessionMetaFromInbound aufrufen (oder denselben Context an updateLastRoute übergeben).