OpenClaw Betrieb-Runbook: Gateway 18789 Health-Checks, stufenweise Upgrades & Log-Disk-Planung (2026)

Drei Betriebsreflexe, die man verinnerlichen sollte:

Doppelsonde — I/O-Spitzen nicht als Gateway-Fehler fehldeuten

curl auf Port 18789 immer mit lsof zur Port-Eigentümerprüfung kombinieren. Ein langsames Dashboard signalisiert meist einen Disk-Write-Spike, keinen Gateway-Ausfall.

curl + lsof
Stufenweises Upgrade, 30-min-Rollback-Fenster

Version einfrieren → Golden Node zuerst → dann Produktion. Tarball-Config und altes plist gemeinsam wiederherstellen; Rollback sollte nie länger als 30 Minuten dauern.

≤ 30 Min
Logs vom Root-Volume trennen

Log-Verzeichnis und npm-Cache benötigen eigenes logrotate. Ein lautlos volles Root-Laufwerk ist die häufigste Ursache für unerwartete Gateway-Beendigungen.

logrotate 7T

Dieser Artikel beantwortet eine einzige Frage

Nachdem das OpenClaw-Installationsskript abgeschlossen ist und Gateway 18789 zum ersten Mal grün leuchtet, geraten Teams oft in eine Phase „läuft, bis es nicht mehr läuft": sporadische 401-Fehler, ein Knoten verhält sich nach einem Upgrade anders, oder der Gateway beendet sich still, weil das Root-Laufwerk voll ist. Diese Probleme deckt das Installationshandbuch nicht ab.

Dieser Artikel beantwortet eine einzige Frage: Wie standardisiert man den täglichen OpenClaw-Betrieb in ein wiederverwendbares Runbook, das jedes Teammitglied in 15 Minuten für einen Health-Check oder Rollback nutzen kann? Umfang: Gateway-Health-Sonden → stufenweise Upgrade-Strategie → Rollback-Verfahren → Tailscale / SSH-Auswahl → Log-Disk-Planung.

1. Gateway 18789 Health-Sonden

Der „Health-Check" vieler Teams besteht aus einem einzigen curl-Aufruf — das reicht nicht. Wenn der Port von einem Restprozess belegt ist oder launchd den Dienst nicht korrekt neu gestartet hat, hängt curl statt sofort zu scheitern. Eine korrekte Sonde validiert sowohl die HTTP-Antwort als auch den Port-Eigentümer.

Gateway-Doppelsonde (als Cron-Job geeignet)

# 1. HTTP-Liveness: 200 erwarten, bei Fehler alarmieren
curl -fsS --max-time 3 http://127.0.0.1:18789/health \
  && echo "gateway OK" || echo "GATEWAY FAIL"

# 2. Port-Eigentümer prüfen: PID muss zu node/openclaw gehören
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 3. Letzte Fehlerzeilen (Pfad an Installation anpassen)
tail -n 50 ~/.openclaw/logs/gateway.log | grep -i "error\|warn\|exit"

Gibt curl 200 zurück, aber das Dashboard ist träge, prüfen Sie zuerst die Disk-I/O: iostat -d 1 5. Einen Log-Write-Spike mit einem Gateway-Ausfall zu verwechseln ist der häufigste Fehlalarm. Halten Sie einen dedizierten „Golden Node" auf derselben Version wie die Produktion, um Anomalien sofort vergleichen zu können.

Port 18789 vom falschen Prozess belegt

Gibt lsof -iTCP:18789 eine PID zurück, die nicht OpenClaw gehört, überprüfen Sie mit launchctl list | grep openclaw den Service-Status. Ein Restprozess einer alten Installation hält häufig den Port. Diesen Prozess zu beenden ohne das alte plist zu entfernen führt dazu, dass launchd ihn beim nächsten Login neu startet.

2. Drei Schritte vor jedem Upgrade

OpenClaw veröffentlicht regelmäßig Updates. Jeder Version blind zu folgen birgt zwei Risiken: Änderungen an Konfigurations-Keys, die den Gateway-Start verhindern, oder Inkompatibilitäten mit bestehenden Channel-Konfigurationen. Stufenweise Upgrades sind der Standard, aber viele Teams interpretieren „stufenweise" als „erst auf einer Maschine testen" und überspringen das Einfrieren der Version sowie die Disk-Prüfung.

