OpenClaw-Migration und Cold-Start-Runbook 2026: Von kopierten Verzeichnissen bis zum ersten Gateway-Link (systemd vs. launchd)

1. Schmerzpunkte: kopierte Bäume laufen nicht von allein

Teams, die von Laptops oder älteren VPS-Hosts migrieren, nehmen oft stillschweigend an: Wenn die Verzeichnisliste stimmt, verhält sich die Software genauso. OpenClaw hängt in der Praxis jedoch an vier gekoppelten Schichten: welches openclaw-Binary auf dem PATH gewinnt, der Konfigurationsbaum unter ~/.openclaw auf der Platte, workspace-relative Artefakte sowie der Supervisor-Kontext, den systemd oder launchd bereitstellt. Fehlt eine Schicht, entstehen intermittierende Symptome – etwa ein Gateway, das in einer SSH-Sitzung tadellos läuft, nach Disconnect oder Reboot aber spurlos verschwindet.

Das ist kein „Bug im Produkt“, sondern ein klassisches Integrationsproblem zwischen Paketmanager, Shell-Profilen und Dienst-Orchestrierung. Je näher die Zielumgebung an einem frischen Cloud-Image liegt, desto wahrscheinlicher sind Diskrepanzen: Auf dem alten Host war vielleicht ein global installiertes npm-Paket aktiv, während das neue Mac-Cloud-Image nur Homebrew-Pfade oder ein statisches Install-Skript mitbringt. JSON-Dateien zu kopieren installiert keine Binaries. In pnpm-Workspaces plus globalen Paketen sehen Versionsstrings sogar identisch aus, während sich dynamische Loader-Pfade unterscheiden – ein Paradebeispiel für scheinbar unmögliche Regressionen.

1. CLI-Drift zwischen Maschinen: Der alte Host nutzte global npm, der neue nur Homebrew oder ein dediziertes Installationslayout. Ohne explizite Festlegung des Einstiegspunkts landen Operatoren schnell auf zwei verschiedenen Binaries, ohne es zu merken.
2. Gebrochener Daemon-Kontext: Unter Linux deklarieren systemd --user-Units oft explizit Environment=HOME=.... Unter macOS erben LaunchAgents keine Login-Shell-rc-Dateien; nvm-ähnliche Präfixe verschwinden, wenn Sie keine absoluten Pfade oder ein dünnes Wrapper-Skript einbetten. Ein falsches WorkingDirectory lenkt Logs und Credential-Lookups still an die falsche Stelle.
3. Falsche Triage-Reihenfolge: Wenn Sie Kanal-Pairing prüfen, bevor openclaw.json syntaktisch valide ist und Port 18789 lokal erreichbar wirkt, verbrennen Sie Stunden. Lokale Sonden müssen grün sein, bevor Sie Messaging-Oberflächen anfassen.
4. Eigentümerschaft nach rsync: Als root kopiert und später an einen Anwendungsnutzer übergebene Bäume sind oft lesbar, aber für Stderr-Logs nicht beschreibbar – stumme Fehler, die wie mysteriöse Hänger wirken.

Ein belastbares Runbook beginnt deshalb nicht mit „Kanal neu verbinden“, sondern mit einer kurzen Inventur: Welches Medium liefert das Binary, welche UID schreibt Logs, welche Unit-Datei startet den Prozess, und welche Umgebungsvariablen sieht der Prozess wirklich – nicht der menschliche Operator in SSH.

2. systemd versus launchd: Umgebungsmatrix

Nutzen Sie die folgende Tabelle als Anhang zum Change-Ticket. Die Spalte „Erster Stopp“ fasst zusammen, was Betrieb auf dem Host prüfen sollte, bevor Chat-Provider oder Firewalls die Schuld bekommen.

Ist das Ziel eine langlebige Mac-Cloud-Instanz, empfiehlt sich zuerst, absolute Pfade und Logdateien in launchd festzuzurren und erst danach zu entscheiden, ob sich Docker-Partitionierung den zusätzlichen Volume- und UID-Aufwand lohnt. Unter Linux: Wenn Sie bereits andere User-Level-Daemons unter systemd --user betreiben, richten Sie OpenClaw in dieselben Slice-Limits ein, damit ein schwerer xcodebuild-Nachbar Gateway-Antworten nicht aushungert.

Die Matrix ersetzt keine detaillierte Unit-Review, aber sie standardisiert die Fragen, die zwei Teams mit unterschiedlichem Hintergrund (Linux-SRE versus macOS-Automation) gleich beantworten können. Das reduziert Missverständnisse in Nachtfenstern, in denen niemand Lust auf Debatten über „ob launchd eigentlich eine Shell ist“ hat.

3. Sieben Schritte bis zum ersten erfolgreichen Link

Diese Schritte stellen menschenlesbare Signale nach vorne und schieben alles, was externe Konten braucht, nach hinten. Für Overnight-Cutover notieren Sie pro Schritt die erwarteten Minuten im Wartungsfenster – der Incident Lead kann dann „weiter“ oder „Rollback“ entscheiden, ohne Scope ad hoc neu zu verhandeln.

