OPENCLAW_2026
MIGRATE_
WORKSPACE_
STATE_GATEWAY.

1. Schmerz-Zerlegung: Repo kopieren ≠ Laufzeit kopieren

(1) Zustandsverzeichnis vs. Workspace: Teams lagern Skills, Prompts und eingechecktes openclaw.json im Repository, während Sitzungen, Kanalbindungen und Gateway-Caches unter dem Benutzerprofil liegen. Wer nur Git migriert, erhält zwar CLI-Befehle, aber Geister-Sitzungen oder leeren Kanalzustand auf dem Ziel. (2) Secrets und OAuth-Refresh-Token verteilen sich: Slack, Discord und Enterprise-IM können Token sowohl im Klartext als auch in verschlüsselten Laufzeit-Speichern halten. Sichert man nur eine Schicht, folgt Re-Autorisierung; stoppt man das alte Gateway nicht, konkurrieren zwei Endpunkte um dieselbe Bot-Sitzung. (3) launchd vs. interaktive Shell: launchd erbt keine Exporte aus .zshrc; API-Schlüssel nur im Terminalprofil, die Plist bleibt leer — klassisches „Vordergrund manuell ok, geplanter Daemon ohne Variablen“. (4) Remote-Mac-Grenzen: Der Account für Screen Sharing oder SSH muss mit dem Gateway-Account übereinstimmen; root mit Login-User zu mischen spaltet Besitz und Keychain-Zugriff.

Operationalisieren Sie diese vier Achsen in einer einseitigen internen Tabelle: OpenClaw-Version neben Archiv-Checksum, Ticket-ID und Stopp-Reihenfolge. Wenn Unterverzeichnisse von ~/.openclaw zwischen Releases umbenannt werden, notieren Sie den Upstream-Pfad zum Zeitpunkt des Snapshots. Bei Umzug vom Laptop in ein Colocation-Rechenzentrum prüfen Sie DHCP, VPN-Split-Tunnel und DNS-Suchdomains erneut — APIs, die gestern noch „stabil“ wirkten, ändern Auflösung und Webhooks fallen ins Leere.

Halten Sie Installationsnachweise bereit: Paketmanager-Version, Node-Laufzeit, aktive Compose-Datei auf dem Quell-Host — sonst ist der Ziel-Host „neuer“ als Ihr State-Snapshot und CLI driftet subtil. Verknüpfen Sie im Ticket direkt Installationsmatrix und Onboarding, damit Reviewer dieselben Leitfäden sehen.

2. Matrix: Was gehört in das kalte Migrationsbündel (2026)

3. Fünf Schritte: Einfrieren → Packen → Prüfen → Kaltstart → Neu koppeln

Schritt 1 — Schreiber einfrieren: Stoppen Sie Gateway und zugehörige launchd-Jobs (oder den Compose-Stack) auf dem alten Rechner, damit keine Hintergrund-Sitzung SQLite-Dateien oder Locks mutiert. Packen bei laufenden Schreibern erzeugt nach Restore zufällige Korruption. Dokumentieren Sie die exakte Stopp-Reihenfolge; manche Teams pausieren auch Cron-Hooks oder CI-Webhooks, die Agent-Läufe auslösen, weil diese Sekunden später wieder State öffnen. Bei mehreren Compose-Projekten stoppen Sie entlang der Abhängigkeiten und speichern docker ps als Beweis eines sauberen Bodens.

Schritt 2 — Snapshots paaren: Erfassen Sie ~/.openclaw und den Workspace im selben Moment, inklusive Lockfiles; bei Docker exportieren Sie Volume oder Image-Digest parallel, damit alle drei Zeitstempel passen. Bei case-sensitiven Volumes oder Symlink-Farmen lösen Sie echte Pfade vor dem Archivieren, sonst entstehen auf dem Ziel zwei Bäume, die sich nur in der Großschreibung unterscheiden. Entscheiden Sie explizit, ob pnpm- oder npm-Caches Teil des Bündels sind oder neu gebaut werden — beides ist legitim, aber gemischter „alter State + frisch installierte Deps“ ohne Dokumentation erzeugt Heisenbugs in Kanal-Smoke-Tests.

