2026 OpenClaw Cluster-Praxis
Mehrknoten-Merge, Multi-Path-Log-Slices, Quotas & Webhook-Fehler-Summary

Dieses HowTo ergänzt Konfig-Fragmente mergen & Canary-Workflow (deterministische Merge-Reihenfolge) und Mandanten-Split, Doctor-Merge & Webhook-Digests (Readiness-Zeilen) um die operative Schicht: wo Logs physisch landen, wie viele Megabyte oder Inodes Sie pro Slice erlauben, und wie fehlgeschlagene Webhooks als kompakte Summary sichtbar werden. Für Gateway-Verkehr und Broadcast-Pfade siehe Multi-AZ-Gateways & Webhooks.

Schritt 1–3: Merge-Vertrag und mehrere Konfig-Slices

Inventarisieren Sie auf jedem clustervps-Gateway dieselbe Verzeichnisstruktur (gateway.d, workflows.d, regionale Overlays). Legen Sie einen unverrückbaren Stack fest — typisch Basis → Region → Mandant — und mergen Sie lokal zu einer autoritativen Datei, bevor launchd neu lädt. Vergleichen Sie den SHA-256 des gemergten Outputs hostübergreifend; weicht er ab, ist das ein Blocker für Log-Quotas und Summary-Pfade, weil sonst jeder Knoten andere Zielverzeichnisse schreibt.

#!/usr/bin/env bash
set -euo pipefail
/usr/local/bin/openclaw config merge --stack base,region,tenant \
  --out /tmp/openclaw.merged.yaml
/usr/bin/shasum -a256 /tmp/openclaw.merged.yaml | /usr/bin/awk '{print $1}' > /tmp/merge.sha256
/usr/bin/scp /tmp/merge.sha256 zentral:/var/db/openclaw/merge/$(hostname).sha256

Dokumentieren Sie im Runbook, welche Felder nach dem Merge noch per Hot-Reload gehen dürfen und welche einen kontrollierten Neustart brauchen — sonst rotieren Logs auf dem alten Pfad weiter, während das Gateway schon den neuen Slice liest.

Schritt 4–6: Multi-Path-Log-Slices, Quotas und Rotation

Weisen Sie getrennte Wurzeln zu: Gateway-HTTP, strukturierte Webhook-Retries, Audit-JSONL. Pro Slice genau ein primärer Writer-Prozess; Sidecars nur append-only auf ihre eigene Datei. Reservieren Sie auf der Log-Partition ein hartes Budget (Beispiel: 12 % der SSD nur für OpenClaw-Logs) und definieren Sie Warnschwellen bei 75 % und 90 % belegter Bytes und — oft vergessen — bei 80 % verbrauchter Inodes im Volumen.

• Rotation: Tägliche Umlagerung per newsyslog, logrotate-Kompat-Schicht oder eigenem mv+Kompressionsschritt; immer atomar per rename, damit Tail-Reader keine torn files sehen.
• Retention: Anzahl Archive begrenzen (z. B. sieben tägliche + vier wöchentliche); ältere Dateien explizit löschen, statt unbegrenzt zu komprimieren.
• Metrik: du -sh pro Slice in die Readiness-Zeile aufnehmen, damit LB und Operator dieselbe Zahl sehen.

/usr/bin/install -d -o root -g wheel -m0750 /var/db/openclaw/logs/gateway
/usr/bin/install -d -o root -g wheel -m0750 /var/db/openclaw/logs/webhook-retry
/usr/bin/install -d -o root -g wheel -m0750 /var/db/openclaw/audit/jsonl
# Quota-Check (Beispiel): Alarm wenn >75% des reservierten Log-Budgets
/usr/sbin/diskutil apfs listVolumeGroups || true

Schritt 7–8: Webhook-Fehler-Summary broadcasten

Ein dedizierter Aggregator (kleiner LaunchDaemon oder Sidecar) sammelt strukturierte Fehlerzeilen der letzten fünf Minuten: HTTP-Status, Partner-URL ohne Query-Secrets, Retry-Zähler, AZ-Label, Korrelations-ID. Er schreibt eine Summary-Datei oder Objektstore-Key, den alle Gateways read-only einbinden — Broadcast bedeutet: identischer Inhalt flottenweit, nicht mehrfach unterschiedliche lokale Fehlerlisten. Signieren Sie den Ausgabekanal mit einem eigenen Secret, getrennt von eingehenden Webhook-Signaturen.

#!/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/webhook-summary.json

Binden Sie die Summary nur in die gemergte Readiness ein (z. B. zusätzliches Feld webhook_digest_stale); sie darf keinen Traffic promoten, sondern nur Transparenz schaffen, wenn Partner-Endpoints ausfallen oder Retry-Schleifen laufen.

Kurz-Matrix: ein Pfad vs. mehrere Slices

Die Kapazitätsplanung bleibt gekoppelt an reale Hardware: Tarife mit genügend SSD-Reserve reduzieren Überraschungen bei gleichzeitiger Rotation und Build-Artefakten auf demselben Knoten.

Triage-Checkliste: Rotation, Platte, Inode

• Rotation hängt: Prüfen, ob noch Prozesse auf .log.1 mmappen; nach postrotate kill -USR1 an den richtigen Daemon senden; Schreibberechtigungen auf Archiv-Verzeichnis.
• Platte „voll“ trotz wenig Daten: df -h und tmutil listlocalsnapshots / prüfen; Time-Machine-lokale Snapshots auf Gateway-Macs häufiger vergessen als erwartet.
• Inode- oder Metadaten-Druck: df -i (bzw. APFS-Äquivalent über Belegung kleiner Dateien) neben df -h; bei Millionen kleiner Retry-Scratchfiles alte Archive aggressiver löschen oder Slice auf separates Volume legen.
• Webhook-Summary leer, Partner down: Fenster auf 1 Min verkürzen, synthetischen 4xx/5xx injizieren, prüfen ob Aggregator noch läuft und ob der öffentliche Spiegelpfad erreichbar ist.
• Merge-Hash driftet: Writer-Lock setzen, erneut mergen, keine parallelen rsync-Wellen ohne Versionierung (siehe Artefakt-Leitfäden im Blog).

Minimal-Checkliste (Reihenfolge)

• 0 Alle Hosts auf identische OpenClaw-Revision; Merge-Stack dokumentiert.
• 1 Gemergten Config-Hash flottenweit vergleichen.
• 2 Drei Log-Wurzeln anlegen, Quotas und Schwellen in Monitoring.
• 3 Rotation testen (trockener Lauf mit SIGUSR1 oder manuellem rename).
• 4 Webhook-Summary erzeugen, öffentlichen Spiegel ohne Secrets.
• 5 Readiness mergen: Doctor + Disk/Inode + Summary-Staleness; erst danach LB erhöhen.

FAQ

Warum zuerst mergen, dann Logs skalieren? Ohne gemeinsamen Vertrag schreibt jeder Mac andere Pfade — Rotationsskripte und Digest-Topics divergieren still.

Was bedeutet Inode-Druck neben freiem Speicher? Viele kleine Dateien füllen Metadaten; immer df -h und df -i gemeinsam lesen.

Darf die Summary Traffic steuern? Nein — nur informieren; Promotion bleibt bei LB- und Canary-Hebeln in den verlinkten Artikeln.