OpenClaw dokumentiert einen gemeinsamen Session Controller für Gateway und Adapter

Wer einen OpenClaw-Agenten in mehreren Chats gleichzeitig laufen lässt, stößt früher oder später auf zwei Fragen. Welche Arbeit darf eine Session als Nächstes nutzen? Und warum fällt ein Heartbeat aus, obwohl der Agent scheinbar nur woanders beschäftigt ist? Beide Fragen hängen zusammen. Die erste beantwortet OpenClaw mit einem gemeinsamen Session Controller, die zweite mit einer eng gefassten Heartbeat-Regel.

Was der Session Controller koordiniert

Nach Angaben von OpenClaw koordiniert der Controller angenommene Eingaben, den aktuellen Turn und Zulassungsbarrieren. Gateway-, Channel-, Direct-Native-, Maintenance- und Lifecycle-Adapter teilen sich dabei denselben Owner. Einen weiteren Session-Scheduler gibt es nicht: Die In-Memory-Implementierung erweitert den bestehenden Reply-Operation-Owner.

Gateway-Protokolle und gespeicherte Daten bleiben unverändert; eine dauerhafte Mailbox wäre eine eigene Speicheränderung. Als Invariante nennt OpenClaw höchstens einen aktuellen Scheduling-Owner pro kanonischer Session-Identität, und alle Scheduling-Abfragen lesen denselben Owner.

Kurz: eine Session, ein Zuständiger.

Vier Identitäten statt eines Session-Namens

OpenClaw unterscheidet einen logischen Session-Key, eine gespeicherte Session-Inkarnation, eine Reply-Operation und einen Backend-Versuch. Ein Reset kann eine gespeicherte Session ersetzen, ein Retry das Backend, ohne dass ein neuer Nutzer-Turn beginnt. Endet eine frühere Operation, darf ihr Nachfolger nach den Vorgaben der Seite nie über den Session-Key wiedergefunden werden. Generation-Checks bleiben auch ohne Gateway-Neustart nötig, weil alte Callbacks einen Reset, Rechteänderungen oder eine Ersetzung überdauern können.

Auch Stores spielen hinein. Gleiche logische Keys in verschiedenen Stores bleiben unabhängig, weil der physische Store-Bereich in die Auswahl einfließt. Eine mehrdeutige Abfrage nur über den Key wählt laut OpenClaw nie willkürlich eine Session aus.

Für Wiederholungslogik gilt noch etwas. Laufzeitannahme und Transkript-Commit sind nach OpenClaw getrennte Fakten, und eine verlorene Bestätigung nach möglichem Commit macht eine Eingabe nicht sicher wiederholbar. Ich lese das als klare Absage an blindes Nachsenden. Mehr zum Thema steht in unserem Beitrag zu Agenten-Retries.

Welche Eingaben der Controller sieht

Die Liste ist lang. Zu den Eingaben zählt OpenClaw Channel-Nachrichten, Gateway-Nutzer-Turns, Agent-RPC-Turns, geplante Wakes, Heartbeats, Übergaben abgeschlossener Subagenten und Resends aus der Restart-Recovery. Adapter behalten dabei Authentifizierung, Sichtbarkeit, Routing, Idempotenz und Bestätigungsvertrag des jeweiligen Eingabe-Owners; eine gemeinsame Scheduling-Schnittstelle macht diese Eingaben nicht gleichwertig.

Stop und Lifecycle-Anfragen bilden eine Ausnahme. Der Controller behandelt sie als Kontrollereignisse: Sie dürfen weder hinter der Arbeit warten, die sie abbrechen sollen, noch durch normalen Mailbox-Überlauf verworfen werden. Das Preemption-Settlement begrenzt OpenClaw standardmäßig auf 15 Sekunden.

Heartbeats: Nur die eigene Ziel-Session zählt

Ein Heartbeat ist laut OpenClaw ein geplanter Turn, der standardmäßig in der Main-Session des Agenten läuft; über das Feld session lässt sich stattdessen eine bestimmte Channel-Session festlegen.

Nimm eine hypothetische Lage: Dein Agent arbeitet in einem Gruppenchat an einer längeren Aufgabe, während der nächste Heartbeat fällig wird. Blockiert das den Heartbeat? Nein. Ein Heartbeat wird nur verworfen, wenn seine eigene Ziel-Session beschäftigt ist.

