Der Setup Wizard wartet auf einen erreichbaren Gateway-Prozess unter den Bedingungen, die launchd tatsächlich sieht – nicht auf das Gefühl „install.sh war grün“. Auf Cloud-Macs unterscheidet sich diese Wahrheit fast immer von Ihrer interaktiven SSH-Shell. Die häufigste Wurzel ist CLI fehlt im launchd-PATH: which openclaw in der Session zeigt /opt/homebrew/bin/openclaw, ProgramArguments der plist zeigen aber ein anderes Präfix oder gar keinen absoluten Pfad. Der Wizard pollt Health; launchd startet nichts Stabiles – Retry ohne neuen Fehlertext.

Die zweite Wurzel ist LaunchAgent bereits failed, Wizard meldet trotzdem Timeout: launchctl list zeigt Exit-Code ≠ 0, während die GUI nur „not ready“ wiederholt. Stoppen Sie doppelte Registrierungen, bevor Sie Retry spamen – sonst verlängern Sie Sperren auf Port und Schlüsselbund. Die dritte Wurzel ist 18789 (oder Ihr gebundener Port) belegt oder an localhost gebunden, während der Wizard von außen prüft; ein zweites gateway start aus einer SSH-Sitzung plus plist-Daemon ist der Klassiker, dokumentiert in der Dual-Track-Anleitung. Die vierte Wurzel sind fehlende EnvironmentVariables in der plist (Token, OPENCLAW_*, WorkingDirectory), symmetrisch zur Token-Missing-Fork.

Frieren Sie im Änderungsdatensatz vier Zeilen ein: absoluter openclaw-Pfad, LaunchAgent-Label, Listen-Port, Exit-Code von openclaw doctor. Jeder Retry ohne diese Zeilen ist nicht reproduzierbar – besonders wenn mehrere Ingenieure per Screen Sharing und SSH gleichzeitig klicken. Wenn Sie personenbezogene Inhalte in Gateway- oder Wizard-Logs dauerhaft speichern, definieren Sie Zweck, Aufbewahrungsdauer und Zugriff im Sinne der DSGVO; alarmieren Sie Zustandswechsel statt jedes Heartbeats, um Datenminimierung und Speicherkosten zu halten.

In Support-Tickets aus 2026.3.x taucht oft die Formulierung auf, install.sh sei „fertig“, während openclaw gateway status bereits einen anderen Exit-Code zeigt als die GUI. Trennen Sie deshalb im Ticket explizit Install-Erfolg von Readiness-Erfolg. Der Wizard pollt typischerweise einen Health-Endpunkt mit kurzem Timeout; ein Gateway, das erst nach 30–60 Sekunden stabil wird, wirkt als Retry-Schleife, obwohl launchd noch startet. Messen Sie mit einem einmaligen Health-Aufruf und einem 60-Sekunden-Fenster, bevor Sie Hardware oder Region wechseln.

Wenn Ihr Team die macOS-App und den globalen CLI parallel nutzt, dokumentieren Sie, wer Port 18789 besitzt: attach an einen bestehenden Listener oder ein frischer Daemon – nie beides. Versionssprünge zwischen App-Bundle und npm i -g openclaw erzeugen grüne Install-Logs und rote Wizard-Meldungen. Gleichen Sie Versionen über den CLI-Ausrichtungs-Artikel ab, bevor Sie erneut Retry drücken. Auf dedizierten Hosts mit mehreren SSH-Admins gilt: jede Sitzung ist verdächtig, bis PATH in login und non-login Shell identisch bewiesen ist.

Nicht jedes Team braucht den grafischen Setup Wizard. Wenn Sie ausschließlich über SSH arbeiten und das Dashboard remote tunneln, ist der Headless-Pfad mit openclaw onboard --install-daemon und openclaw doctor oft schneller und auditierbarer – beschrieben in der Headless-SSH-Anleitung. Den App-Wizard behalten Sie, wenn macOS-Berechtigungen, Schlüsselbund-Prompts oder ein nicht-technischer Kollege Screen Sharing nutzt und Sie GUI-Feedback für die Abnahme brauchen.

