2026 OpenClaw Upgrade Split-Brain: meta.lastTouchedVersion, gateway status --deep und PATH-Angleich

Schmerzpunkte: warum Restart lügt

Schmerz 1: stiller Schema-Stamp. Der neue Build schreibt beim ersten Start still openclaw.json neu; Operatoren sehen weiterhin gültiges JSON, aber Dienstaktionen scheitern zuverlässig, weil das ältere Binary den neueren Stamp erkennt und absichtlich stoppt.

Schmerz 2: PATH-Schizophrenie. Homebrew, globales npm und manuelle Symlinks führen dazu, dass which openclaw im Terminal nicht dasselbe Binary wie die launchd-Unit startet, oft still.

Schmerz 3: doppelte Supervisoren. Deep-Scans listen parallele gateway-ähnliche Dienste; doctor und install bekämpfen sich, bis Duplikate deaktiviert sind.

Schmerz 4: Pairing-Irrweg. Nach Upgrades zuerst Versionen und PATH angleichen, bevor Sie Pairing wiederholen.

Schmerz 5: Remote-URL verwechseln. Wenn gateway.remote.url noch auf einen abgeschalteten Host zeigt, ähnelt das Symptom Split-Brain; trennen Sie Hypothesen mit which -a.

Schichten: altes Binary vs. echte Korruption

L0 Erfassen Sie openclaw --version plus die Runtime-Zeilen aus gateway status.

L1 Vergleichen Sie meta.lastTouchedVersion mit der CLI-Hauptlinie; wenn die Datei neuer gestempelt ist, stoppen Sie Dienstmutationen vom alten Binary.

L2 Führen Sie openclaw gateway status --deep aus und archivieren Sie Hinweise zu systemweiten Units oder zusätzlichen Labels.

L3 Erst nach PATH-Angleich openclaw doctor; doctor --fix nur mit passender Binärversion und unter Beachtung des 4.14-Audits.

L4 Nur bei grüner RPC-Schicht channels status --probe; sonst Kanal-Runbook und Telegram-Stille.

Ticketfelder: minimaler Evidenzkoffer

Version A/B, beide Config-Pfade, meta.lastTouchedVersion, which -a openclaw, Unit-Namen, Deep-Auszug, stündliche Deltas im Upgrade-Fenster. Das trennt PATH-Drift von Duplikat-Units.

Auf Remote-Mac-Farmen ergänzen Sie CPU- und IO-Snapshots, damit Ressourcen-Hunger nicht als RPC-Fehler endet; siehe zweistufige CI-Lieferung für Ressourcenkonkurrenz.

Sieben-Schritte-Runbook

1. Beweise einfrieren: vollständiger gateway status und --deep, redigiert.
2. Alle Binaries listen: which -a openclaw plus Symlink-Ziele.
3. PATH für Shell und Supervisor auf denselben Präfix ausrichten; absolute Pfade in plists falls nötig.
4. Versionen angleichen, dann erst Dienstmutationen.
5. openclaw gateway install --force und Kaltstart laut Install-Leitfaden.
6. doctor-Schleife bis keine Blocker; Auszug ins Ticket.
7. Baseline: RPC-p95 und eine erfolgreiche UI-Aktion für das nächste Upgrade.

which -a openclaw
openclaw --version
openclaw gateway status --deep
openclaw doctor

Vertiefung: Betrieb, Compliance und Observability

Pfad-Tagebuch nach jedem brew-Upgrade

Jedes Homebrew-Upgrade kann Cellar-Pfade verschieben, während launchd weiter einen älteren PATH exportiert. Dokumentieren Sie nach jedem Touch von OpenClaw die exakte Zeichenkette, die im Plist steht, und vergleichen Sie sie mit dem Ergebnis von `which openclaw` aus einer nicht-interaktiven Shell. Ohne dieses Pfad-Tagebuch wiederholen sich Split-Brain-Vorfälle trotz scheinbar erfolgreicher Paketmanager-Ausgaben.

