2026-05-08 OpenClaw: Sitzungs-Checkpoints und Wiederherstellung nach Gateway-Neustart auf headless gemietetem Apple-Silicon-Cloud-Mac (HK / JP / KR / SG / US)

Kurz nachdem Health-Probes stabil laufen, startet launchctl das Gateway während eines npm-Upgrades neu und Slack schreit: „Der Bot hat alles vergessen.“ Das Modell hat nichts vergessen — die Persistenzgrenzen haben sich verschoben, weil OPENCLAW_STATE_DIR nicht gesichert wurde oder Cleaner Scratch neben CI-Artefakten löschen. Auf gemieteten Mac mini M4 in Hongkong, Tokio, Seoul, Singapur und den USA behandeln Sie Sitzungsreste als Datenebenen-Zustand mit derselben Ernsthaftigkeit wie Signaturschlüssel. Dieser Guide 2026-05-08 zeigt, wie Checkpoint-Verzeichnisse mit launchd-Umgebungen zusammenspielen, wie Sie Recovery mit synthetischem Traffic üben und Signale aus strukturiertem Logging, KeepAlive-Triage, Gateway-Upgrade und Rollback sowie den neuen Dateitransfer-Plugin-Richtlinien bündeln, bis Neustarts langweilig werden.

Warum Gateway-Neustarts den Dienst noch überraschen

OpenClaw verbindet schnelle Iteration mit langlebiger Automatisierung. Wenn npm-Postinstalls Globals ändern oder ein Engineer per SSH unter demselben Benutzer wie CI arbeitet, kann der Prozess sauber neu starten und trotzdem eine andere Umgebungssemantik laden. Ohne Checkpoint-Disziplin verlieren Sie Transkripte, Webhook-Dedup-Caches und Tool-Allowlists. Dokumentieren Sie erwartete Persistenz im selben README wie Ihre launchctl-Labels.

Aufbau von OPENCLAW_STATE_DIR

Denken Sie in Schichten:

• Sitzungshinweise — Gesprächsgerüst, das Ops nach Reconnect erwarten.
• Tool-Caches — begrenzte Metadaten, die kurze Gateway-Pausen überstehen.
• Webhook-Buchführung — Dedup-Schlüssel gegen Doppelausführung.

Trennen Sie Schichten per Mount oder ACL, damit CI-Cleaner nicht zum Assistentenzustand hochwandern. Bei gemeinsamer UID nutzen Sie die Leitlinien zu parallelen CI-Lanes.

launchd: ThrottleInterval, Exit-Codes, Respawns

Bei aggressiven KeepAlive-Richtlinien startet launchd schneller neu, als Menschen merken. Ergänzend lesen Sie die Respawn-Triage: Exit-Codes loggen, ThrottleInterval gegen enge Crash-Loops prüfen, StandardOutPath für stderr-Splits. Nach plist-Änderungen immer das curl-Matrix aus Health-Probes fahren, bevor Sie gewinnen.

Checkpoint-Playbook vor Wartungsfenstern

1. Einfrieren: npm/Mint-Pins festziehen und Abhängigkeitsbaum exportieren.
2. Sicherung: OPENCLAW_STATE_DIR per tar oder APFS-Snapshot.
3. Informieren: Webhook-Anbieter über mögliche Doppel-Lieferungen bei Replay-Tests.
4. Neustart: Gateway per launchctl kickstart, nicht mit Ad-hoc-kill -9.
5. Prüfen: Dedup-Schlüssel füllen sich wieder bei synthetischen Inbound-Ereignissen.

Veröffentlichen Sie Wandzeit pro Schritt, damit Finanzen zusätzliche Witness-Nodes gegen längeres Incident-MTTR abwägen können.

Fehlermatrix

Symptom	Wahrscheinliche Ursache	Minderung
Doppelte Kundenmails nach Neustart	Dedup-Cache geleert	Replay-sichere Webhook-IDs + externes Journal
Tool-Verweigerungen nach Upgrade	Policy-Dateien nicht migriert	Allowlists versionskontrolliert laut Plugin-Doku
Höherer RSS nach Neustart	Skills-Bundle doppelt geladen	npm ls mit Tarball-Backup vergleichen

Plugins und Dateitransfer-Nähe

Das Dateitransfer-Plugin vom 2026-05-07 fügt Dateisystem-Semantik hinzu, die Neustarts überstehen muss: leben Allowlists nur in flüchtigen Umgebungsvariablen, verengt ein Neustart den Zugriff still. Persistieren Sie Policies unter dem Zustandsbaum per Git oder versiegelten Configs. Kombinieren Sie mit Chunking-Disziplin, damit fortgesetzte Sitzungen keine Riesen-Fetches starten.

Strukturierte Logs & Korrelations-IDs

Jedes Gateway-Event soll Session-ID, Gateway-Generation und Restart-Nonce tragen, damit Grafana Pre/Post-Bounce trennt. Verknüpfen Sie nginx-Kanten gemäß Reverse-Proxy-Leitfaden, wenn Replay-Tests Inbound-Spitzen erzeugen.

Achtstufiges Recovery-Runbook

1. Neustart via Prozessstartzeit vs. Heartbeat-Drift erkennen.
2. Tarball-Hash des Zustandsverzeichnisses mit Live-Disk vergleichen.
3. Synthetische CLI-Konversation gegen Staging-Kanal.
4. Webhook-Beispiel mit Idempotency-Tokens replayen.
5. Plugin-Policies verifizieren, dass unerwünschte Roots weiter abgelehnt werden.
6. Bei Verdacht auf Korruption npm-Pin vorziehen.
7. Incident-Timeline mit Restart-Nonce dokumentieren.
8. Retro planen, ob Witness-Node MTTR verkürzt.

SLO-Tabelle

Signal	Schwelle	Aktion
Fehler beim Sitzungs-Resume	> 0,5 % der Reconnects	Deploys einfrieren; plist-Umgebung prüfen
Dedup-Kollisionen	Jede doppelte Nebenwirkung	Integrität Replay-Journal prüfen
Checkpoint-Tarball-Alter	> 36 h veraltet	Nächtliche Snapshot-Jobs automatisieren

FAQ

Frage	Praktische Antwort (2026-05-08)
ZFS-/APFS-Snapshots?	Je nach Lease — mit Anbieter abstimmen; sonst Tarball zum Objektspeicher.
Checkpoints regionsübergreifend syncen?	Nein — Sitzungen regional; Konfiguration replizieren, keine lebenden Chat-Caches.

Warum Mac mini M4 zu zustandsbehafteten Gateways passt

Einheitlicher Speicher und schnelles NVMe machen Checkpoint-Snapshots und Tarball-Vergleiche unter Incident-Druck machbar — vorhersagbare Hardware schlägt laute Nachbarn, wenn Gigabyte-Zustandsbäume diffen. Budget: regionale Preise; Onboarding: Hilfe-Dokumentation plus optional VNC, wenn GUI-Zustimmung nicht vermeidbar ist.