2026 OpenClaw Cluster-Praxis
Konfig-Schnipsel mergen, Workflow-Isolation & Canary-Shunt

Dieses HowTo richtet sich an Teams, die bereits Canary, Skill-Slices und gemergte Probes kennen und jetzt Fragment-Vorlagen deterministisch zusammenführen wollen, ohne dass sich Produktions-Workflows gegenseitig blockieren. Für den Rolling-Pfad inklusive Peer-Abhängigkeiten und Rollback-Stufen siehe Rolling auf 2026.4.x & Canary-Rollback; die Basis zu Mandanten-Fragmenten und Doctor-Digests bleibt in Mandanten-Split, Doctor-Merge & Webhook-Digests dokumentiert.

Mandanten-Konfigurationsverzeichnisse

Legen Sie auf jedem Mac dasselbe Skelett an, bevor launchd Units aktiviert werden: typischerweise /etc/openclaw/tenants/<tenant>/gateway.d/, workflows.d/ und optional overrides.d/ für experimentelle Schalter. Gateway-Fragmente beschreiben Listener und Routing-Gewichte; Workflow-Fragmente nur Queue-Namen, Concurrency-Limits und Idempotenz-Präfixe — keine Geheimnisse in Klartext, sondern Verweise auf den lokalen Secret-Store.

Workflow-Isolation erzwingen Sie über eindeutige Labels (tenant, workflow_pool, priority): jede CI-Pipeline schreibt nur in ihr Unterverzeichnis; globale Worker lesen ausschließlich das gemergte Artefakt unter /var/lib/openclaw/merged/<tenant>/. Merge-Skripte schreiben zuerst nach .tmp und finalisieren per atomarem rename, damit niemals halbes YAML unter dem Prozess landet.

Für den Betrieb: pflegen Sie im Infra-Repo ein Diagramm „welches Team darf welches Verzeichnis anfassen“ und hängen Sie die Pfade an Tickets — sonst wandert der nächste Hotfix wieder in eine Monolith-Datei. Öffentliche Kapazitäts- und Standortinfos finden Sie parallel im Tarifkatalog, damit Mandanten-Queues nicht an SSD- oder RAM-Grenzen scheitern.

Vorlagen-Merge-Strategie

Wählen Sie eine feste Merge-Reihenfolge, die Sie in CI loggen: zuerst 00-base.yaml (Cluster-weit), dann 10-region.yaml, zuletzt mandantenspezifische 90-tenant.yaml. Überschneidende Schlüssel sind ein Build-Fehler, kein stiller Last-Write-Wins — so bleiben Reviews lesbar und Rollbacks reproduzierbar.

2026-Gateway: Hot-Reload-Grenzen. In aktuellen OpenClaw-2026-Builds lassen sich viele Oberflächen des Gateways ohne harten Prozess-Stopp aktualisieren: Listener-Ports, TLS-Zertifikatsrotation über denselben SNI-Namen und einige Upstream-Gewichte, sofern der Datenpfad bereits etabliert ist. Nicht zuverlässig hot-reload-fähig bleiben typischerweise: Wechsel der Plugin-Sandbox-Bindings, Änderungen am Workflow-Executor-Image-Pin, Umbenennung von Unix-Sockets, die noch aktive Handles tragen, sowie größere Umbauten der Auth-Pipeline. Dokumentieren Sie im Runbook pro Feld „reload vs. kontrollierter Restart“ — sonst testen Sie Canary nur halb und wundern sich über hängende Sessions.

Halten Sie versions.lock neben dem Merge-Skript: Binär-Digest, Sidecar-Tags und Git-SHA des Merge-Tools. Ohne Lockfile ist kein Multi-Knoten-Canary seriös messbar.

Canary-Knotenauswahl und Rollback

Wählen Sie den Canary-Knoten nach drei harten Kriterien: identisches versions.lock wie die Produktionsflotte, niedriges reales LB-Gewicht (oder dedizierter Canary-Pool) und ausreichend freier APFS-Speicher für Queue-Spikes. Labeln Sie den Host in Nomad/Kubernetes oder Ihrer Inventardatei explizit als openclaw_canary=1, damit Playbooks nicht aus Versehen den falschen Rechner treffen.