Pre-Upgrade-Checkliste: der Unterschied im Überblick
Schritt	Durchgeführt Stufenweises Upgrade	Übersprungen npm update direkt
Versions-Freeze (aktueller Tag)	Rollback per `npm install openclaw@alter-tag`	Alte Version unbekannt; nur Tarball-Restore möglich
Golden Node zuerst	Fehler auf Test-Node isoliert, Produktion unberührt	Alle Channels fallen gleichzeitig aus
Root-Disk ≥ 15 % frei	Temporäre npm-install-Dateien haben Platz	Installation bricht mittendrin ab; inkonsistenter Zustand

Pre-Upgrade-Snapshot (.upgrade-memo speichern)

# Aktuelle Version aufzeichnen
npm list -g openclaw --depth=0 > .upgrade-memo

# Konfiguration archivieren
tar czf openclaw-config-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/config/ \
  ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Disk-Freiraum prüfen ≥ 15 %
df -h / | awk 'NR==2 {print "Frei:"$4, "Genutzt:"$5}'

3. Rollback: tarball + plist zweistufige Wiederherstellung

Der häufigste Grund für Rollback-Fehler ist nicht die Binärversion — es ist Konfigurations-Key-Inkompatibilität. Eine neue Version kann Pflichtfelder hinzugefügt haben; das Binär zurückzusetzen während die neue Konfiguration bestehen bleibt führt zu einem Gateway-Startfehler. Die korrekte Reihenfolge ist: bootout → Tarball wiederherstellen → Binär herunterstufen → bootstrap.

Vollständiges Rollback-Verfahren (Ziel: ≤ 30 Min)

# Schritt 1: Service stoppen
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Schritt 2: Konfigurations-Tarball wiederherstellen
tar xzf openclaw-config-20260604.tar.gz -C /

# Schritt 3: npm-Paket herunterstufen
npm install -g openclaw@1.x.x   # durch aufgezeichneten Versions-Tag ersetzen

# Schritt 4: Service neu starten
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Schritt 5: Verifizieren (~10 s warten)
sleep 10 && curl -fsS http://127.0.0.1:18789/health && echo "Rollback OK"

Achten Sie auf plist-Pfad-Drift: Hat das Installationsprogramm der neuen Version ProgramArguments überschrieben, muss bootout den neuen plist-Pfad verwenden, bootstrap den wiederhergestellten alten. Diese Pfade können abweichen — weshalb ein Diff von altem und neuem plist vor dem Upgrade zum Runbook gehört.

4. Tailscale vs. SSH/rsync: was wann einsetzen

Die ewige Teamdebatte „Tailscale oder direktes SSH?" ist ein falsches Dilemma. Jedes Tool hat seinen optimalen Einsatzbereich. Tailscale glänzt bei Multi-Gerät- und Cross-Region-Zugang ohne Firewall-Regeln. SSH/rsync ist die richtige Wahl für Massentransfers, bei denen der Engpass die Ausgangs-Bandbreite ist, nicht der Protokoll-Overhead.

Tailscale vs. SSH/rsync Entscheidungsmatrix
Kriterium	Tailscale WireGuard-Mesh	SSH / rsync Direkter verschlüsselter Transfer
Empfohlener Einsatz	Dashboard von beliebigem Gerät, Multi-Member-Fernzugriff, VPN-Kontrollebene	CI-Artefakt-Downloads, Log-Archiv-Abrufe, geplante TB-Syncs
Latenz	DERP-Relay +~50 ms Asien↔Kanada; Direktverbindung nahe am Bare-RTT	Bare-TCP, minimaler Overhead; offener Port oder Jump-Host erforderlich
Bandbreite	~+5 % Protokoll-Overhead; geeignet für anhaltende Niedrigdurchsatz-Sessions	`--bwlimit` nutzen, um den Kanada-Ausgang nicht zu sättigen
Zugriffskontrolle	Tailscale ACLs pro Gerät/Benutzer	SSH-Keys; `authorized_keys` regelmäßig prüfen
Fehlerbehebung	ACL-Regeln, DERP-Node, MagicDNS-Auflösung	Routing, MTU, Timeout und Wiederaufnahme

rsync mit Bandbreitenlimit (Kanada-Ausgang schützen)

# Log-Archive vom Kanada-Node abrufen, max. 50 MB/s, Fortsetzung bei Abbruch
rsync -avz --bwlimit=50000 --partial \
  user@canada-m4.hashvps.com:~/.openclaw/logs/archive/ \
  ./local-logs/

# Prüfen, ob Tailscale Direktverbindung nutzt (kein DERP-Relay)
tailscale ping canada-m4 --until-direct

5. Log-Disk-Planung: logrotate-Konfiguration und Partitionierungsempfehlungen

