Schluss mit manueller Konfiguration: OpenClaw-Hochverfügbarkeits-Gateway mit launchd automatisieren

Freitagabend, Webhooks schlagen rot an. Sie SSH-en auf den Remote-Mac und stellen fest: Der Gateway-Prozess ist längst weg — zuletzt hatten Sie ihn manuell mit openclaw gateway run gestartet, und nach dem automatischen Neustart um 3 Uhr morgens hat niemand den Befehl erneut ausgeführt. Der Discord-Bot zeigt online, aber Port 18789 ist leer, und GitHub-Callbacks haben sich zu 47 HTTP-502s gestapelt.

Das ist kein OpenClaw-Bug. Es ist ein Betriebsmodell, das noch in Dev-Machine-Denken steckt: interaktive Starts, per Hand editierte Plists, auf jedem Host eine andere Konfiguration. 2026 behandeln Sie das Gateway als Infrastruktur — und auf macOS ist das richtige Werkzeug launchd: Autostart nach Neustart, Crash-Recovery, Logs auf der Platte, Konfiguration in Git.

Dieser Artikel liefert einen Automatisierungspfad von null bis Abnahme: onboard-Registrierung, produktionsreife Plist-Vorlage, Ein-Klick-Bootstrap-Skript, Health-Probes und eine feste Upgrade-Rollback-Reihenfolge. Zur Fehlersuche siehe den Begleitartikel OpenClaw-Gateway launchd Stabilitäts- und Fehlerbehebungs-Handbuch; für Multi-Machine-CI-Orchestrierung OpenClaw Schritt-für-Schritt-Deployment und GitHub Actions-Automatisierung.

Quick Answer: die drei häufigsten Fragen

1. Warum manuelle Konfiguration aufhören muss

Auf einem Remote-Dauer-Mac scheitert manuelle Konfiguration vorhersehbar:

2. Was Gateway-«Hochverfügbarkeit» auf einem Mac bedeutet

Ein einzelner Mac kann kein Kubernetes-artiges Multi-Replica-HA leisten, aber betriebliches HA ist erreichbar:

• Survive reboot: Gateway innerhalb von 2 Minuten nach dem Boot lauschend, ohne manuelles SSH.
• Survive crash: KeepAlive + ThrottleInterval — abnormaler Exit löst Backoff-Neustart aus, ohne die CPU zu pegeln.
• Survive config drift: Plist, Umgebungsvariablen und ~/.openclaw gesichert und in Git nachverfolgt.
• Survive silent failure: Äußerer Healthcheck erkennt «Port lauscht, aber Probe schlägt fehl».
• Survive upgrade: Feste Reihenfolge: backup → doctor --fix → gateway restart, jedes Mal skriptierbar.

In der Praxis: Ein M4 Mac mini (24 GB) mit OpenClaw-Gateway plus leichten Plugins verbraucht im Leerlauf etwa 4–6 W; der Gateway-Prozess liegt typischerweise bei 200–450 MB RAM. Die Maschine auf dem Pfad der nativen Remote-Mac-Bereitstellung zu betreiben ist planbarer, als einen iMac im Büro dauerhaft eingeschaltet zu lassen.

3. LaunchAgent oder LaunchDaemon

Standard 2026: Starten Sie mit einem LaunchAgent — führen Sie onboard und doctor darüber aus. Wechseln Sie erst zum Daemon, wenn Sie bestätigt haben, dass keine Anmeldesitzung nötig ist, und dokumentieren Sie das im Runbook. In beiden Fällen müssen ProgramArguments absolute Pfade verwenden — launchd liest Ihre .zshrc nicht.

4. onboard: launchd per Ein-Klick registrieren

OpenClaw-onboard schreibt Node-Pfad, State-Verzeichnis und Gateway-Port in die Konfiguration; neuere Versionen unterstützen die direkte Installation als launchd-Dienst. Empfohlene Reihenfolge:

# 1. 确认运行时（与 plist 内 PATH 一致）
node -v          # 期望 v22.x
which openclaw   # 记下绝对路径，如 /opt/homebrew/bin/openclaw

# 2. 预检
openclaw doctor

# 3. 交互式 onboard（按提示启用 Gateway + launchd）
openclaw onboard

# 4. 验收
launchctl print "gui/$(id -u)/com.openclaw.gateway" 2>/dev/null || launchctl list | grep -i openclaw
lsof -nP -iTCP:18789 -sTCP:LISTEN
openclaw gateway probe

