Skip to Content
👋 Willkommen bei HowToUseOpenClaw Schnellstart
GrundkonzepteSession

Sitzungsverwaltung

Sitzungen halten Konversationen geordnet. Ein Thread, eine Sitzung. OpenClaw treats one direct-chat session pro Agent as primary. Direct chats collapse to agent:<agentId>:<mainKey> (Standard main), while group/channel chats get their own keys. session.mainKey is honored. Use session.dmScope to control how Direktnachrichten are grouped:

  • main (Standard): all DMs share the main session für Kontinuität.
  • per-peer: isolate by sender id across channels.
  • per-channel-peer: isolate by channel + sender (empfohlen für Multi-User-Postfächer).
  • per-account-channel-peer: isolate by account + channel + sender (empfohlen für Multi-Account-Postfächer). Use session.identityLinks to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using per-peer, per-channel-peer, or per-account-channel-peer.

Gateway ist die Single Source of Truth

Der gesamte Sitzungs-State gehört dem Gateway (the “master” OpenClaw). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists und token counts instead of reading local files.

  • Im Remote-Modus, der für dich relevante Sitzungs-Store liegt auf dem Remote-Gateway-Host, nicht auf deinem Mac.
  • In UIs angezeigte Token-Zahlen come from the gateway’s store fields (inputTokens, outputTokens, totalTokens, contextTokens). Clients do not parse JSONL transcripts to “fix up” totals.

Wo der State liegt

  • Auf dem Gateway-Host:

    • Store-Datei: ~/.clawdbot/agents/<agentId>/sessions/sessions.json (pro Agent).

  • Transcripts: ~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl (Telegram-Themensitzungen verwenden .../<SessionId>-topic-<threadId>.jsonl).

  • Der Store ist eine Map sessionKey -> { sessionId, updatedAt, ... }. Einträge löschen ist unkritisch; sie werden bei Bedarf neu erstellt.

  • Gruppeneinträge können enthalten displayName, channel, subject, room, und space um Sitzungen in UIs zu beschriften.

  • Sitzungseinträge enthalten origin metadata (label + routing hints) damit UIs erklären können, woher eine Sitzung kommt.

  • OpenClaw liest keine Legacy-Pi/Tau-Sitzungsordner.

Sitzungs-Bereinigung

OpenClaw entfernt alte Tool-Ergebnisse aus dem In-Memory-Kontext standardmäßig direkt vor LLM-Aufrufen. Dadurch wird keine JSONL-Historie umgeschrieben. Siehe /concepts/session-pruning.

Memory-Flush vor Compaction

Wenn eine Sitzung sich der Auto-Compaction nähert, OpenClaw kann einen stummen Memory-Flush ausführen Turn, der das Modell an dauerhafte Notizen auf die Festplatte erinnert. Das läuft nur, wenn der Workspace beschreibbar ist. Siehe Memory and Compaction.

Transports → Sitzungsschlüssel zuordnen

  • Direktchats folgen session.dmScope (Standard main).

    • main: agent:<agentId>:<mainKey> (Kontinuität über Geräte/Kanäle).

      • Multiple phone numbers und channels can map to the same agent main key; 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 defaults to default).

    • If session.identityLinks matches a provider-prefixed peer id (for example telegram:123), the canonical key replaces <peerId> so the same person shares a session across channels.

  • Gruppenchats isolieren State: agent:<agentId>:<channel>:group:<id> (rooms/channels use agent:<agentId>:<channel>:channel:<id>).

    • Telegram-Forumsthemen hängen an :topic:<threadId> to the group id zur Isolation.
    • Legacy-group:<id>-Schlüssel werden zur Migration weiter erkannt.

  • Eingehende Kontexte können noch verwenden group:<id>; der Kanal wird abgeleitet aus Provider und normalized to the canonical agent:<agentId>:<channel>:group:<id> form.

  • Weitere Quellen:

    • Cron-Jobs: cron:<job.id>
    • Webhooks: hook:<uuid> (unless explicitly set by the hook)
    • Node-Läufe: node-<nodeId>