Schritt 3 — Prüfen und bereinigen: Prüfen Sie die Checksumme des Archivs vor dem Entpacken; durchsuchen Sie Konfigurationen nach alten Hostnamen, absoluten Pfaden und nur im LAN erreichbaren URLs, die vom neuen oder Remote-Mac aus erreichbar sein müssen. Ersetzen Sie Verweise auf USB-Serien, lokale Modellgewichte oder Samba-Mounts durch neue Äquivalente und führen Sie ein schnelles Grep nach IP-Literalen aus — häuslicher DHCP-Wechsel ist ein häufiger Grund, warum Webhooks still ins Nichts zeigen.

Schritt 4 — Gateway-Kaltstart: Booten Sie mit minimaler Oberfläche (Loopback-Admin-Port zuerst), führen Sie openclaw doctor oder die Projekt-Leiter aus und bestätigen Sie Log-Verzeichnisse, Rechte und Listener gemäß Plist-Vertrag. Lassen Sie den ersten Kanal deaktiviert, bis doctor grün ist; vorzeitige OAuth-Redirects bei halbem Env-Block erzeugen verwirrenden Teilstaat in Vendor-Konsolen. Erfassen Sie CPU- und Speicher-Baseline nach dem Kaltstart zum Vergleich mit dem alten Host und prüfen Sie, ob Debug-Flags vergessen wurden.

Schritt 5 — Kanal neu koppeln: Folgen Sie OAuth oder Webhook-Registrierung je Vendor — die meisten Plattformen verbieten zwei aktive Bots mit denselben Credentials; fahren Sie die alte Instanz vollständig herunter, bevor die neue live geht, um doppelte Zustellungen und Signaturkonflikte zu vermeiden. Rotieren Sie App-Secrets bei Migration wenn möglich: klare Audit-Spur, keine vergessenen Staging-Tokens gegen Produktions-URLs. Nach dem Neu-Pairing führen Sie skriptierte Send/Empfangs-Probes pro Kanal aus statt Ad-hoc-Klicks, damit On-Call dieselben Schritte nach dem nächsten Upgrade wiederholen kann.

Optional: erfassen Sie in derselben Checkliste die externe DNS-TTL und Tunnel-Provider-Wechsel, damit nach einem IP- oder Hostnamenwechsel niemand „zufällig“ noch den alten Endpunkt cached.

4. Parameter: Warum „Prozess läuft“ trotzdem stille Kanäle bedeutet

Der irreführendeste Modus nach Migration: gesunde Prozesse und bestehende Healthchecks, aber eingehende Nachrichten kommen nie an. Bind-Adressen: Wechsel von 127.0.0.1 auf eine LAN-IP ohne Reverse-Proxy/Firewall-Update — das Gateway spricht mit sich, die öffentliche URL zeigt noch auf die alte IP. Webhook-URLs: Konsolen müssen Tunnel-Hostnamen oder statisches Egress referenzieren; vergessene Slack- oder Feishu-Callbacks sind klassische stille Drops. Uhrzeit und TLS: große NTP-Abweichung auf einem colokierten Mac bricht signierte Requests; TLS-Inspection mit ersetzten Zertifikaten scheitert oft leise. tools.profile: Whitelists mit absoluten Binärpfaden vom alten Host brechen auf neuem PATH — gehen Sie das sessions_spawn-Runbook durch und erweitern Sie Allowlists bewusst.

Wenn weiterhin unklar, sammeln Sie vier Artefakte vor dem Vendor-Ticket: redigierte Plist, exakte öffentliche URL, tcpdump/Proxy-Trace zum TLS-Handshake und Log-Slice mit einer vollständigen Inbound-Event-ID. Damit trennen Sie „HTTP kam nie an“ von „kam an, Signatur verworfen“ — Token neu ausstellen oder Netz reparieren. Pflegen Sie ein kurzes Glossar von Dashboard-Feldnamen zu Config-Keys; Onboarding-Dokumente lieben Synonyme, Migration verstärkt die Verwirrung.

Reife zeigt sich in Übungen: vierteljährlich letztes Quartals-Tarball auf einen Scratch-Mac auspacken, doctor laufen lassen, Webhook-Proben spielen. Teams mit gepaarten Snapshots und dokumentierter Stopp-Reihenfolge erholen sich in Stunden; „nur Repo kopiert“ diffiert tagelang unsichtbaren State. Betrachten Sie Kanal-Stille primär als Netzwerk- und Identitätsproblem, nicht als Modellproblem.

5. Entscheidungstabelle: Laptop vs. dedizierter Remote-Mac-Gateway