5. Produktions-Plist-Vorlage (Git-tauglich)

Wenn onboard keine Plist erzeugt hat oder Sie sie in einem Infra-Repo explizit versionieren müssen, nutzen Sie die Vorlage unten. Ersetzen Sie OPENCLAW_BIN durch die Ausgabe von which openclaw:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.openclaw.gateway</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/openclaw</string>
    <string>gateway</string>
    <string>run</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/your-ci-user</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    <key>HOME</key>
    <string>/Users/your-ci-user</string>
  </dict>
  <key>StandardOutPath</key>
  <string>/Users/your-ci-user/Library/Logs/OpenClawGateway/gateway.stdout.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/your-ci-user/Library/Logs/OpenClawGateway/gateway.stderr.log</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <dict>
    <key>SuccessfulExit</key>
    <false/>
  </dict>
  <key>ThrottleInterval</key>
  <integer>30</integer>
</dict>
</plist>

Laden (Ventura+):

UID_NUM=$(id -u)
DOMAIN="gui/${UID_NUM}"
LABEL="com.openclaw.gateway"
PLIST="${HOME}/Library/LaunchAgents/${LABEL}.plist"

launchctl bootout "${DOMAIN}/${LABEL}" 2>/dev/null || true
launchctl bootstrap "${DOMAIN}" "${PLIST}"
launchctl kickstart -k "${DOMAIN}/${LABEL}"

Häufige Fallstricke:

• Auf Intel-Macs liegt Homebrew oft unter /usr/local/bin; auf Apple Silicon unter /opt/homebrew/bin — im Plist fest codieren, keinen «universellen PATH».
• Log-Verzeichnis zuerst mit mkdir -p anlegen — sonst startet launchd möglicherweise nicht und stderr hat kein Ziel.
• Dasselbe Label nie gleichzeitig in Benutzer- und Systemdomäne halten; vor dem Upgrade den alten Job mit bootout entfernen.

6. Ein-Klick-Bootstrap-Skript

«CLI installieren → doctor → Plist schreiben → bootstrap → probe» in einen Befehl fassen — ideal für einen frisch gemieteten Cloud-Mac oder einen GitHub Actions Self-Hosted Runner. Vollständiges Skript im Ressourcenordner dieses Artikels:

resources/bootstrap-openclaw-gateway-launchd.sh

Auf dem Remote-Mac:

chmod +x bootstrap-openclaw-gateway-launchd.sh
./bootstrap-openclaw-gateway-launchd.sh

Ablauf des Skripts:

1. node / openclaw erkennen; falls fehlend npm i -g openclaw@latest ausführen
2. ~/Library/Logs/OpenClawGateway anlegen
3. openclaw onboard bevorzugen; falls keine Plist existiert, Fallback-LaunchAgent schreiben
4. launchctl bootstrap + kickstart -k
5. Abnahme mit lsof + openclaw gateway probe

7. Health-Probes und äußeres Self-Healing

KeepAlive prüft nur, ob der Prozess existiert — nicht «Prozess-Zombie, aber Port noch LISTEN». Fügen Sie einen leichten Probe-LaunchAgent hinzu (alle 5 Minuten):

#!/bin/bash
# ~/bin/openclaw-gateway-healthcheck.sh
set -euo pipefail
PORT="${OPENCLAW_GATEWAY_PORT:-18789}"
LABEL="com.openclaw.gateway"
DOMAIN="gui/$(id -u)"

if ! openclaw gateway probe >/dev/null 2>&1; then
  logger -t openclaw-ha "probe failed, kickstart gateway"
  launchctl kickstart -k "${DOMAIN}/${LABEL}" || true
fi

Kombinieren Sie das mit einer Plist mit StartCalendarInterval unter ~/Library/LaunchAgents/com.openclaw.gateway-healthcheck.plist. Optional UptimeRobot oder Prometheus Blackbox Exporter — aber die Probe muss denselben Pfad wie Webhooks nehmen (Reverse Proxy und TLS inklusive), nicht nur localhost curlen.

Logs mit newsyslog oder größenbasierter Truncation rotieren, damit eine einzelne Datei die NVMe nicht füllt — bei vollem Datenträger beenden launchd-Kindprozesse mit ENOSPC, was wie zufällige Verbindungsabbrüche wirkt.

8. Git-versionierte Konfiguration und Rolling Upgrades

