Gateway unter macOS

OpenClaw.app enthält weder Node/Bun noch die Gateway-Laufzeit. Die macOS-App erwartet eine externe Installation der openclaw-CLI, startet das Gateway nicht als untergeordneten Prozess und verwaltet einen benutzerspezifischen launchd-Dienst, der das Gateway am Laufen hält (oder stellt eine Verbindung zu einem bereits laufenden lokalen Gateway her).

Automatische Einrichtung

Wählen Sie auf einem neuen Mac während des Onboardings This Mac aus. Die App führt vor dem Gateway-Assistenten ihr signiertes, mitgeliefertes Installationsskript aus: Es installiert eine Node-Laufzeit im Benutzerbereich und die passende openclaw-CLI unter ~/.openclaw und installiert und startet anschließend den benutzerspezifischen launchd-Dienst. Für diesen Weg sind weder Terminal noch Homebrew oder Administratorzugriff erforderlich.

Die App enthält nur das Installationsskript, nicht die Node- oder Gateway-Nutzlast; für die Einrichtung ist eine Internetverbindung erforderlich, um die Laufzeit und das passende OpenClaw-Paket herunterzuladen.

Manuelle Wiederherstellung

Node 24 wird für eine manuelle Installation empfohlen; Node 22.19+ funktioniert ebenfalls. Installieren Sie openclaw global:

npm install -g openclaw@<version>

Verwenden Sie nach einer fehlgeschlagenen automatischen Einrichtung Retry setup. Falls dies weiterhin fehlschlägt, installieren Sie die CLI manuell mit dem obigen Befehl und wählen Sie anschließend beim Onboarding Check again aus.

Launchd (Gateway als LaunchAgent)

Bezeichnung: ai.openclaw.gateway (Standardprofil) oder ai.openclaw.<profile> für ein benanntes Profil.

Plist-Speicherort (benutzerspezifisch): ~/Library/LaunchAgents/ai.openclaw.gateway.plist (oder ai.openclaw.<profile>.plist).

Die macOS-App ist im lokalen Modus für die Installation und Aktualisierung des LaunchAgent für das Standardprofil zuständig. Die CLI kann ihn ebenfalls direkt installieren: openclaw gateway install (benannte Profile werden über die Umgebungsvariable OPENCLAW_PROFILE ausgewählt).

Verhalten:

• „OpenClaw Active“ aktiviert/deaktiviert den LaunchAgent.
• Das Beenden der App stoppt das Gateway nicht (launchd hält es am Laufen).
• Wenn auf dem konfigurierten Port bereits ein Gateway läuft, stellt die App eine Verbindung dazu her, anstatt ein neues zu starten.

Protokollierung:

• launchd-Standardausgabe: ~/Library/Logs/openclaw/gateway.log (Profile verwenden gateway-<profile>.log)
• launchd-Standardfehlerausgabe: unterdrückt
• Wenn der Host durch wiederholtes EADDRINUSE oder schnelle Neustarts in einer Schleife hängt, suchen Sie nach doppelten LaunchAgents ai.openclaw.gateway / ai.openclaw.node und prüfen Sie die Problemumgehung mit launchd-Markierung unter Gateway-Fehlerbehebung.

Versionskompatibilität

Die macOS-App gleicht die Gateway-Version mit ihrer eigenen Version ab. Das Onboarding führt die verwaltete Einrichtung automatisch aus, wenn eine vorhandene CLI fehlt oder inkompatibel ist. Verwenden Sie Retry setup, um die Installation zu wiederholen, oder Check again, 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 mit der Cloud synchronisierte Ordner; Synchronisierungslatenzen und Dateisperren können Sitzungen, Anmeldedaten und den Gateway-Zustand beeinträchtigen.

Setzen Sie OPENCLAW_STATE_DIR nur dann auf einen lokalen Pfad, wenn Sie eine Überschreibung benötigen. openclaw doctor warnt vor häufig verwendeten, mit der Cloud synchronisierten Zustandspfaden und empfiehlt die Rückkehr zu lokalem Speicher. Weitere Informationen finden Sie unter Umgebungsvariablen und Doctor.

App-Verbindung debuggen

Verwenden Sie die macOS-Debug-CLI aus einem Quellcode-Checkout, um denselben Gateway-WebSocket-Handshake und dieselbe Erkennungslogik auszuführen, die von der App verwendet werden:

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

connect akzeptiert --url, --token, --timeout, --probe und --json (sowie Überschreibungen der Clientidentität; führen Sie den Befehl mit --help aus, um die vollständige Liste anzuzeigen). discover akzeptiert --timeout, --json und --include-local. Vergleichen Sie die Erkennungsausgabe mit openclaw gateway discover --json, wenn Sie Probleme bei der CLI-Erkennung von appseitigen Verbindungsproblemen unterscheiden müssen.

Funktionstest

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

Anschließend:

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

Verwandte Themen

• macOS-App
• Gateway-Betriebshandbuch