2026 OpenClaw Cluster-Praxis
doctor --deep, launchd-Cleanup, Canary-Ports & Webhook-Summary

Dieser Text ist bewusst komplementär zu den rein verkehrsgetriebenen Canary-Playbooks in Canary, Skill-Pack-Slices & gemergte Probes und Konfig-Fragmente mergen & Canary-Shunt: Dort steuern Sie LB-Anteile und Merge-Reihenfolge. Hier räumen Sie die physische und schedulbare Realität auf — doppelte launchd-Labels, kollidierende Listener und fehlinterpretierte Service-Discovery — damit Doctor, Readiness und Webhook-Summaries wieder dasselbe Cluster meinen. Für Mandanten-Digests und Token-Überlappung siehe Mandanten-Fragmente, Doctor-Merge & Webhook-Fehler-Digests; für Gateway-Broadcast-Pfade Multi-AZ-Gateways & Webhooks; für Rolling-Peer-Konsistenz Rolling 2026.4.x & Canary-Rollback.

Schritt 1–2: Mehrknoten-Baseline mit doctor --deep

Starten Sie auf jedem clustervps-Gateway mit derselben OpenClaw-Version und leeren Sie vorher temporäre JSON-Ausgaben, damit Diff-Tools nicht alte Artefakte mischen. doctor --deep (Flag-Namen je Release prüfen) soll Sidecar-Sockets, Bonjour-/DNS-Slices und konkurrierende HTTP-Bindings im selben JSON-Schema ausgeben wie der flache Doctor — aber mit erweiterten Blöcken für registrierte Helferprozesse. Sammeln Sie die Dateien zentral: scp gw-a:/tmp/deep.json ./deep-a.json usw., dann jq-Vergleich auf identische listener_ports, mdns_fqdn und sidecar_sha. Abweichungen markieren Sie als Blocker, bevor Sie Canary-Ports oder LB-Gewichte anfassen — sonst promoten Sie Zufall.

#!/usr/bin/env bash
set -euo pipefail
HOST="$(/usr/sbin/scutil --get ComputerName)"
/usr/local/bin/openclaw doctor --deep --json | /usr/bin/tee "/tmp/openclaw-deep-${HOST}.json"
/usr/bin/diff -u /tmp/openclaw-deep-stable.json "/tmp/openclaw-deep-${HOST}.json" || true

Erst wenn der Diff nur erwartbare Canary-Zeilen zeigt (zum Beispiel absichtlich anderer HIGH_PORT_BASE), gehen Sie zu launchd und Ports über.

Schritt 3–4: Doppelte launchd-Labels minimal bereinigen

Typisches Symptom: zwei Plists unter /Library/LaunchDaemons und /usr/local/etc/LaunchDaemons referenzieren dasselbe Label — kickstart startet scheinbar erfolgreich, aber Health flattert. Vor jedem bootout ein Tar-Archiv der betroffenen Plists nach /var/db/openclaw/backup/launchd-$(date +%s).tgz legen. Listen Sie mit launchctl print system | rg -i openclaw doppelt geladene Jobs. Behalten Sie genau eine autoritative Plist (üblicherweise unter /Library/LaunchDaemons); die andere Datei umbenennen (.disabled), nicht löschen, bis Doctor wieder grün ist.

sudo /bin/tar czf /var/db/openclaw/backup/launchd-pre-clean.tgz /Library/LaunchDaemons/com.openclaw*.plist 2>/dev/null || true
sudo /bin/mv /usr/local/etc/LaunchDaemons/com.openclaw.gateway.plist \
  /usr/local/etc/LaunchDaemons/com.openclaw.gateway.plist.disabled
sudo launchctl bootout system/com.openclaw.gateway 2>/dev/null || true
sudo launchctl bootstrap system /Library/LaunchDaemons/com.openclaw.gateway.plist

Schritt 5–6: Canary-Port-Slice statt Produktions-Port zu teilen

