Gateway-Lebenszyklus auf macOS

Die macOS-App verwaltet den Gateway standardmäßig über launchd und startet den Gateway nicht als Child-Process. Sie versucht zuerst, sich mit einem bereits laufenden Gateway auf dem konfigurierten Port zu verbinden. Falls keiner erreichbar ist, aktiviert sie den launchd-Service über die externe openclaw CLI (ohne eingebettete Runtime). So bekommst du zuverlässigen Auto-Start beim Login und automatische Neustarts bei Abstürzen.

Der Child-Process-Modus (Gateway wird direkt von der App gestartet) ist aktuell nicht im Einsatz. Falls du eine engere Kopplung mit der UI brauchst, starte den Gateway manuell in einem Terminal.

Standardverhalten (launchd)

  • Die App installiert einen benutzerspezifischen LaunchAgent mit dem Label bot.molt.gateway (oder bot.molt.<profile> bei Verwendung von --profile/OPENCLAW_PROFILE; das alte Format com.openclaw.* wird weiterhin unterstützt).
  • Wenn der Local-Modus aktiviert ist, stellt die App sicher, dass der LaunchAgent geladen ist und startet den Gateway bei Bedarf.
  • Logs werden in den launchd Gateway-Log-Pfad geschrieben (sichtbar in den Debug-Einstellungen).

Häufig verwendete Befehle:

launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway

Ersetze das Label durch bot.molt.<profile>, wenn du ein benanntes Profil verwendest.

Unsignierte Dev-Builds

scripts/restart-mac.sh --no-sign ist für schnelle lokale Builds gedacht, wenn du keine Signing-Keys hast. Um zu verhindern, dass launchd auf eine unsignierte Relay-Binary zeigt:

  • Schreibt die Datei ~/.openclaw/disable-launchagent.

Signierte Ausführungen von scripts/restart-mac.sh entfernen diese Überschreibung, falls die Markierung vorhanden ist. Zum manuellen Zurücksetzen:

rm ~/.openclaw/disable-launchagent

Attach-only-Modus

Um die macOS-App zu zwingen, niemals launchd zu installieren oder zu verwalten, starte sie mit --attach-only (oder --no-launchd). Das setzt ~/.openclaw/disable-launchagent, sodass die App sich nur mit einem bereits laufenden Gateway verbindet. Du kannst dasselbe Verhalten auch in den Debug-Einstellungen umschalten.

Remote-Modus

Der Remote-Modus startet niemals einen lokalen Gateway. Die App nutzt einen SSH-Tunnel zum Remote-Host und verbindet sich über diesen Tunnel.

Warum wir launchd bevorzugen

  • Auto-Start beim Login.
  • Eingebaute Restart/KeepAlive-Semantik.
  • Vorhersehbare Logs und Überwachung.

Falls jemals wieder ein echter Child-Process-Modus benötigt wird, sollte er als separater, expliziter Dev-Only-Modus dokumentiert werden.