Vor dem Wizard-Lauf müssen interaktive und non-interaktive Shells denselben Node- und globalen bin-Pfad sehen wie die plist. Auf KVMNODE-Hosts ohne GUI-Login ist der häufige Fehler, Homebrew nur in .zprofile zu setzen, während launchd /usr/bin:/bin erbt. Legen Sie absolute Pfade in ProgramArguments fest und validieren Sie mit openclaw gateway call health, nicht mit Bauchgefühl. Teams, die später Channels verkabeln, planen danach Channels-Probes ein – aber nur nach stabiler Gateway-Readiness.

Der Headless-Pfad eignet sich besonders für Runbooks in CI-artigen Abläufen: jeder Schritt hinterlässt Text in stdout, den Sie an Tickets anhängen. Der App-Wizard eignet sich für erste Pairing-Schritte mit Schlüsselbund-Prompts, die in reinem SSH hängen bleiben. Mischen Sie die Vorlagen nicht: ein Ticket „Greenfield Wizard“ und ein Ticket „Headless doctor“ haben unterschiedliche Abnahmekriterien. Wenn Stakeholder Screenshots verlangen, exportieren Sie zusätzlich die doctor-Ausgabe – Screenshots allein zeigen selten den launchd Exit-Code.

Nach onboard --install-daemon prüfen Sie mit launchctl print gui/$(id -u)/… oder dem dokumentierten Label, ob WorkingDirectory auf ~/.openclaw zeigt und nicht auf ein altes Laptop-Verzeichnis. Ein falscher WorkingDirectory erklärt Token-Wahrheit in der Shell versus token_missing im Daemon – auch ohne erneuten Wizard-Retry. Wenn Sie von Laptop auf Cloud umziehen, lesen Sie zuerst die Migrations-Backup-Story, bevor Sie den Wizard als „Neuinstallation“ behandeln.

Die Reihenfolge ist bewusst linear: jeder Schritt liefert ein Artefakt fürs Ticket. Überspringen Sie keinen Schritt zugunsten von Retry – der Wizard ersetzt keine Triage.

which openclaw
openclaw --version
openclaw gateway status
openclaw doctor
launchctl list | grep -i openclaw
lsof -nP -iTCP:18789 -sTCP:LISTEN
openclaw gateway call health --url ws://127.0.0.1:18789 --timeout 5000

Erst wenn Schritt 06 grün ist, den Setup Wizard erneut öffnen oder Schritt 07 ausführen. War Schritt 04 rot, führen Sie openclaw onboard --install-daemon nicht blind erneut aus – bereinigen Sie zuerst das alte Label. Die Diagnoseleiter ordnet Felder L1/L2 zu, falls mehrere Symptome gleichzeitig auftauchen.

Schritt 04 verdient Tiefe: log show --predicate um das Label herum plus die neuesten Dateien unter /tmp/openclaw. Suchen Sie nach „address already in use“, „ENOENT“ auf openclaw oder Node-Modul-Fehlern nach Upgrade. Wenn der Health-Aufruf in Schritt 06 fehlschlägt, obwohl lsof einen Listener zeigt, prüfen Sie Bind auf 127.0.0.1 versus 0.0.0.0 und ob der Wizard dieselbe URL verwendet. Ein klassischer Cloud-Fehler ist ein manuell gestartetes Gateway auf 18789 und ein LaunchAgent, der auf 18999 konfiguriert ist – beide „laufen“, Readiness bleibt rot.

Schritt 07 sollte eine echte Geschäftsnachricht oder einen Channel-Probe sein, nicht nur ein grünes Dashboard. Hängen Sie ein einzeiliges JSON von gateway status an und notieren Sie die Uhrzeit der ersten erfolgreichen Antwort. In der Akzeptanzwoche wiederholen Sie Schritte 03 und 06 täglich; Regressionen nach brew upgrade node zeigen sich so, bevor Nutzer erneut Retry sehen. Für Upgrade-Pfade mit Remote-Auth siehe Upgrade Remote Auth – aber nur nach lokaler Readiness.