Shunt: erhöhen Sie das Gewicht schrittweise (z. B. 2 % → 10 % → 40 %), während ein synthetischer Workflow und eine Stichprobe echter Mandantenjobs laufen. Beobachten Sie p95-Latenz, Fehlerrate und degraded-Anteil der zusammengesetzten Probe — nicht nur HTTP 200.

Rollback in unter zwei Minuten: (1) LB-Gewicht auf 0 setzen oder den Canary aus dem Pool entfernen; (2) Symlink merged auf .prev zurückdrehen, das Sie vor dem Merge angelegt haben; (3) kontrollierten Prozess-Neustart nur ausführen, wenn die Hot-Reload-Grenze laut Runbook überschritten wurde. Tragen Sie die Reihenfolge in Ihr Einsatz-Handbuch ein — im Stressfall zählt jedes weniger zu treffende Entscheid.

Doctor mit Health-Checks mergen

Extern soll nur eine Readiness-URL existieren. Intern kaskadieren Sie openclaw doctor --tenant … --json, launchd-Zustände, Disk-Druck, Queue-Tiefe und optional die Frische eines Webhook-Digest-Endpunkts zu einem JSON-Objekt. Load Balancer und Monitoring hängen sich ausschließlich daran — so vermeiden Sie das klassische „TLS-Check grün, Business-Workflow rot“.

#!/usr/bin/env bash
set -euo pipefail
/usr/local/bin/openclaw doctor --tenant "${TENANT}" --json >/tmp/oc-doctor.json
/usr/bin/curl -fsS --max-time 3 "http://127.0.0.1:9099/v1/healthz" -o /tmp/oc-sidecar.json || true
/usr/bin/python3 - <<'PY'
import json, os
from pathlib import Path
d=json.load(open("/tmp/oc-doctor.json"))
p=Path("/tmp/oc-sidecar.json")
s=json.load(open(p)) if p.exists() else {}
print(json.dumps({"tenant": os.environ.get("TENANT",""),"doctor_ok": d.get("ok"),"sidecar": s}))
PY

Setzen Sie harte Timeouts pro Teilcheck; überschreitet doctor das Budget, liefern Sie HTTP 200 mit "status":"degraded", wenn der Datenpfad noch sicher ist — sonst 503 und sofortigen Canary-Rückbau. Screenshots und Kurztexte zum Betrieb finden Sie im Hilfe-Center.

Minimal-HowTo (zehn Schritte)

1. Drei clustervps-Macs mit identischem OS-Build; Golden-Image-User und Pfade angleichen.
2. Mandanten-Verzeichnisse und Merge-Skript deployen; CI verweigert Push bei Merge-Konflikt.
3. versions.lock schreiben und auf jedem Knoten gegen openclaw version --json prüfen.
4. Canary-Knoten labeln; LB-Gewicht initial bei 0 % belassen.
5. Merge ausführen, Lint laufen lassen, .prev-Symlink setzen.
6. Gateway-Reload: nur Felder aus dem Hot-Reload-Allowlist-Kapitel Ihres Runbooks ohne Neustart; sonst rollierend pro Knoten.
7. Zusammengesetzte Readiness-Route live schalten und gegen den LB testen.
8. Synthetischen Workflow injizieren; Metriken 15–20 Minuten beobachten.
9. Canary-Gewicht schrittweise erhöhen oder bei Abweichung sofort zurücknehmen.
10. Änderung dokumentieren; bei Erfolg Fleet-Lockfile bumpen und nächste Region wiederholen.

Wenn Ihr Team denselben OpenClaw-Verbund auf mehreren dedizierten Macs ausrollen will, nutzen Sie die öffentliche Bestellseite und den Tarifkatalog für transparente Kapazität — ohne Konsolen-Login, damit Einkauf und Engineering vorab denselben Stand haben. Die Startseite fasst Angebot und Regionen gebündelt zusammen.