2026 OpenClaw v2026.5.20 Mac VPS Upgrade-Abnahme: managed Gateway Node, Protokoll-Drift und Policy/Doctor Runbook (Entscheidungsmatrix und FAQ)

1. Schmerzpunkte: Multi-Node, Protokoll-Drift, Config-Drift

Auf Mac-Cloud-Hosts sind OpenClaw-Ausfaelle selten «Modell ohne Guthaben». Hauefiger laeuft der Gateway-Prozess weiter, Port 18789 hoert zu, aber CLI und Gateway sitzen auf verschiedenen Node-Installationen — oder die Protokollversionen weichen um eine Minor-Stufe ab. Symptome: der erste gateway restart nach dem Upgrade scheitert am Healthcheck, Kanaele fallen sporadisch weg, Cron markiert erfolgreiche Jobs als fehlgeschlagen. Das trifft besonders Teams, die OpenClaw seit Wochen stabil betrieben haben und v2026.5.20 nur wegen Release Notes einspielen — ohne zu wissen, dass der Patch primaer Betriebssicherheit auf Multi-Node-Mac-VPS adressiert.

Wer bereits das Gateway-Runbook oder die Mai-Baseline gelesen hat, erkennt das Muster: der Dienst wirkt gesund, solange niemand restart ausloest oder ein Cron-Lauf die Protokollgrenze beruehrt. v2026.5.20 macht genau diese unsichtbare Kluft sichtbar — vorausgesetzt, Sie messen Node-Pfad und running version im selben Wartungsfenster.

Die folgenden vier Cluster treten in Produktions-Tickets am haeufigsten auf und lassen sich direkt in ein Change Board uebernehmen:

1. Multi-Node-Stille Drift: Neben Homebrew-Node, nvm und Install-Skript-Node konnte altes openclaw update Follow-up-Befehle auf ein anderes Node legen, waehrend der managed Gateway-Dienst weiter alte Pfade nutzt.
2. CLI/Gateway-Protokoll-Abweichung: CLI bereits 5.20, Gateway noch 5.18 — Restart-Healthcheck meldet scheinbar Fehler, Teams reinstallieren Plugins auf der falschen Schicht.
3. Neue doctor-Warnungen ignoriert: Ab 5.20 Hinweise auf Klartext-API-Keys in openclaw.json, Sandbox-Policy fuer MCP-Tools, ungueltiges thinkingFormat. Blindes doctor --fix ohne Diff kann noetige Provider-Felder loeschen.
4. Exec-Approval-Pfad geaendert: Skills duerfen cat SKILL.md nicht mehr per Shell; read-Tool ist Pflicht. Automatisierung mit shell-cat bricht nach Upgrade mit «Tool abgelehnt».

2. Entscheidungsmatrix: wann auf 5.20

3. Snapshot vor dem Upgrade

Vor jeder Binaer-Aenderung diese Ausgaben im Change-Ticket sichern — reiner Text reicht fuer Rollback-Vergleich:

openclaw --version
openclaw gateway status --json | tee /tmp/gw-before.json
lsof -nP -iTCP:18789 -sTCP:LISTEN
which node; node -v
type -a node 2>/dev/null || true
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)
launchctl print gui/$(id -u)/ai.openclaw.gateway 2>/dev/null | head -80

Notieren Sie den absoluten Node-Pfad in ProgramArguments und running Gateway version aus gateway status --json — ab 5.20 ist dieses Feld zuverlaessiger. Weicht die Basis vom Gateway-Runbook ab, zuerst reparieren, dann upgraden.

Archivieren Sie den Snapshot im Change-Ticket mit Zeitstempel und SSH-User. Bei Rollback vergleichen Sie /tmp/gw-before.json Zeile fuer Zeile mit dem Post-Upgrade-Output — Unterschiede bei runningVersion oder server sind oft der schnellste Hinweis, dass der managed Node-Fix noch nicht greift. Fuer Staging-Knoten gilt dieselbe Checkliste; nur so reproduzieren Sie Multi-Node-Drift vor dem Produktionsfenster.

4. Sieben-Schritte-Runbook

Schritt 1: Version pinnen und update

openclaw update --tag v2026.5.20
# oder npm global:
# npm i -g openclaw@2026.5.20

Warten bis der Restart-Healthcheck am Ende durch ist. Bei Fehlschlag nicht sofort Plugins neu installieren — Schritt 2 (Node) zuerst.

Schritt 2: managed Gateway Node ohne Drift

openclaw --version
which node
node -v
openclaw gateway status --json | jq '.server,.version,.runningVersion'

Kernfix in 5.20: Follow-up-Befehle nach openclaw update muessen dasselbe Node nutzen wie der managed Gateway-Dienst — nicht «CLI Homebrew, launchd /usr/local». Hauptversionen von node -v auf beiden Pfaden muessen uebereinstimmen.

Schritt 3: Gateway restart und 18789

openclaw gateway restart
sleep 3
lsof -nP -iTCP:18789 -sTCP:LISTEN
openclaw gateway status --deep