Diese Dateien unter Versionskontrolle stellen und in PRs reviewen statt per SSH zu editieren:

Minimale Upgrade-Skript-Reihenfolge (abgestimmt mit dem Begleitartikel zur Mehrkanal-Gateway-Stabilität):

openclaw backup create
npm update -g openclaw@latest   # 或锁版本号
openclaw doctor --fix
launchctl kickstart -k "gui/$(id -u)/com.openclaw.gateway"
openclaw gateway probe
# 多插件环境：逐个 browser/cron doctor

9. Sieben-Schritte-Abnahme-Checkliste

Vor Release oder Go-Live einer neuen Maschine per SSH abhaken:

• openclaw doctor ohne ERROR
• launchctl print gui/$(id -u)/com.openclaw.gateway Status running
• lsof -nP -iTCP:18789 -sTCP:LISTEN PID stimmt mit Plist überein
• openclaw gateway probe erfolgreich
• Öffentlichen Einstieg vom Büronetz / Mobilfunk curlen (nicht nur 127.0.0.1)
• Nach sudo reboot Probe innerhalb von 2 Minuten weiterhin erfolgreich
• Gateway-PID absichtlich killen — automatische Wiederherstellung innerhalb von 30 Sekunden ohne Throttle-Spam

10. Warum Mac mini weiter der beste Host für diese Automatisierung ist

Ein Gateway muss dauerhaft online, leise und pfadkonsistent bleiben. Mac mini M4 auf Apple Silicon verbraucht im Leerlauf etwa 4 W — 24/7 kostet eine Größenordnung weniger als ein Desktop-Tower. launchd, Homebrew und OpenClaws ~/.openclaw entsprechen Ihrer lokalen Entwicklungsmaschine, Sie pflegen kein zweites Runbook.

Wenn Sie OpenClaw vom «Experiment auf dem Laptop» zu einem dedizierten Remote-Mac verlagern, stabilisieren Sie zuerst die Ein-Knoten-Automatisierung, bevor Sie weitere Knoten hinzufügen. Auf der Macstripe-Startseite gibt es tageweise abrechenbare Mac-mini-Tests in mehreren Regionen — einmal das Bootstrap-Skript durchlaufen, und es schlägt ein dauerhaft eingeschaltetes Bürogerät.

FAQ

Muss ein OpenClaw-Gateway zwingend launchd nutzen?

Nicht zwingend — aber auf macOS ist launchd der offizielle Daemon-Manager und eignet sich für unbeaufsichtigten Betrieb besser als nohup. Docker passt zu parallelen Mehrversion-Setups; launchd zu einem latenzarmen Gateway mit weniger Virtualisierungs-Overhead.

LaunchAgent oder LaunchDaemon — was wählen?

LaunchAgent, wenn Sie Benutzer-TCC oder Schlüsselbund-Zugriff brauchen; LaunchDaemon (Root), wenn der Dienst ohne angemeldeten Benutzer lauschen muss. Die meisten Teams starten mit Agent.

Steht onboard im Konflikt mit einer handgeschriebenen Plist?

Das Label muss eindeutig sein. Vor dem Upgrade bootout, damit nicht zwei Prozesse um 18789 konkurrieren. Finale Plist in Git committen.

Probe schlägt fehl, aber der Port lauscht?

Auth, TLS und Bind-Adresse prüfen. doctor ausführen, dann ~/.openclaw vergleichen; Details im launchd-Fehlerbehebungs-Handbuch.

Wie deploye ich auf mehrere Macs?

Selbst gehostete Runner + dasselbe Bootstrap-Skript, Secrets für Tokens, rollierende probe-Abnahme. Siehe GitHub Actions Multi-Machine-Zusammenarbeit.

Fazit

Schluss mit manueller Konfiguration heißt nicht «nie wieder Terminal» — es heißt im Terminal nur Skripte ausführen, keine Ad-hoc-Befehle: onboard registriert launchd, Plist geht in Git, bootstrap provisioniert neue Maschinen, probe nimmt ab, healthcheck fängt Randfälle ab. Das Gateway wird vom «Vordergrundprozess in einer SSH-Sitzung» zu wiederholbarer Infrastruktur.

Nächster Schritt: bootstrap auf einem Remote-Mac ausführen, Reboot-Übung machen, die Sieben-Schritte-Checkliste ins Team-Wiki kopieren. Wenn Sie einen dedizierten Knoten brauchen, Region auf der Macstripe-Startseite wählen.