Ein überraschend hoher Anteil unerwarteter Gateway-Beendigungen lässt sich auf ein volles Root-Laufwerk zurückführen. OpenClaw schreibt Logs standardmäßig ins Home-Verzeichnis des Benutzers — dasselbe Volume wie der globale npm-Cache. Fügen Sie Xcode-Exporte oder CI-Temp-Dateien hinzu und ein 512-GB-Laufwerk kann sich still in wenigen Wochen füllen. Die richtige Lösung ist logrotate, nicht ein regelmäßiges rm.

~/.openclaw/logrotate.conf (Pfade anpassen)

/Users/mac/.openclaw/logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    dateext
    copytruncate
}

# Zu crontab hinzufügen (täglich um 03:00 Uhr):
# crontab -e, dann einfügen:
# 0 3 * * * /usr/local/bin/logrotate /Users/mac/.openclaw/logrotate.conf

Für den npm-Cache: npm config set cache-max 10240 begrenzt ihn auf 10 GB; nach jedem Upgrade npm cache clean --force ausführen. Bei einem 1-TB-Node empfiehlt es sich, ~/.openclaw/logs und den npm-Cache auf ein separates Volume zu verschieben — so beeinträchtigt ein Log-Anstieg weder Root-Disk noch Gateway-Prozess.

6. FAQ: Sechs häufige Betriebsfragen

Gateway 18789 Health-Check gibt kein 200 zurück — wo zuerst nachsehen?

Führen Sie lsof -nP -iTCP:18789 -sTCP:LISTEN aus, um zu prüfen, ob etwas lauscht. Keine Ausgabe bedeutet, dass der Prozess nicht läuft: prüfen Sie launchd mit launchctl list | grep openclaw, dann die letzten 50 Zeilen von ~/.openclaw/logs/gateway.log. Lauscht der Port, liefert HTTP aber 500, ist ein Konfigurations-Key-Fehler wahrscheinlich — Vergleich mit dem Pre-Upgrade-Tarball.

Muss nach einem Rollback der plist-Pfad manuell angepasst werden?

Nur wenn das Installationsprogramm der neuen Version ProgramArguments verändert hat. Bei einem reinen npm-Versions-Bump ohne Installationsänderungen lässt die Tarball-Wiederherstellung den plist unverändert. Hat sich der Binärpfad geändert, muss ProgramArguments im plist vor dem bootstrap auf den alten Binärpfad gesetzt werden — genau deshalb gehört ein Diff von altem und neuem plist ins Runbook.

Mehrere Nodes gleichzeitig oder nacheinander upgraden?

Immer nacheinander. Den Golden Node zuerst upgraden; 24 Stunden lang Gateway-Gesundheit und Channel-SLA beobachten. Dann Produktions-Nodes mit mindestens 30 Minuten Abstand schrittweise deployen. Gleichzeitige Upgrades bedeuten: tritt ein Problem auf, gibt es keine Vergleichsbasis und alle Nodes fallen zusammen aus.

Dashboard zeigt 100 % CPU — ist das ein OpenClaw-Bug?

Nicht unbedingt. Nutzen Sie top -o cpu oder den Activity Monitor, um die tatsächlich CPU-intensive PID zu identifizieren. Ein gesunder OpenClaw-Gateway-Prozess sollte im Normalbetrieb bei 1–5 % CPU liegen. Läuft ein node-Prozess heiß, prüfen Sie gestaute Channel-Anfragen oder abnormale Log-Schreibvorgänge. Auf einem dedizierten Mac mini können Sie mit renice Xcode-Build-Prozesse herunterpriorisieren, damit sie nicht mit OpenClaw konkurrieren.

Tailscale ist verbunden, aber das Dashboard ist nicht erreichbar — warum?

Prüfen Sie in Ihrer Tailscale-ACL-Policy, ob Port 18789 für das betreffende Gerät erlaubt ist. Holen Sie sich dann die Tailnet-IP per tailscale ip -4 und testen Sie direkt: curl http://<tailnet-ip>:18789/health. Funktioniert die IP, aber nicht der MagicDNS-Hostname, ist es ein DNS-Auflösungsproblem, kein Gateway-Problem.

Schreibt der Gateway nach logrotate weiterhin in die richtige Datei?

Mit copytruncate kopiert logrotate die Datei und kürzt das Original in-place — der Datei-Deskriptor des Gateways bleibt dabei gültig. Bei Verwendung des Standard-create-Modus muss dem Gateway ein SIGHUP-Signal gesendet oder per postrotate-Skript launchctl kickstart ausgeführt werden, um den Log-Handle neu zu öffnen. copytruncate ist einfacher und vermeidet jede Dienstunterbrechung.