Nach bereinigten Labels bindet das Canary-Gateway Sidecars auf einen Offset-Block (Beispiel: HIGH_PORT_BASE=47100 statt 47000). Der Load Balancer health-checkt nur den Canary-Pool auf diesen Ports, während stabile Gateways unverändert bleiben. Dokumentieren Sie Basis plus Offset in Ihrer Mandanten-Fragmentdatei, damit Fragment-Merge und Doctor dieselbe Zahl lesen. Wenn doctor --deep weiterhin zwei Listener auf demselben Produktionsport meldet, ist der Port-Slice noch nicht wirksam — zurück zu Schritt 3–4.

# LaunchDaemon Environment (Beispiel)
export OPENCLAW_HIGH_PORT_BASE="${OPENCLAW_HIGH_PORT_BASE:-47100}"
sudo launchctl setenv OPENCLAW_HIGH_PORT_BASE "${OPENCLAW_HIGH_PORT_BASE}"
sudo launchctl kickstart -k system/com.openclaw.gateway

Schritt 7–8: Webhook-Fehler-Summary broadcasten (ohne Promotion)

Koppeln Sie die letzten fünf Minuten fehlgeschlagener Webhook-Zustellungen (HTTP-Status, Partner-Endpoint, Retry-Count) an einen schreibgeschützten Endpunkt, den Ihre Readiness-Route nur einliest — analog zur Digest-Zeile in Tenant-Split & Digests. Broadcast heißt: alle Gateways lesen dieselbe Summary-Datei oder denselben Objektstore-Key, damit ChatOps und On-Call nicht pro Host raten. Die Summary erweitert Verkehr nicht; sie macht nur sichtbar, ob Canary-Ports oder Partnerausfälle korreliert sind.

#!/usr/bin/env bash
set -euo pipefail
/usr/local/bin/openclaw notifier webhook-summary --window 5m --json \
  | /usr/bin/tee /var/db/openclaw/summary/webhook_failures.json
/usr/bin/install -d /var/db/openclaw/summary
/usr/bin/install -m0644 /var/db/openclaw/summary/webhook_failures.json \
  /usr/local/share/openclaw-infra/public/summary.json

Kurz-Checkliste (Reihenfolge strikt einhalten)

• 0 Writer-Lock setzen (Ticket-ID im Dateisystem oder Nomad-Constraint), alle Gateways auf identische OpenClaw-Revision.
• 1 doctor --deep --json pro Host, zentral diffen; Blockerliste führen.
• 2 launchd-Duplikate per bootout/bootstrap bereinigen; ein Label, eine Plist.
• 3 Canary-HIGH_PORT_BASE setzen, Sidecars neu binden, erneut doctor --deep.
• 4 Webhook-Summary erzeugen und öffentlich lesbar spiegeln (ohne Secrets im JSON).
• 5 Readiness-Route mergen: Doctor + Summary + optional bestehende Digests; erst danach LB-Canary nach den anderen HowTos erhöhen.

Rollback-Matrix (Marken R0–R3)

Jede Marke ist ein commit-fähiger Zustand — nicht „wir haben irgendwas zurückgedreht“. Kombinieren Sie mit Artefakt-Disziplin aus Artefakt-Matrix (rsync), falls Sie Konfiguration zwischen Hosts kopieren.

FAQ

Reicht flacher doctor nach einem Major-Upgrade? Für Mehrknoten-Betrieb nein — Deep deckt Sidecars auf, die erst nach dem zweiten Neustart registriert werden.

Darf die Webhook-Summary Traffic steuern? Nein. Sie informiert nur; Promotion bleibt bei LB- und Semver-Hebeln wie in den verlinkten Canary-Artikeln.

Wie viele Hosts minimum? Wie in den Canary-HowTos: drei ehrliche Knoten (zwei stabil, einer Canary), sonst sehen Sie keine echten Port-Kollisionen.