Lifecycle

  • Reset-Richtlinie: Sitzungen werden wiederverwendet bis sie ablaufen, und Ablauf wird bei der nächsten eingehenden Nachricht geprüft.
  • Täglicher Reset: Standard 4:00 Uhr Ortszeit auf dem Gateway-Host. Eine Sitzung ist veraltet, sobald ihr letztes Update vor der letzten täglichen Reset-Zeit liegt.
  • Leerlauf-Reset (optional): idleMinutes fügt ein gleitendes Leerlauffenster hinzu. Wenn sowohl täglicher als auch Leerlauf-Reset konfiguriert sind, was zuerst abläuft erzwingt eine neue Sitzung.
  • Legacy nur Leerlauf: if you set session.idleMinutes without any session.reset/resetByType config, OpenClaw stays in idle-only mode zur Abwärtskompatibilität.
  • Pro-Typ-Überschreibungen (optional): resetByType lets you override the policy for dm, group, und thread sessions (Thread = Slack/Discord-Threads, Telegram-Themen, Matrix-Threads wenn vom Connector geliefert).
  • Pro-Kanal-Überschreibungen (optional): resetByChannel overrides the reset policy for a channel (gilt für alle Sitzungstypen dieses Kanals und hat Vorrang vor reset/resetByType).
  • Reset-Trigger: exact /new or /reset (plus any extras in resetTriggers) starten eine neue Sitzungs-ID und leiten den Rest der Nachricht durch. /new <model> accepts a model alias, provider/model, or provider name (fuzzy match) to set the new session model. If /new or /reset is sent alone, OpenClaw runs a short “hello” greeting turn to confirm the reset.
  • Manueller Reset: bestimmte Schlüssel im Store löschen oder das JSONL-Transkript entfernen; die nächste Nachricht erstellt sie neu.
  • Isolierte Cron-Jobs erzeugen pro Lauf immer eine neue sessionId (kein Wiederverwenden im Leerlauf).

Send-Richtlinie (optional)

Zustellung blockieren for specific session types ohne einzelne IDs aufzulisten.

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

Laufzeit-Überschreibung (nur Besitzer):

  • /send on → allow for this session
  • /send off → deny for this session
  • /send inherit → clear override und use config rules Als eigenständige Nachrichten senden, damit sie erfasst werden.

Konfiguration (optionales Umbenennungsbeispiel)

// ~/.clawdbot/openclaw.json
{
  session: {
    scope: "per-sender",      // keep group keys separate
    dmScope: "main",          // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"]
    },
    reset: {
      // Defaults: mode=daily, atHour=4 (gateway host local time).
      // If you also set idleMinutes, whichever expires first wins.
      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: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",
    mainKey: "main",
  }
}

Inspecting

  • openclaw status — shows store path und recent sessions.
  • openclaw sessions --json — dumps every entry (filter with --active <minutes>).
  • openclaw gateway call sessions.list --params '{}' — fetch sessions from the running gateway (use --url/--token for remote gateway access).
  • Send /status as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, und when your WhatsApp web creds were last refreshed (helps spot relink needs).
  • Send /context list or /context detail to see what’s in the system prompt und injected workspace files (and the biggest context contributors).
  • Send /stop as a standalone message to abort the current run, clear queued followups for that session, und stop any sub-agent runs spawned from it (the reply includes the stopped count).
  • Send /compact (optional instructions) as a standalone message to summarize older context und free up window space. Siehe /concepts/compaction.
  • JSONL transcripts can be opened directly to review full turns.

Tips

  • Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
  • When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.

Session origin metadata

Each session entry records where it came from (best-effort) in origin:

  • label: human label (resolved from conversation label + group subject/channel)
  • provider: normalized channel id (including extensions)
  • from/to: raw routing ids from the inbound envelope
  • accountId: provider account id (when multi-account)
  • threadId: thread/topic id when the channel supports it The origin fields are populated for Direktnachrichten, channels, und groups. If a connector only updates delivery routing (for example, to keep a DM main session fresh), it should still provide inbound context so the session keeps its explainer metadata. Extensions can do this by sending ConversationLabel, GroupSubject, GroupChannel, GroupSpace, und SenderName in the inbound context und calling recordSessionMetaFromInbound (or passing the same context to updateLastRoute).
Zuletzt aktualisiert am:
Session-ToolSessions