GDPR-konforme Logs ohne Klartext-Tokens

Speichern Sie in Tickets nur Präfixe oder gehashte Fingerabdrücke von Tokens, niemals Vollwerte in Slack oder E-Mail. Für Artikel-13-Anfragen muss nachvollziehbar sein, welche Logpipelines personenbezogene Inhalte tragen könnten. Wenn Sie Deep-Scans archivieren, maskieren Sie Pfade, die Heimverzeichnisse offenbaren, und kürzen Sie Nutzernamen auf Initialen, solange die technische Diagnose erhalten bleibt.

Doppelte launchd-Labels und Race beim Boot

Zwei Labels, die dasselbe Binary starten, erzeugen Race-Zustände: welcher Prozess zuerst die Ports hält, ist zufällig. Deep sollte beide nennen; entscheiden Sie pro Host, welches Label kanonisch ist, und deaktivieren Sie das andere explizit mit dokumentiertem Zeitstempel. Rollbacks müssen das alte Label wieder aktivieren können, ohne dass zwei Wahrheiten koexistieren.

systemd --user vs. systemweite Units

Ein Gateway, das als Benutzerdienst läuft, stirbt mit der Login-Session, wenn linger fehlt. Split-Brain kann entstehen, wenn Operatoren weiterhin systemweite Pfade erwarten. Prüfen Sie `loginctl show-user` und gleichen Sie die Unit-Datei mit dem tatsächlichen Installationsaccount ab, bevor Sie meta-Stamps interpretieren.

Warum doctor --fix auf altem Binary riskant ist

Security-Härtungen erwarten bestimmte Transformationsreihenfolgen. Ein älteres Binary kann Teilwrites erzeugen, die ein neueres Binary später ablehnt. Richten Sie zuerst PATH auf den neuesten Build aus, lesen Sie Release Notes zu Audit-Flags, und führen Sie Fixes nur mit passender Hauptversion aus.

Chaos-Drill: PATH-Inversion

Legen Sie testweise ein Wrapper-Skript mit höherer Priorität in PATH und messen Sie, wie lange Monitoring braucht, um die falsche Auflösung zu melden. Ohne Drill überschätzen Teams ihre Observability. Dokumentieren Sie Alarmtexte, damit On-Call nicht jedes Mal neu interpretiert.

Postmortem-Vorlage mit Binärpfad

Jedes Postmortem nennt explizit den aufgelösten Pfad des binaries, nicht nur die Semantikversion. Fügen Sie plist-Diffs bei, wenn verfügbar. Das reduziert Tribalwissen und verkürzt die nächste Wiederholung.

Metrik: nightly PATH-Vergleich

Vergleichen Sie jede Nacht den Pfad aus nicht-interaktiver Shell mit dem PATH aus dem Supervisor-Export. Schon kleine Abweichungen sind Frühwarnung, bevor Dienstaktionen scheitern. Kombinieren Sie das mit einer leichten RPC-Sonde aus derselben Shell-Klasse wie Ihre Automatisierung.

npm global vs. brew Reihenfolge

Wenn npm vor brew in PATH steht, gewinnt ein global installiertes openclaw oft trotz brew-Link. Definieren Sie kanonische Reihenfolgen pro Rolle: Entwicklerlaptop darf anders sein als Produktionshost, aber Produktionshosts brauchen IaC, das die Reihenfolge erzwingt.

Container-Digest statt floating tag

Für containerisierte Gateways pinnen Sie Image-Digest und notieren Sie ihn neben openclaw-Version und meta-Stamp. Sonst rotieren Basisimages still und erzeugen neue Binaries ohne koordiniertes Upgrade-Fenster.

Windows-WSL und native Dienste

Mischen Sie nicht zwei Supervisoren für dasselbe Gateway; dokumentieren Sie, welche Seite Upgrades besitzt. Deep hat auf macOS direkte Analogien; auf Windows exportieren Sie geplante Tasks inventarisiert.

