2026-04-16 OpenClaw-Gateway-Upgrade und Rollback auf headless gemietetem Cloud-Mac

OpenClaw auf einem gemieteten Apple-Silicon-Mac, der nur SSH spricht, ist reines Betriebshandwerk: kein Finder-Klickpfad, kein „App einfach neu starten“. Dieses Playbook vom 2026-04-16 behandelt Ingress-Freeze, Reihenfolge Stop vor npm, Checksummen-Backups von ~/.openclaw, Versions-Pinning (kein blindes @latest), Validierung mit openclaw doctor, gelegentlichen doppelten Gateway-Neustart nach Global-Installs und Tarball-Rollback unter 3 Minuten, wenn Builds schiefgehen. Verlinken Sie Umgebungsvariablen und Geheimnisse (2026-04-15), Health-Probes und nginx-Ingress, damit der Stack in HK / JP / KR / SG / US konsistent bleibt.

Risiken speziell für headless Gateways

• Heißes globales npm — Dateien ersetzen, während Node Handles hält, erzeugt Teilinstalls und „Geister“-Versionen.
• launchd-Überlappung — ein User-LaunchAgent kann das Gateway mitten im Upgrade neu starten, wenn nicht zuerst unload.
• Config-Drift — neue Minors können Keys umbenennen; halten Sie einen Git-getrackten Export von openclaw.json ohne Secrets.
• Webhook-Sturm — nginx ohne Readiness wieder öffnen lässt Partner aggressiv retryen; nutzen Sie Probes aus dem Health-Artikel.

Zuerst öffentlichen Traffic einfrieren

Auf Hosts mit nginx Reverse Proxy schalten Sie Upstreams in Wartung oder antworten mit 503 und Retry-After: 90. Interne Canarys auf 127.0.0.1:18789 sollten erreichbar bleiben, bis Sie die Welt wieder öffnen.

Backup-Matrix: Was vor npm tarren

Pfad / Artefakt	Einbeziehen?	Hinweise
~/.openclaw (oder $OPENCLAW_STATE_DIR)	Immer	Gateway zuerst stoppen; gzip-Integrität mit shasum -a 256 prüfen
Globaler npm-Prefix-Baum	Optional	Text von npm prefix -g + npm ls -g --depth=0 für Diffs speichern
launchd plist	Immer	Aus ~/Library/LaunchAgents in denselben Tarball-Ordner kopieren

TS=$(date +%Y%m%d-%H%M) tar -czf "/Volumes/backups/openclaw-state-$TS.tgz" -C "$HOME" .openclaw shasum -a 256 "/Volumes/backups/openclaw-state-$TS.tgz" > "/Volumes/backups/openclaw-state-$TS.tgz.sha256"

Installieren und pinnen: semver wie DB-Migrationen

Produktions-Gateways tracken ein explizites semver, z. B. 1.24.3, im Infra-Repo. CI darf etwas schneller treiben, aber der Mac, der Partner in Singapur bedient, soll Sie nicht um 02:00 mit einer brechenden Plugin-API überraschen. Nach Service-Stopp:

npm install -g openclaw@1.24.3

Validieren, neu starten, wann zweimal bouncen

openclaw doctor ausführen und stdout an den Log-Shipper. Gateway per launchctl bootstrap/kickstart laut plist starten. Bei veralteten Modulpfaden oder seltsamen require-Stacks ein weiterer sauberer Stop/Start-Zyklus—dokumentieren, damit On-Call kein Flapping vermutet. Vor Ende der nginx-Wartung synthetische Checks aus Health-Probes wiederholen.

Rollback: State wiederherstellen, nicht hoffen

1. Gateway und nginx-Upstream erneut stoppen.
2. Bei Bedarf defekte Global-Installation entfernen: npm rm -g openclaw, dann altes semver neu installieren.
3. Tarball entpacken: tar -xzf openclaw-state-....tgz -C "$HOME" (Ownership prüfen).
4. plist wiederherstellen, falls geändert; launchctl bootout/bootstrap nach Bedarf.
5. doctor + internen curl verifizieren; erst danach 200 am öffentlichen Ingress.

Verwandte Runbooks und Secret-Disziplin

Upgrades berühren dieselben Dateien wie Secret-Rotation—mit dem launchd-Umfeld-Guide abstimmen, damit .env und plist-Keys konsistent bleiben. Bei Blue/Green zweiten Gateway-User OPENCLAW_STATE_DIR wie dort beschrieben trennen. Nach wiederholten Ausfällen Kapazität per Preise-Witness-Node ergänzen statt eine müde Maschine endlos zu patchen.

FAQ: Gateway-Upgrades auf Cloud-Macs

Frage	Antwort
pnpm statt npm?	Unterstützt—gleiche Stop/Backup/Pin/Start-Disziplin; Store-Pfad in Runbooks.
Wöchentlich automatisieren?	Nur mit Canary + automatisiertem doctor + Probe-Gates; Produktion nie ohne Menschen im Dienst auto-upgraden.
Incidents loggen?	Bestehende Bridge; mit strukturierten Logs korrelieren.

Fazit: OpenClaw-Upgrades wie DB-Failover behandeln—Traffic einfrieren, State sichern, Versionen pinnen, zweimal validieren, Rollback in jeder Region proben, bis es Reflex ist.