Die Mailbox dieser Session lehnt einen Heartbeat-Turn ab, solange dort ein aktiver oder wartender Turn liegt, und vermerkt den Skip als requests-in-flight. Turns in anderen Sessions desselben Agenten, die Main-Queue und laufende Automationen verzögern Heartbeats laut der Heartbeat-Dokumentation nicht, und Geschwister-Agenten pausieren sich nicht gegenseitig.

Für verworfene Wakes gilt:

• Ein verworfener, ereignisfreier Monitor-Poll wird als übersprungen erfasst und wartet auf seinen nächsten persistierten Takt, statt es erneut zu versuchen.
• Wakes mit wartenden Events oder geplanten Tasks sowie isolierte Heartbeat-Läufe versuchen es erneut, bis ihre Session frei ist.
• Eine gezielte Abschlussmeldung eines Hintergrundbefehls wartet nur auf ihre eigene Session, einschließlich der Recovery der finalen Zustellung.

Nach einem Neustart gilt eine Sonderregel. Ein Resend aus der Restart-Recovery zählt laut OpenClaw als wartende Arbeit, sobald sein Turn als unterbrochen markiert ist. Kein Heartbeat läuft davor, auch kein manueller.

Zum Weiterlesen: OpenClaw schafft HEARTBEAT.md ab: Was aus Heartbeats, Tasks und Cronjobs wird.

Woran du einen regulären Skip erkennst

Nicht jeder fehlende Heartbeat ist ein Fehler. Die Heartbeat-Dokumentation nennt mehrere Skip-Gründe mit eigenem Vermerk: requests-in-flight bei beschäftigter Ziel-Session, reason=no-route, wenn sich keine Direktnachricht an den Betreiber auflösen lässt, und reason=alerts-disabled, wenn showOk, showAlerts und useIndicator abgeschaltet sind. Außerhalb konfigurierter aktiver Stunden werden Heartbeats ebenfalls bis zum nächsten Takt im Zeitfenster übersprungen. Den letzten Heartbeat-Event zeigt openclaw system heartbeat last.

Anders liegt der Fall, wenn gar keine geplanten Heartbeats laufen. Ist cron.enabled auf false gesetzt oder OPENCLAW_SKIP_CRON=1 aktiv, protokolliert das Gateway laut OpenClaw beim Start eine Warnung und führt keine geplanten Heartbeats aus.

Meine Reihenfolge bei der Fehlersuche wäre deshalb: erst den vermerkten Skip-Grund, dann die Ziel-Session, zuletzt die Automationen.

Wo die Grenzen liegen

OpenClaw grenzt den Controller ausdrücklich ab: Er ersetzt weder Runtime-Ausführungsautorität noch Datenbank-Write-Fencing oder prozessweite Parallelitätslimits. Die globale Lane und Kapazitätsgruppen steuern weiterhin die Parallelität über Sessions hinweg. Datenbank- und Worker-Placement-Owner prüfen ihre eigenen maßgeblichen Ansprüche weiterhin unmittelbar vor Effekten, und globale Kapazität bleibt gehalten, bis die tatsächliche Ausführung abgeschlossen ist.

Beim Abbrechen ist Vorsicht angebracht. Ein angeforderter Abbruch ist laut OpenClaw noch kein abgeschlossener Abbruch. Und wird der Scheduling-Slot freigegeben, heißt das nicht, dass jeder alte Schreibvorgang abgeschlossen ist.

Die Mailbox des Controllers ist prozesslokal und führt keinen neuen Replay- oder Speichervertrag ein. Die Erholung eines blockierten Prozesses kann kein In-Process-Statechart allein garantieren, räumt die Seite ein.

Was du für deinen Betrieb mitnimmst

Plane Retries entlang der getrennten Identitäten, statt dich auf den Session-Key allein zu verlassen. Lies den Controller als Zuständigkeitsregel für Turns; Datenbank- und Kapazitätsschutz bleiben eigene Baustellen. Und fehlt ein Heartbeat, prüfe zuerst seine Ziel-Session und den vermerkten Grund.

Der Controller schafft klare Zuständigkeiten. Garantien für alles liefert er nicht.