Reconnect-Stürme nach kurzer Unterbrechung

Clients öffnen gleichzeitig WebSockets neu; ohne Backoff kann CPU steigen, obwohl PATH korrekt ist. Simulieren Sie das getrennt von Split-Brain, damit Ursachen nicht vermischt werden.

RACI für PATH und Units

Ein Owner für PATH-Strings, ein Owner für launchd/systemd-Dateien. Ohne RACI editieren mehrere Personen parallel und hinterlassen widersprüchliche Reloads.

Wirtschaftlichkeit: gemieteter Remote-Mac

Wenn wiederkehrende Nachtschichten nur PATH und plist jagen, amortisiert ein verwalteter Remote-Mac schneller als heroische Fixes. Sie behalten Token-Policies, outsourcen aber Hardware- und Standard-Observability.

Upgrade-Checkliste mit einem zusätzlichen Gate

Fügen Sie nach jedem Upgrade eine Zeile hinzu: aufgelöster Binary-Pfad bestätigt, bevor Success verkündet wird. Diese eine Zeile verhindert die meisten Split-Brain-Überraschungen.

Audit-4.14 und doctor-Reihenfolge

Lesen Sie den Audit-Artikel, bevor Sie aggressive doctor-Flags setzen. Manche Flags sind nur auf bestimmten Minor-Linien sicher; halten Sie eine interne Kompatibilitätstabelle.

Telegram-Stille nicht als Split-Brain

Wenn RPC grün ist, aber Kanäle still sind, folgen Sie dem Telegram-Runbook statt PATH zu drehen. Vermischung verschwendet Zeit und erzeugt neue Drift.

Pairing nur nach L1 grün

Pairing erneuert Identität, löst aber keine Binär-Drift. Halten Sie die offizielle Status-Leiter ein, bevor Sie Geräte neu freigeben.

Retention von gateway status Snapshots

Speichern Sie die ersten zwanzig Zeilen nach jedem Upgrade gehasht in Ihrer Log-Pipeline, um Diff über Releases zu ermöglichen, ohne sensible Werte zu duplizieren.

Kapazität: Artefakt-IO vs. RPC

Auf Build-Macs kann rsync die Platte sättigen und RPC langsamer machen ohne Split-Brain. Messen Sie IO-wait parallel zu Versionsstrings.

Blue-Green für Binärpfade

Wenn Sie versionierte Verzeichnisse unter /opt nutzen, symlinken Sie atomar auf das neue Release und aktualisieren Sie plist in derselben Transaktion.

Schulung: junior vs. senior Pfad

Juniors lesen oft nur Semantikversion; seniorengineers prüfen den Pfad. Trainieren Sie bewusst das Lesen von `which -a` Ausgaben in Tickets.

Rollback- tarball bekannt

Definieren Sie, welches Paket als letzte bekannte gute Version gilt und wie lange ein Rollback dauert. Split-Brain-Stress verkürzt sich, wenn Rollback kein improvisiertes wget ist.

Metrik-Kardinalität

Vermeiden Sie pro Nutzer-Labels auf jeder Zeitreihe; halten Sie Umgebung und Major-Version grob, sonst explodieren Kosten ohne diagnostischen Gewinn.

Vendor-SLA vs. interne Observability

Anbieter ersetzen keine PATH-Checks; dokumentieren Sie, welche Metriken intern bleiben müssen, selbst wenn Hardware beim Vendor liegt.

Letzte Meile: Kommunikation im Ticket

Fordern Sie Screenshots von deep und von plist-PATH in einem Kommentar. Ohne visuelle Evidenz diskutieren Teams aneinander vorbei.

LaunchAgent versus LaunchDaemon