Die Tabelle fasst typische Kompromisse; in der Praxis entscheidet oft wer On-Call-Verantwortung trägt und ob Ihre Organisation Remote-Zugriff mit Zwei-Faktor- und Session-Recording abdeckt. Ein dedizierter Mac lohnt sich, sobald Webhooks geschäftskritisch werden und Ausfallminuten dokumentiert werden müssen.

6. FAQ: Fünf Fragen zu jeder Migration

F: Nur den Workspace synchronisieren? Für reine CLI-Experimente ok, stark abzuraten, sobald Kanäle oder Sitzungskontinuität zählen — Sie verbrennen mehr Stunden als das Tarball-Format spart. F: Docker zu Bare Metal? Als Stack-Wechsel plus Migration behandeln; eine Ziel-Form dokumentieren oder die Risikofläche verdoppelt sich. F: Klartext-API-Keys in der Plist? Funktioniert, verletzt Hygiene; gesicherte Env-Dateien oder Secret-Backend bevorzugen. F: Brauche ich Screen Sharing auf Remote? Routine per SSH; VNC nur für erstes OAuth oder GUI-only-Tools, mit Ticket. F: Alten Laptop sofort wipen? Parallelbeobachtung mindestens einen Geschäftszyklus.

Zusätzlich: F: Wie teste ich Kanäle ohne Produktionslast? Nutzen Sie dedizierte Staging-Apps oder eingeschränkte Workspaces, spiegeln Sie aber Webhook-Pfade realistisch — ein reiner Unit-Test ersetzt keine TLS- und DNS-Wahrheit. F: Was tun bei gemischten Apple-IDs auf demselben Host? Trennen Sie klar, welcher Benutzer launchd besitzt; wechselnde GUI-Logins verwischen Ownership und erzeugen sporadische EACCES-Fehler in Logs, die wie Netzwerkprobleme aussehen. F: Soll ich Compose-Overrides mitwandern lassen? Ja, versionieren Sie sie neben dem Archiv und referenzieren Sie die Datei im Ticket; sonst reproduziert niemand den exakten Stack, der den Snapshot erzeugt hat.

F: OpenClaw im selben Fenster upgraden? Zuerst gleiche Version migrieren, Kanäle validieren, Upgrade als zweites Ticket mit eigenem Rollback — Migration plus Major-Upgrade macht jeden Vorfall zweidimensional. F: MDM-gesperrte Macs? Mit Gerätemanagement abstimmen, damit Plists, Helfer und Netzwerk-Erweiterungen signiert und erlaubt bleiben. F: Multi-Region? Dokumentieren, welche Rechtsumgebung Tokens und Logs besitzt; State über Regionen kopieren kann Datenresidenz erwarten, auch wenn technisch trivial.

7. Deep Dive: Migration bewegt State und Identität gemeinsam

OpenClaw-Agenten 2026 sind weniger „installiert es sich“ als welche Prozesse State lesen/schreiben und wie externe Identitäten internen Sitzungen zugeordnet werden. Nur Code ohne State zu verschieben gleicht einem Umzug ohne Tresor — Türen gehen auf, Arbeitsabläufe nicht. Repository-openclaw.json codiert Absicht und Tool-Politik; das Profilverzeichnis hält bereits verhandelte Drittanbieter-Credentials — beides muss in derselben logischen Transaktion wandern oder es entsteht doctor-grün, Kanal-stumm-Schizophrenie.

Die Spaltung zwischen launchd und interaktiven Shells bleibt die zweite Falle: Keys in .zshrc, leere Plist-EnvironmentVariables — der daemonisierte Gateway sieht nichts und loggt vage 401er. Das Gegenteil — Dutzende Variablen in der Plist ohne Ownership auf Log-Pfaden — lässt den Prozess starten, blockiert aber Rotation bis die Platte voll läuft. Halten Sie eine Kreuzcheck-Tabelle für jede sensible Variable über Plist, Shell-Profil und CI.

Neu-Koppeln ist keine Bürokratie: Es erzwingt Ein-Endpoint-Annahmen. Dual-active Bots duplizieren Zustellungen und verärgern Vendor-Abuse-Systeme. Seriöse Runbooks listen Altersinstanz-Stilllegung vor Neuinstanz-Promotion mit Grau-Fenster. Enterprise-WeChat, Feishu, Slack und Discord haben unterschiedliche Cooldowns und IP-Allowlists — eine Vorlage passt selten allen Mandanten.

