Gateway-Lebenszyklus unter macOS

Die macOS-App verwaltet den Gateway standardmäßig über launchd und startet den Gateway nicht als untergeordneten Prozess. Sie versucht zunächst, eine Verbindung zu einem bereits laufenden Gateway am konfigurierten Port herzustellen. Ist keiner erreichbar, aktiviert sie den launchd-Dienst über die externe openclaw-CLI (keine eingebettete Runtime). Dies gewährleistet einen zuverlässigen automatischen Start bei der Anmeldung und einen Neustart nach Abstürzen.

Der Modus mit untergeordnetem Prozess (Gateway wird direkt von der App gestartet) wird derzeit nicht verwendet. Wenn Sie eine engere Kopplung an die UI benötigen, führen Sie den Gateway manuell in einem Terminal aus.

Standardverhalten (launchd)

• Die App installiert einen benutzerspezifischen LaunchAgent mit der Bezeichnung ai.openclaw.gateway (oder ai.openclaw.<profile> bei Verwendung von --profile/OPENCLAW_PROFILE).
• Wenn der lokale Modus aktiviert ist, stellt die App sicher, dass der LaunchAgent geladen ist, und startet den Gateway bei Bedarf.
• Protokolle werden in den launchd-Gateway-Protokollpfad geschrieben (sichtbar in den Debug-Einstellungen).

Häufig verwendete Befehle:

launchctl kickstart -k gui/$UID/ai.openclaw.gatewaylaunchctl bootout gui/$UID/ai.openclaw.gateway

Ersetzen Sie beim Ausführen eines benannten Profils die Bezeichnung durch ai.openclaw.<profile>.

Unsignierte Entwicklungs-Builds

scripts/restart-mac.sh --no-sign ist für schnelle lokale Builds ohne Signierungsschlüssel vorgesehen. Um zu verhindern, dass launchd auf eine unsignierte Relay-Binärdatei verweist, schreibt es ~/.openclaw/disable-launchagent.

Signierte Ausführungen von scripts/restart-mac.sh entfernen diese Überschreibung, wenn die Markierung vorhanden ist. So setzen Sie sie manuell zurück:

rm ~/.openclaw/disable-launchagent

Nur-Verbindungsmodus

Um zu erzwingen, dass die macOS-App launchd niemals installiert oder verwaltet, starten Sie sie mit --attach-only (oder --no-launchd). Dadurch wird ~/.openclaw/disable-launchagent gesetzt, sodass die App nur eine Verbindung zu einem bereits laufenden Gateway herstellt. Das gleiche Verhalten können Sie in den Debug-Einstellungen umschalten.

Remote-Modus

Der Remote-Modus startet niemals einen lokalen Gateway. Die App verwendet einen SSH-Tunnel zum Remote-Host und stellt die Verbindung über diesen Tunnel her.

Warum wir launchd bevorzugen

• Automatischer Start bei der Anmeldung.
• Integrierte Neustart-/KeepAlive-Semantik.
• Vorhersagbare Protokolle und Überwachung.

Falls jemals wieder ein echter Modus mit untergeordnetem Prozess benötigt wird, sollte er als separater, expliziter und ausschließlich für die Entwicklung vorgesehener Modus dokumentiert werden.

Verwandte Themen

• macOS-App
• Gateway-Betriebshandbuch