User-Agenten starten im Login-Kontext, Daemons als root. Wenn Upgrades im Terminal als normaler Benutzer laufen, launchd aber eine root-Unit mit anderem PATH exportiert, entsteht klassischer Split-Brain. Dokumentieren Sie Label-Typ und Unix-Account, bevor Sie Tokens rotieren oder doctor ausführen.

CI-Runner und npm-Prefix-Drift

Runner injizieren eigene PATH-Präfixe. Wenn Pipelines `openclaw gateway restart` aufrufen, muss der Runner dieselbe Node-Installation sehen wie die launchd-Unit auf dem Ziel-Mac. Speichern Sie den Runner-Pfad als Variable und vergleichen Sie ihn nach jedem Secret-Rollout mit dem Host.

rsync-Last und RPC-Latenzen

Schwere Artefakt-Syncs erhöhen IO-wait und RPC-p95, ohne dass sich meta.lastTouchedVersion ändert. Korrelieren Sie Plattenmetriken mit RPC, damit Teams PATH nicht fälschlich zurücksetzen.

Wiki-Floskeln vermeiden

Vermeiden Sie leere Appelle ohne Ticket-ID. Jede Empfehlung braucht Owner und Fälligkeit, sonst bleibt Wissen flach und Split-Brain kehrt zurück.

Handover über Zeitzonen

Parallel reloaden verschiedener Teams erzeugt Races. Serialisieren Sie Dienstmutationen über eine sichtbare Sperre oder ein einziges Wartungsfenster.

Canary für neue dist-Pfade

Testen Sie neue Binärpfade zuerst auf einem kleinen Host, beobachten Sie deep 24 Stunden, rollen Sie dann breit aus.

Video plus maschinenlesbares Runbook

Kurze Lernvideos ergänzen, ersetzen aber keine exakten Kommandos in Git. Kombinieren Sie beides für konsistente Ausführung.

Token-Rotation entkoppeln

Planen Sie Secret-Rotation unabhängig von Binary-Upgrades. Wenn beides am selben Wochenende passiert, multiplizieren sich Mehrdeutigkeiten in Logs.

Forensik: mtime vs. Log-Zeit

Vergleichen Sie Dateisystem-Zeiten von openclaw.json mit Verweigerungs-Logs; Abweichungen deuten auf manuelle Kopien oder Restores ohne passendes Binary hin.

Abschluss-Gate vor Ticket-Schließen

Verlangen Sie drei grüne RPC-Sonden aus zwei Netzen plus einen erfolgreichen UI-Klick, bevor das Ticket geschlossen wird.

Immutable Infrastructure für Gateway-Hosts

Wenn Sie Ansible oder ähnliche Werkzeuge nutzen, codieren Sie den erwarteten absoluten Pfad zu openclaw als Idempotenz-Check. Jede Abweichung soll den Playbook-Lauf stoppen, statt still einen zweiten Symlink anzulegen. Das verhindert schleichende Divergenz zwischen dokumentiertem Soll und tatsächlichem Ist-Zustand auf langjährig gemanagten Macs.

Lesbarkeit von Alarmen im Incident-Channel

Benennen Sie Alarme so, dass sie den Unterschied zwischen PATH-Skew, fehlgeschlagenem install --force und echtem RPC-Ausfall sofort erkennen lassen. Generische Texte wie Gateway unhealthy zwingen Engineers, jedes Mal von vorn zu debuggen und verlängern mittlere Reparaturzeiten messbar, besonders wenn mehrere Zeitzonen beteiligt sind.

Weiterführend

Remote-URL-Themen: Remote-Matrix. Pairing: Runbook. Installation: Install.

Laptops, Schlafmodus und mehrfache Paketmanager vergrößern die Varianz; ein dauerhaft online gemieteter Remote-Mac mit einem überwachten Gateway senkt häufig die Gesamtkosten, wenn Sie 7x24-Stabilität neben Datei-Workflows brauchen. Messbare Observability für PATH-Skew ist dabei genauso wichtig wie niedrige Hardware-Latenzen.