Sie nutzen bereits eine ältere OpenClaw-Version und wollen auf 2026.3.x upgraden, fürchten aber Konfig-Inkompatibilität? 2026.3.x hat die Standard-Konfig-Logik (z. B. tools.profile, ACP dispatch) geändert – alte Tutorials greifen oft nicht mehr. Dieser Guide erklärt warum die Migration nötig ist, Pflichtschritte vor dem Upgrade (Backup und Checks), den 5-Schritte-Migrationsablauf (Install/Upgrade → Onboard-Assistent → API und Rechte → Daemon → Verify) sowie häufige Fallstricke: Rechte-Rollback, Portkonflikte, Umgebungsvariablen – und Tipps für VNC-Remote-Mac, damit Sie ohne Reinfällen durchkommen.
① Warum auf 2026.3.x migrieren? Alte Tutorials und Hauptänderungen
2026.3.x hat Sicherheit und Defaults verschärft: Bei Neuinstallation ist tools.profile standardmäßig messaging (nur Chat-/Sitzungstools). Wenn Sie Dateizugriff oder Terminal-Ausführung brauchen, gibt es nach dem Upgrade „keine Berechtigung“. ACP dispatch ist standardmäßig aktiv und kann Multi-Agent-Routing ändern; die Plugin-HTTP-Registrierung hat sich ebenfalls geändert. Alte Konfig oder Tutorial-Kopien führen daher oft zu Fehlverhalten nach dem Upgrade.
| Änderung | Alt / üblicher Zustand | 2026.3.x Standard / Empfehlung |
|---|---|---|
| tools.profile | Nicht gesetzt oder coding/full | Neuinstallation standardmäßig messaging; bei Lese-/Schreib-/Ausführungsbedarf auf coding oder full setzen |
| acp.dispatch | Oft nicht gesetzt | Standardmäßig enabled; bei reinem /acp ohne Auto-Routing deaktivieren |
| Plugin-HTTP-Registrierung | registerHttpHandler usw. | Registrierungsverhalten geändert; Plugin-Code und Doku prüfen |
② Vor dem Upgrade: Backup, Versionscheck, Abhängigkeitscheck
Diese drei Schritte vor dem Upgrade vermeiden fehlgeschlagene Upgrades oder Konfig-Verlust ohne Rollback-Option.
Konfig und Workspace sichern
~/.openclaw/openclaw.json und ~/.openclaw/workspace/ an einen sicheren Ort kopieren. Beim Umzug auf eine neue Maschine beide kopieren, dann openclaw doctor und openclaw gateway restart ausführen.
Version und Abhängigkeiten
Node-Version bestätigen (20+ empfohlen); openclaw doctor für Migration und Fixes; openclaw config validate für Konfig-Syntax.
Aktuelle tools und ACP prüfen
openclaw config get tools für aktuelles profile; bei ACP-Nutzung acp.dispatch.enabled prüfen.
③ 5-Schritte-Migration: Install/Upgrade → Onboard-Assistent → API und Rechte → Daemon → Verify
Schritt 1: Mit npm install -g openclaw@latest oder offiziellem Install-Skript auf 2026.3.x upgraden.
Schritt 2: openclaw onboard starten, Konfig-Assistent durchlaufen (Nutzung persönlich/Team, Install-Typ z. B. QuickStart, AI-Modell/API wie OpenAI/Claude/Drittanbieter).
Schritt 3: In ~/.openclaw/openclaw.json tools.profile auf coding (normale Datei/Ausführung) oder full setzen oder bestätigen; für ACP ohne Auto-Routing acp.dispatch.enabled: false setzen.
Schritt 4: Bei Daemon/LaunchAgent openclaw onboard --install-daemon ausführen oder laut Doku den Daemon einrichten; in plist/Umgebung PATH und API-Variablen korrekt setzen.
Schritt 5: openclaw gateway restart, dann openclaw health zum Prüfen; auf Remote-Mac per VNC verbinden und einmal durchspielen, damit keine Berechtigungsdialoge offen bleiben.
④ Fallstricke: Rechte-Rollback, Portkonflikte, Umgebungsvariablen, VNC-Remote-Mac
Rechte-Rollback: Nach Upgrade „keine Lese-/Schreib-/Ausführungsberechtigung“ → oft ist tools.profile auf messaging; auf coding oder full stellen und Gateway neu starten.
Portkonflikte: Port belegt → lsof -i :Port für den Prozess, beenden oder Konfig auf anderen Port ändern.
Umgebungsvariablen: Bei Start über launchd oder PM2 PATH und API-Variablen in plist/ecosystem explizit setzen, sonst funktioniert die interaktive Shell, der Hintergrunddienst aber nicht.
VNC-Remote-Mac: Für Upgrade und Erst-Autorisierung immer per VNC verbinden, um System- und Keychain-Dialoge zu bedienen. Nach dem Upgrade kann SSH für Automatisierung genutzt werden. Nur per SSH zu upgraden kann Dialoge unklickbar lassen und den Prozess blockieren.
openclaw doctor für Migration und Fixes. Beim Umzug auf eine neue Maschine ~/.openclaw/ und ~/.openclaw/workspace/ gemeinsam kopieren, um Konfig, Kanalstatus und Credentials zu behalten.⑤ FAQ: Rollback, Multi-Instanz, Links zu unseren Troubleshooting-Artikeln
Wie rollback? Mit Backup von openclaw.json und Workspace: wiederherstellen, alte npm-Version installieren, Dienst neu starten. Ohne Backup muss die Konfig an die neue Logik angepasst werden.
Multi-Instanz-Migration? Jede Instanz hat ihr eigenes Konfig-Verzeichnis; einzeln sichern, einzeln upgraden und prüfen, Port und profile unterscheiden.
Verwandte Artikel auf dieser Seite: Bei Install- oder Laufzeitfehlern siehe OpenClaw häufige Fehler & Troubleshooting; für Autorisierungsdialoge auf Remote-Mac OpenClaw VNC-Freigaben & Sicherheits-Isolierung; zur Umgebungsauswahl OpenClaw v2026.3.7 Umgebungsauswahl.
Warum sich für das OpenClaw-Upgrade auf Remote-Mac VNC empfiehlt
Die 2026.3.x-Migration bringt mehrere „Erstläufe“ und mögliche System- und Keychain-Dialoge mit sich. Nur per SSH können Sie diese Dialoge nicht bestätigen, der Ablauf bleibt hängen. Auf einem VNC-Remote-Mac können Sie onboard abschließen, Dialoge bedienen und openclaw health sowie Logs wie lokal prüfen – der Upgrade-Pfad ist klar, Fehlersuche schneller. Um „nach dem Upgrade startet es nicht“ oder „Rechte passen nicht“ zu vermeiden, Upgrade und Verifikation auf einem VNCMac-Remote-Mac-Node durchführen und bei Bedarf SSH für die tägliche Automatisierung nutzen – oft die stabilste und zeitsparendste Variante.