1. Version und Medium einfrieren: Auf dem alten Host openclaw --version, npm versus pnpm versus Install-Skript versus Image-Digest dokumentieren. Auf dem neuen Host einen einzigen Einstieg wählen – siehe Installationspfad-Artikel – bevor Sie Bäume kopieren, damit nie zwei Binaries parallel laufen.
2. Verzeichnisse synchronisieren: rsync -aH oder Äquivalent für ~/.openclaw und den Workspace, Team-Excludes für große Caches respektieren. Direkt danach mtimes und Größen kritischer Dateien vergleichen, um Teilübertragungen früh zu erwischen.
3. Berechtigungen und Secret-Erreichbarkeit: ls -la ~/.openclaw. Bei Docker-Flows Bind-Mounts und UID-Mapping anhand des Docker-Abschnitts im Installationsleitfaden erneut validieren.
4. Service-Unit verfassen: Linux erhält eine systemd --user-Unit mit expliziten Umgebungszeilen. macOS einen LaunchAgent, dessen ProgramArguments absolute Pfade zu openclaw nutzen. Listenadresse und Port explizit kodieren, wenn Defaults zwischen Releases wechseln.
5. Laden und Cold Start: systemctl --user daemon-reload && restart oder launchctl bootstrap gefolgt von kickstart. Elternprozess muss systemd oder launchd sein, keine SSH-Sitzung.
6. Lokale Sonden: lsof -i :18789, minimale JSON-Validierung, dann openclaw doctor gemäß Doctor-Leiter-Artikel. Keine Kanal-Token rotieren, solange Sonden rot sind.
7. Kanal-Smoke-Test: Erst wenn Gateway-Logs gesund wirken, Pairing reparieren. Kommando-Transkripte im Change-Record für Auditoren festhalten.

4. Referenz: Pfade, Port 18789, Auditfelder

Dieser Abschnitt ist das Wiki-Anhang; die nummerierten Schritte oben sind die Erzählung. Zusammen liefern sie Sequenz und Checklist-Tiefe für Postmortems.

• Single Source of Truth für JSON: Dokumentieren, welche Maschine den kanonischen openclaw.json besitzt und wie Backups laufen. Nach Migration alte und neue Datei diffen, bevor Dienste starten – halbfertige Merges vermeiden.
• Port-Kollision: Mehrere Lab-Gateways auf einem Mac-Cloud-Host brauchen getrennte Ports oder gestoppte Labels. Kollision tarnt sich oft als flaky Connectivity.
• Audit-Minimum: Medium, Semver, Unit- oder plist-Label, Image-Digest falls containerisiert, erste grüne Doctor-Zusammenfassung, Kanal-Account-ID, Pairing-Zeitstempel, Operator-IDs in regulierten Umgebungen.
• Rollback: Letzte bekannte-gut-Unit-Datei plus Paket- oder Image-Tag auf dem alten Host aufbewahren. Quartals-Drills stellen sicher, dass seit dem Snapshot rotierte Keys innerhalb des RTO wiederherstellbar sind.
• Upstream-Risiken: Wenn Installations- und Supervisor-Schichten grün sind, ClawHub-Skill-Supply-Chain mit dem April-2026-Audit-Checklisten-Artikel adressieren.
• Zeitzonen: Beim Korrelieren von Datei-Logs über Regionen NTP und angezeigte Zeitzonen angleichen, bevor Kausalität inferiert wird.

5. FAQ

F: Ich habe nur den Workspace kopiert, nicht ~/.openclaw. Kann das Gateway trotzdem starten?
Nein zuverlässig: Schlüssel und lokaler Zustand fehlen. Entweder beide Bäume migrieren oder Secrets bewusst mit Read-only-Export-Checkliste vom alten Host neu aufbauen.

F: launchctl zeigt „loaded“, aber auf 18789 lauscht nichts?
StandardErrorPath, WorkingDirectory und plist-PATH prüfen. Leere Fehlerdateien können bedeuten, dass Logs auf einen nicht beschreibbaren Pfad zeigen.

F: Kann ich meine Linux-systemd-Unit unter macOS wiederverwenden?
Nein. Als LaunchAgent neu schreiben und Umgebungsvariablen sowie Logpfade Zeile für Zeile neu validieren.

F: Kanal ist stumm, 18789 antwortet lokal?
Zuerst Gateway-Logs, dann Upstream-Netz und Allowlists. Nicht gleich die gesamte Konfiguration verwerfen, bevor Bind-Adress-Mismatches nach letzten Edits ausgeschlossen sind.

F: Ich will eine parallele Altinstanz zum Vergleich?
Getrennte Ports und Labels; Produktions-JSON darf von der Lab-Unit nicht beschrieben werden, um Doppel-Schreiber-Korruption zu verhindern.

6. Vom Piloten zur Produktion auf nativer Mac-Cloud

Runbook-Komplexität skaliert mit dem Abstand zwischen SSH-Zugang und Produktion. Nested Virtualization verstärkt Überraschungen bei PATH, Volumes und Rechten. Ein dedizierter Mac-Cloud-Host mit launchd, ausgerichtet am Installationsleitfaden, ist der kürzeste Weg zu auditierbaren Cold Starts. Docker-Sandboxes erst ergänzen, wenn der native Pfad langweilig stabil ist – nicht im ersten Migrationsfenster.

Betrachten Sie langlebige OpenClaw-Gateways als Infrastruktur-Gleichgestellte zu CI-Runnern: Disk reservieren, Logs rotieren, Nodes taggen, Login-Auditing verdrahten. Wenn jedes Teammitglied denselben plist- und Verzeichnisvertrag befolgt, wiederholen spätere Migrationen ein bekanntes Playbook statt improvisierter Laptop-Sonderwege.