Gateway unter macOS

OpenClaw.app bündelt Node/Bun oder die Gateway-Laufzeit nicht mehr. Die macOS-App erwartet eine externe openclaw-CLI-Installation, startet das Gateway nicht als Kindprozess und verwaltet einen launchd-Dienst pro Benutzer, um das Gateway auszuführen (oder verbindet sich mit einem bestehenden lokalen Gateway, falls bereits eines läuft).

Automatische Einrichtung

Wählen Sie auf einem neuen Mac während des Onboardings Dieser Mac aus. Die App führt ihr signiertes, gebündeltes Installationsprogramm vor dem Gateway-Assistenten aus, installiert eine Node-Laufzeit im Benutzerbereich und die passende openclaw-CLI unter ~/.openclaw und installiert und startet anschließend den launchd-Dienst pro Benutzer. Dieser Weg erfordert kein Terminal, kein Homebrew und keinen Administratorzugriff.

Die App bündelt das Installationsskript, nicht die Node- oder Gateway-Nutzlast. Die Einrichtung benötigt daher eine Internetverbindung, um die Laufzeit und das passende OpenClaw-Paket herunterzuladen.

Manuelle Wiederherstellung

Node 24 wird für eine manuelle Installation empfohlen. Node 22 LTS, derzeit 22.19+, funktioniert ebenfalls. Installieren Sie dann openclaw global:

npm install -g openclaw@<version>

Verwenden Sie nach einer fehlgeschlagenen automatischen Einrichtung Einrichtung erneut versuchen. Falls dies weiterhin fehlschlägt, installieren Sie die CLI manuell mit dem obigen Befehl und wählen Sie dann im Onboarding Erneut prüfen. Node bleibt die empfohlene Gateway-Laufzeit.

Launchd (Gateway als LaunchAgent)

Label:

• ai.openclaw.gateway (oder ai.openclaw.<profile>; veraltetes com.openclaw.* kann bestehen bleiben)

Plist-Speicherort (pro Benutzer):

• ~/Library/LaunchAgents/ai.openclaw.gateway.plist (oder ~/Library/LaunchAgents/ai.openclaw.<profile>.plist)

Manager:

• Die macOS-App ist im lokalen Modus für Installation/Aktualisierung des LaunchAgent verantwortlich.
• Die CLI kann ihn ebenfalls installieren: openclaw gateway install.

Verhalten:

• "OpenClaw Aktiv" aktiviert/deaktiviert den LaunchAgent.
• Das Beenden der App stoppt das Gateway nicht (launchd hält es am Leben).
• Wenn bereits ein Gateway auf dem konfigurierten Port läuft, verbindet sich die App damit, statt ein neues zu starten.

Protokollierung:

• launchd stdout: ~/Library/Logs/openclaw/gateway.log (Profile verwenden gateway-<profile>.log)
• launchd stderr: unterdrückt

Versionskompatibilität

Die macOS-App prüft die Gateway-Version gegen ihre eigene Version. Das Onboarding führt die verwaltete Einrichtung automatisch aus, wenn eine vorhandene CLI fehlt oder inkompatibel ist. Verwenden Sie Einrichtung erneut versuchen, um die Installation zu wiederholen, oder Erneut prüfen nachdem Sie eine externe CLI repariert haben.

Zustandsverzeichnis unter macOS

Speichern Sie den OpenClaw-Zustand auf einem lokalen, nicht synchronisierten Datenträger. Vermeiden Sie iCloud Drive und andere cloud-synchronisierte Ordner, da Synchronisierungslatenz und Dateisperren Sitzungen, Anmeldeinformationen und Gateway-Zustand beeinflussen können.

Setzen Sie OPENCLAW_STATE_DIR nur dann auf einen lokalen Pfad, wenn Sie eine Überschreibung benötigen. openclaw doctor warnt vor gängigen cloud-synchronisierten Zustandspfaden und empfiehlt, zurück auf lokalen Speicher zu wechseln. Siehe Umgebungsvariablen und Doctor.

App-Konnektivität debuggen

Verwenden Sie die macOS-Debug-CLI aus einem Source-Checkout, um denselben Gateway- WebSocket-Handshake und dieselbe Discovery-Logik auszuführen, die die App verwendet:

cd apps/macosswift run openclaw-mac connect --jsonswift run openclaw-mac discover --timeout 3000 --json

connect akzeptiert --url, --token, --timeout und --json. discover akzeptiert --timeout, --json und --include-local. Vergleichen Sie die Discovery-Ausgabe mit openclaw gateway discover --json, wenn Sie CLI-Discovery von appseitigen Verbindungsproblemen trennen müssen.

Smoke-Check

openclaw --version OPENCLAW_SKIP_CHANNELS=1 \OPENCLAW_SKIP_CANVAS_HOST=1 \openclaw gateway --port 18999 --bind loopback

Dann:

openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

Verwandt

• macOS-App
• Gateway-Runbook