Auf einem dedizierten KVMNODE-Cloud-Mac ist SSH fast immer die Wahrheit für Änderungen, launchd die Wahrheit für Laufzeit. Screen Sharing zeigt den Wizard, fixiert aber nicht automatisch plist-Pfade. Dokumentieren Sie, ob Abnahme über VNC oder nur CLI erfolgt – Postmortems verwechseln das regelmäßig. Zeitzonen der sechs Regionen (SG, JP, KR, HK, US East, US West) beeinflussen Cron und Log-Rotation, nicht die Gateway-Syntax; rotieren Sie /tmp/openclaw und persistente Logs getrennt, damit die Akzeptanzwoche nicht an voller Root-Partition scheitert.

Ohne TTY scheitern manche Wizard-Schritte still; wechseln Sie dann auf CLI-Abnahme. Mehrfach-SSH ohne vier-Zeilen-Freeze erzeugt „es ging gestern“ – jede Sitzung gilt als divergent, bis PATH bewiesen ist. Halten Sie Zustand außerhalb von Team-Sync-Ordnern, wie in der Persistenz-Baseline. Wenn Health personenbezogene Metadaten schreibt, beschränken Sie Retention und dokumentieren Sie Verarbeitung nach DSGVO – besonders wenn Logs EU-Teams betreffen, der Knoten aber in einer anderen Region steht.

Nach erfolgreicher Erstinstallation hängen Sie ein einzeiliges Monitoring an: Zustandswechsel Gateway, nicht jedes Poll des Wizards. So erkennen Sie Regressionen nach Node-Upgrades, bevor Benutzer erneut Retry sehen.

Screen Sharing über Jump oder VNC zeigt den Wizard, ändert aber nicht die plist auf dem Host. Vereinbaren Sie: wer SSH-Fixes macht, wer GUI klickt – sonst überschreibt ein Retry-Klick während eines plist-Edits den Zustand. Bei geteilten Admin-Konten rotieren Sie Passwörter und dokumentieren, welches Konto onboard ausgeführt hat; Schlüsselbund-Einträge sind benutzergebunden.

Cron-Jobs für Health sollten in der Cloud-Zeitzone des Knotens laufen, nicht in der Zeitzone des Laptops des Operators. Wenn Logs nach UTC rotieren, aber Cron nach lokaler Region des Engineers, fehlen Dateien scheinbar „gestern“. Standardisieren Sie auf die Region des KVMNODE-SKUs im Ticket. Trennen Sie außerdem Akzeptanz-Logs von Dauerbetrieb-Logs, damit ein dreitägiger Test nicht die Produktionsrotation füllt.

Für einen ersten Wizard-Durchlauf ohne paralleles xcodebuild reicht oft ein naher M4 mit 16 GB – vorausgesetzt, Git-Remote und Artefakte sind kontinentnah und der workspace bleibt unter Ihrer Schwellwertgröße. Wählen Sie M4 Pro mit höherem einheitlichem Speicher, wenn in derselben Akzeptanzwoche iOS-CI, große Skill-Repos und das Gateway gemeinsam Speicherdruck erzeugen oder Port 18789 wiederholt durch Runner-Prozesse kollidiert.

Ein Laptop mit Sleep ist ein schlechter Referenzhost für „Wizard ging lokal“ – dedizierte Cloud-Macs liefern stabile launchd-Fenster und vertragliche Laufzeit. Für Teams, die Gateway-Readiness auditierbar brauchen, ist KVMNODE Mac mini Miete die übliche Antwort: sechs Regionen, Apple Silicon, dieselbe PATH- und plist-Sprache wie in diesem Runbook. SKUs auf der Preisseite, Runbooks im Hilfezentrum, Bestellung über Bestellseite.