update vs migrate · Plan / Dry-Run · JSON · Gateway 18789
Mit v2026.4.26 rückt openclaw migrate vom bloßen Versionsstempel in die Nähe eines nachvollziehbaren Engineering-Workflows: ein planbarer Schritt zeigt betroffene Pfade und Secret-Flächen, ein dry-run liefert maschinenlesbare Diffs, und integrierte Importpfade erlauben, Prompt-Archive, MCP-Metadaten und Fähigkeiten aus Claude Code bzw. Claude Desktop ohne stilles Doppelbuchführungschaos zusammenzuführen. Auf gemieteten Macs bleibt OPENCLAW_PLUGIN_DIR der Hebel, an dem sich häufig zeigt, ob Abhängigkeiten wirklich auf ein beschreibbares Volume zeigen oder nur scheinbar: ein read-only Layer im Image wirkt wie ein sporadischer Installer-Fehler, obwohl das eigentliche Problem die Wurzelkonfiguration ist. Dieser Leitfaden richtet sich an Teams, die Knoten tauschen, mehrere Konfigurationsquellen vereinheitlichen oder Claude als Kanon etablieren wollen — nicht an einen simplen Patch-Abend.
Statt Banner-Texten liefern wir eine Entscheidungstabelle (wann openclaw update reicht), ein achtstufiges Runbook mit ticketfertigen Überschriften, vier Sätze für Änderungsprotokolle und eine VNC-spezifische Abnahmetabelle, weil Browserzustimmungen und Gateway-Health nicht aus SSH-Scrollback rekonstruierbar sind. Verlinkt werden ausschließlich die in blog-data.js für Deutsch hinterlegten Ziele: offizielles Docker Compose, Daemon und launchd, zehn konkrete Fehlerketten, kaltes Plugin-Registry-Thema 4.25 sowie der historische Kontrast 3.x Konfig-Migration, der noch stark auf manuell abgetippte Kernelemente setzte.
Operativ zahlt sich aus, wer vor dem ersten apply klärt, welche Quelle nach einem Konflikt gewinnt. Slack-Threads reichen nicht; ein Wiki-Eintrag mit „OpenClaw bleibt Kanon für X, Archiv Y wird importiert und danach eingefroren“ senkt die Wahrscheinlichkeit, dass zwei Wochen später jemand per Hand eine JSON-Datei überschreibt. Wenn zusätzlich ein Compose-Stack läuft, muss nach der Migration das Zusammenspiel aus Volume-Mount, Container-Environment und plist-EnvironmentVariables nochmals explizit geprüft werden — sonst entsteht der Klassiker „Container-Doctor grün, Host-UI rot“.
Registry-nahe Symptome gehören in die Denkweise des 4.25-Artikels: repair-Zyklen, Install-Metadaten und gemischte Binärversionen sind nicht automatisch durch einen migrate-Lauf entschärft. Planen Sie deshalb zwei Absicherungstore: eins für den strukturellen Merge (dieses Dokument) und eins für den laufenden Betrieb (4.25). Die hier beschriebene Port 18789 dient als Anker für lokale oder proxied Zugriffe; jede Diskrepanz zwischen Notizblock, Env-Datei und tatsächlichem Listener führt sonst zu TLS- oder Auth-Stürmen, die in Artikel zehn bereits katalogisiert sind.
Update hält eine gesunde Einzellinie aktuell. Migrate organisiert strukturelle Bewegungen: neuer Host, anderer state-Pfad, Massenimport fremder Wahrheit. Wer nur deshalb migriert, weil die Versionsnummer gewachsen ist, erzeugt Lärm. Wer nach einem Hostwechsel nur openclaw update fährt, riskiert Halb-Waisen bei Ports und relativen Pfaden.
Ein Sonderfall sind Teams, die parallel Docker und Bare-Metal testen. Ohne klare Port- und Datenbindung existieren schnell zwei Gateways mit demselben Namen unterschiedlichen Binärgehirnen — migrate-JSON hilft nur dann, wenn die Netztopologie vorher fixiert ist.
Patch-Tag, gleicher Node: zuerst openclaw update + openclaw doctor; kein migrate „zur Sicherheit“.
Neuer Node: migrate plan/dry-run normalisiert Pfade und Ports, bevor das Gateway auf falschen Mappings startet.
Claude-Workspace führt Prompt-Kanon: 4.26-Import statt Copy&Paste, das zwei Wahrheiten hinterlässt.
Plugin-Install mit EROFS-Aroma: zuerst beschreibbare Wurzel und OPENCLAW_PLUGIN_DIR, dann erneutes Update.
Compose und Bare Metal: Docker-Leitfaden lesen, doppelte 18789-Pfade vermeiden.
launchd um den Daemon: nach migrate plist prüfen, siehe launchd-Checkliste.
Die Tabelle ersetzt keine Logs, aber sie verhindert, dass man beim ersten Raten gleich das falsche Werkzeug öffnet. Gemischte Gateways bleiben gekoppelt an den 4.25-Repair- Pfad. Tragen Sie ergänzend ein, welche Monitoring-Metriken Sie in der Nacht nach dem Merge beobachten — ohne Baseline sind kleine Regressions schwer zu verteidigen.
| Beobachtung | Default | Nächster Hop | Vermeiden |
|---|---|---|---|
| nur Paket alt | update + doctor | Cache/Rechte | komplettes migrate |
| frischer Host | plan + JSON | Secrets diff | JSON manuell als Wahrheit |
| MCP in Claude | 4.26 Merge + dry-run | redacted Tickets | doppelte Bücher |
| read-only Install | beschreibbare Wurzel + repair | Gateway neu | globales chmod |
| gemischtes Gateway | Binär + Registry | 4.25 Flow | nur reboot theater |
Wenn in derselben Nacht auch noch Skalierungsarbeiten für Container anstehen, dokumentieren Sie strikt, welche Session zuerst wieder erreichbar sein muss: Gateway, Doktor oder Plugin-UI. Sonst mischt sich Rollback-Physik mit Container-Neustarts.
Jede Überschrift kann CR-Titel sein. Öffnen Sie parallel eine VNC-Sitzung mit dem Gateway-Benutzer. Halten Sie die Ausgaben von doctor nach dem dry-run bereit, falls Auditoren Rückfragen stellen oder Compliance kurzfristig zusätzliche Exporte und Checksummen verlangt.
Backup ohne Snapshots führt auf Cloud-Mieten oft zu Wiederherstellungs-Tagebau: erwähnen Sie Snapshot-IDs im Change Record. Für getrennte System- und Daten-Volumes notieren Sie, welches Volume schreibgeschützt bleiben soll — das erklärt später half-written Dependencies.
Wenn Ihre Organisation formale Abnahmeprotokolle verlangt, sollten Screenshots oder Kurzfilme aus eben dieser GUI-Sitzung stammen; ein Benutzerwechsel invalidiert TCC-Kontext und macht die „Beweiskette“ wertlos. Für wiederkehrende Staging-Deployments kombinieren Sie diesen Ablauf mit den Hinweisen im Compose-Leitfaden, damit Container-IDs nicht versehentlich als permanenter Pfad im JSON landen.
Ein praktischer Trick für gemischte Teams: exportieren Sie doctor-Ausgaben vor und nach dem apply in dieselbe Artefakt-Ablage wie das migrate-JSON. So bleibt der Zeitreihenvergleich für Sicherheitsteams nachvollziehbar ohne Zugriff auf Produktions-SSH. Achten Sie bei mehreren lokalisierungsfähigen Umgebungen darauf, dass OPENCLAW_PLUGIN_DIR nicht still auf ein Home-Verzeichnis zeigt, das im nächsten Release umbenannt wird.
Fingerprint: Version, doctor, Kanal, Container?
Backup: claw backup plus Volume-Snapshot.
Plan: migrate plan aus Release Notes aufrufen.
Dry-run JSON: additive vs. kanonische Schlüssel trennen.
Claude Merge Review: geheime Felder maskieren.
OPENCLAW_PLUGIN_DIR + repair/doctor.
Gateway 18789: Health, WS, Fehlerliste.
CR einfrieren: Diff, Rollback, Launchd/Docker Ansprechpartner.
openclaw --version && openclaw doctor claw backup openclaw migrate <plan|dry-run lt. Release Notes> openclaw plugins repair openclaw status
Diese Sätze sind bewusst normativ formuliert, damit sie ohne Umformulierung in Tickets wandern können und später nicht als „meinte ich nur rhetorisch“ entschärft werden müssen.
Hier beginnt der Teil, den reine SSH-Sitzungen nicht abdecken: echte Klicks in Systemdialogen, sichtbare WebSocket-Stabilität, abgleichbare Plugin-UI. Auf geteilten Hosts kann ein aggressiver Energiesparmodus laufende Sessions hinter dem VNC-Fenster drosseln — stimmen Sie das mit Ihrer launchd-Erwartung ab.
Ergänzend sollten Sie notieren, welche Browser-Erweiterungen aktiv sind: blockierte Automations-APIs sehen aus der Ferne wie Gateway-Fehler, obwohl nur Mixed-Content oder ein Cookie-Banner stört. Ohne Screenshot aus derselben Session verschwendet das Ops-Team Stunden mit falschen Spuren.
| Item | In VNC | Pass |
|---|---|---|
| Loopback/Proxy | Devtools | keine 401-Kaskade, stabiles WS |
| Betroffene Rechte | Dialoge schließen | gleicher Nutzer |
| Schlafmodus | Policy prüfen | konsistent zu launchd |
| Plugin-UI | GUI vs CLI | Namen/Versionen passen |
Volumes, Loopback, Validierung.
Lesen →Environment nach Baumänderung.
Lesen →Repair und gemischtes Gateway.
Lesen →Ein Host, ein Kanon → update. Maschinenwechsel → plan/dry-run.
Echte Schreibwurzel, dann repair; parallel 4.25 lesen.
Für CLI/JSON ja; Zustimmungen siehe Abschnitt 05.
Betrieb & repair; großer Merge bleibt hier.
Migrate beweist Merges; es ersetzt aber keine disziplinierte Infrastruktur. Wer Bare-Metal kauft, kauft Stromverträge und nächtliche Patch-Verantwortung mit. Wer lieber SSH plus reviewbares GUI auf gemieteten Apple-Silicon-Knoten fokussiert, schiebt Betriebslärm zur Plattform und behält diffbare Integrationsarbeit beim Team.
Vergleichen Sie Ihre nächtliche Routine abschließend mit dem Äquivalent aus der 3.x-Migration: dort waren Handschrift und mühsames Abgleichen im Vordergrund, hier steht maschinenlesbarer Plan im Zentrum. Ohne diese geistige Verschiebung bleibt migrate nur ein neues Verb in alten Gewohnheiten.
VNCMac: primär zur Kaufseite; Übersicht auf der Startseite. Archivieren Sie Docker-, launchd- und Fehlerartikel gemeinsam mit diesem Leitfaden in einem Run-Ordner, den Sie später für Audits vorlegen können.