Auf gemieteten Remote-Macs trennen Sie interaktive GUI-Sitzungen von unbeaufsichtigten Diensten: Erstere für OAuth-Popups, Letztere restartbar, auditierbar, im Einklang mit Apple-Silicon-Headless-Best-Practice. MACGPU-Knoten halten Gateway-Last auf vorhersagbarer Topologie, während Laptops wieder kreative Arbeit leisten statt thermisch gedrosselte Server mit Deckel zu spielen — dieselbe Lektion wie npm vs. Docker: Wahrheit zuerst definieren, dann Kanäle und SLAs verkabeln.

Operational Excellence zeigt sich in Failure-Rehearsals: vierteljährlich letztes Archiv auf Scratch-Mac, doctor, Webhook-Proben — nicht weil Katastrophen wöchentlich drohen, sondern weil Runbooks schneller verrotten als Anwendungscode. Bei Vorfällen gewinnen Teams mit gepaarten Snapshots Stunden; „nur Repo kopiert“ diffiert unsichtbaren State tagelang. Behandeln Sie Stille nach Migration zuerst als Netz- und Identitätsproblem: falsch konfiguriertes Egress tarnt sich oft als „KI denkt nach“, öfter als Vendor zugibt.

Ergänzend lohnt ein kurzer Abnahme-Backlog pro Kanal: erwartete Latenz, erlaubte Fehlerraten, Eskalationspfad wenn Webhooks länger als definierte Minuten ausbleiben. Dokumentieren Sie, welche internen Tickets automatisch erzeugt werden, sobald Healthchecks grün sind, aber keine echten Nutzlasten ankommen — das verhindert, dass On-Call nur CPU-Graphen starrt. Für Remote-Mac-Deployments sollten Sie außerdem einen Wartungsfenster-Kalender mit Apple-Software-Updates abstimmen: ein unangekündigter Neustart ohne vorgefasste Plist- und Volume-Reihenfolge kann genauso Kanal-Stille erzeugen wie ein falscher Token. Teams, die diese Artefakte pflegen, merken schnell, dass Migration kein Einmalprojekt ist, sondern ein wiederkehrendes Betriebsritual mit messbarer Qualität.

Alignieren Sie Observability früh: strukturierte Logs vom Mac weg (oder rotieren und Archive versenden), hänge OpenClaw-Version und Git-SHA des Skills-Repos an jede Alert und tagge Vorfälle mit „post-migration“, bis ein kalenderbasierter Burn-in vorbei ist. Diese Gewohnheiten kosten in ruhigen Wochen fast nichts, zahlen aber die erste Nacht nach einem Security-Patch-Reboot. Die Migrationsgeschichte ist also nicht nur Dateien — es geht darum, Vertrauen wiederherzustellen, weil externe Verträge (Tokens, URLs, Zertifikate) auf dem neuen Metal exakt einmal passen müssen.

Dokumentieren Sie zudem Kapazitätskorridore: gleichzeitige Kanäle, Spitzen durch große Anhänge und Unified-Memory-Budget neben anderen Diensten. Ein knapp dimensionierter Remote-Mac zeigt sporadische Timeouts, die wie Vendor-Fehler wirken. Verknüpfen Sie diese Kennzahlen mit den Leitfäden zu systemd/launchd und Docker-Produktion, damit Betrieb und Entwicklung bei der nächsten Hardwaregeneration dieselben Annahmen teilen.

8. Schluss: Schnelle Bewegungen brauchen trotzdem volle Schritte

(1) Grenzen: State-Layout kann sich zwischen Major-Versionen ändern — semver neben jedem Archiv notieren; Compliance kann Keychain-Klonen verbieten, also Re-Auth-Fenster einplanen. (2) Warum Remote-Mac gewinnt: fester User, fester Egress, feste Hardwareklasse reduziert Long-Tail-Inzidenten vom „Laptop als Server“. (3) MACGPU: Gateway-Hosting auf gemietetem Apple-Silicon-Knoten vor Topologie-Fixierung üben — Startseite, Pläne, Hilfe. Behandeln Sie jede Migration als Probe für die nächste: engere Runbooks summieren sich. Kurz: keine Abkürzung beim State-Bündel — das ist der billigste Versicherungsschein gegen nächtliche Rückfälle und unnötige Eskalationen im Support-Backlog der Nacht.