Schlaegt --deep fehl, Gateway-Runbook zu gateway.auth, Loopback und Token — nicht zuerst den Modell-Provider aendern.

Schritt 4: openclaw doctor (Policy-Plugin)

openclaw doctor
openclaw doctor --fix   # nur nach Diff-Review

Ab 5.20 bundled Policy-Plugin fuer Kanal-Compliance und Workspace-Hinweise. Bei Klartext-API-Key-Warnungen in Umgebungsvariablen oder SecretRef migrieren, doctor nicht abschalten.

Schritt 5: Kanal-Smoke

Eine Sende/Empfang-Runde auf Telegram, Feishu, Slack oder Ihrem Produktionskanal. Bei mehreren Kanaelen zuerst die Einzelkanal-Phase aus dem Multi-Channel-Runbook — nicht zu viele Variablen gleichzeitig.

Schritt 6: Cron-Probe

openclaw cron list
# eine risikoarme Aufgabe ausloesen, Endzustand success ohne tool-warning-Override

5.20 behebt erfolgreiche Cron-Jobs, die durch trailing tool warnings als fehlgeschlagen galten, sowie Blockaden zwischen main-session und cron wake lane. Nach Upgrade muessen Log und Endzustand uebereinstimmen.

Planen Sie fuer Schritte 1–6 insgesamt etwa zehn bis fuenfzehn Minuten auf einem dedizierten Mac VPS ohne parallele npm-Global-Updates. Unterbrechen Sie nicht mitten in Schritt 2, wenn which node und launchd divergieren — das ist der Kern von v2026.5.20, nicht ein Grund zum Abbrechen. Dokumentieren Sie jeden Befehl mit Exit-Code; das beschleunigt Escalations, falls ein Kanal-Smoke in Schritt 5 scheitert, obwohl Gateway bereits gruen ist.

5. v2026.5.20 Abnahmetabelle

6. Fehler-Mapping und Rollback

Rollback: JSON-Backup zurueck, vorherigen Tag pinnen, gateway restart. Bei nicht auditierbarer Config: Mai-Baseline auf frischem Knoten.

Halten Sie waehrend Rollback dasselbe Disziplin-Niveau wie beim Upgrade: zuerst Node-Pfade vergleichen, dann Config, zuletzt Kanaele. Ein haeufiger Fehler ist, nach Rollback sofort Pairing neu zu starten, obwohl der Gateway-Prozess noch auf dem falschen Binary haengt — das verlaengert das Fenster ohne Nutzen. Wenn Sie ACP- oder Plugin-Rollback aus dem ACP-Rollback-Runbook kennen, kombinieren Sie Digest-Pin und json-Restore in einer Ticket-Notiz.

7. Drei Pruefsignale

• Node-Konsistenz: Im selben Wartungsfenster nutzen launchd-managed Node und das von openclaw update gemeldete Node dieselbe Hauptversion — sonst greift der 5.20-Fix nicht.
• Versions-Sichtbarkeit: gateway status --json liefert running Gateway version = 2026.5.20, aligned mit openclaw --version.
• Cron-Endzustand: Erfolgreiche Jobs duerfen nicht mehr durch trailing tool warnings ueberschrieben werden; eine Probe mit delivered-Flag zaehlt mehr als nur Gateway-Gruen.

8. FAQ

Frage: Docker vs npm-Pfad? Im Container gilt das Node im Image; auf Mac-VPS-Host mit npm+launchd ist Node-Pinning aus diesem Artikel entscheidend. Docker-Upgrade: Image-Tag und Volume-Config-Backup angleichen.

Frage: 5.18/5.19 ueberspringen? Ja, mit Snapshot; Staging zuerst sieben Schritte, dann Produktion.

Frage: Bezug zum Erst-Deploy in fuenf Schritten? Fuenf Schritte = von null live; dieser Artikel = sicheres Upgrade einer laufenden 7×24-Instanz auf 5.20. Neuinstallation kann direkt 5.20, danach Multi-Channel-Abnahme.

9. Fazit

v2026.5.20 liefert weniger Feature-Show als stabile Node- und Protokoll-Vertraege fuer Mac VPS — genau dort, wo «nach dem Upgrade haengt der Gateway» entsteht. Notebook oder WSL2 eignen sich fuer Kurztests; Sleep, NAT und Multi-Node-Mischung verdecken update-Drift. Reines Linux-VPS laeuft Gateway, fehlt aber launchd plus Apple-Stack-Dokumentation. Wer OpenClaw als 7×24-Produktionseingang braucht, sollte im Wartungsfenster dieses Sieben-Schritte-Runbook fahren und managed Node, doctor und Cron-Endzustand ins Change-Template schreiben — statt wiederholt Voll-Reinstall. Teams mit Bedarf an stabilem Disk, auditierbarem launchd und SSH-Runbooks profitieren von einem VPSMAC Apple-Silicon-Mac-VPS, der 18789, Config-Backup und Upgrade-Abnahme in einer Betriebsebene buendelt — konsistent mit Gateway-, Multi-Channel- und Baseline-Leitfaeden auf dieser Site.