2026 OPENCLAW
FALLBACK_
CONFIG_
DRIFT.
Primary + Fallback schützt die Verfügbarkeit — bis ein erfolgreiches Fallback still in openclaw.json zurückschreibt und der deklarierte Primary nie zurückkehrt. Dieser Leitfaden trennt Platten- vs Session-Drift vs Provider-Parsing, beschreibt fünf Schritte (Gateway stoppen → Trio-Backup → Intent-Felder → Mapping prune → gestaffelter Neustart) und launchd-Hinweise für Remote-Macs. Querverweise: 429-Failover, Session-Recovery, LaunchAgent-Token.
1. Schmerzpunkte
Laufzeitwahl persistiert in agents, Provider-Pfade divergieren, sessions.json hält alte Routen, SSH und launchd unterscheiden sich.
Besonders unangenehm: Verfügbarkeitsmetriken bleiben grün. Webhooks liefern 200, Kanäle liefern aus — aber Compliance-Labels oder Kostenaufteilung driften leise. Ohne agents.list[].model-Hash im Dashboard wird die Ursache schnell als „instabiler Provider“ fehlinterpretiert, und dauerhafte Fixes rutschen nach hinten. Über Zeitzonen hinweg kann ein nächtlicher jq-Fix durch den Frühlaunchd zu einer doppelten Wahrheit werden.
Deshalb behandelt dieses Runbook nicht einzelne Befehle, sondern Trio-Backup, strukturierten Diff, Mapping-Prune und gestaffelten Neustart als Paket. Je öfter Fallback zum Alltag wird, desto strenger müssen „Schreiben erlaubt?“ in Code Review und Feature Flags geklärt werden.
2. Symptommatrix
| Signal | Ursache | Vermeiden |
|---|---|---|
| Primary heißt wie Backup | Fallback write-back | Revert ohne Session-Prune |
| Nur ein Kanal falsch | Session hat Runtime-Provider | blinde Neuinstallation |
| doctor mismatch | JSON vs Session | endlose npm-Upgrades |
| nur Remote | plist env alt | halbe plist |
3. Fünf Reparatur-Schritte
Step 1 Gateway stoppen
systemd/launchctl, WebSockets schließen.
Step 2 Trio-Backup
openclaw.json, sessions.json, jsonl-Fingerprints.
Step 3 Intent wiederherstellen
agents.list[].model, defaults.primary, fallbacks; nie Modell ohne Provider ändern.
Step 4 Mapping prune
Unbillige Runtime-Keys löschen und protokollieren.
Step 5 Gestaffelter Neustart
openclaw doctor→Gateway→drei Probenrunden.
4. Entscheidungsmatrix
| Auslöser | Primär | Sekundär |
|---|---|---|
| Live aber falsches Modell | Allowlist + JSON-Fix | Session wipe |
| Mehrere Personas | einfrieren pro Persona | globales Override |
| launchd alte env | WorkingDirectory prüfen | adhoc export |
5. Feldnotiz und Audit-Linse
„Die Nacht gerettet — zwei Wochen später Audit: Primaries klein geblieben.“
Multi-Provider-Failover hielt die Verfügbarkeit, doch die Session-Laufzeit überschrieb agents.list[0].model mit einem kleineren Modell; nach Primär-Recovery blieb die Resolver-Logik auf „zuletzt erfolgreiches Modell“ kleben. Backup→JSON-Reparatur→Sessions-Mapping-Prune→Gateway-Neustart, MR-Template mit verbotener stiller Fallback-Persistenz — danach gingen gleichartige Tickets auf null.
Im Audit wurde die Schwere als Konfigurationsintegrität eingestuft (nicht Kanal-Ausfall, sondern Label- und Vertragsrisiko). Seitdem fließt ein täglicher Hash des models-Blocks ins interne Reporting; Diffs ohne CR-Nummer landen automatisch in zweiter Review. Strukturierte Logs bleiben DSGVO-konform, ohne PII zu überfrachten.
6. Governance und Observability
JSON-Diffs gehören in denselben Genehmigungsfluss wie Terraform-Änderungen. Jede erfolgreiche Runde loggt das qualified model (mit Namespace) strukturiert; im SIEM löst eine Änderung von agents.list ohne CR Pflichtalarm aus. Nur Freitext stoppt die Ursachenanalyse drei Wochen später.
launchd auf Remote-Macs stabilisiert Thermik und Strom, aber SSH-exportierte Umgebungen wirken wie die Wahrheit. Für Bereitschaft: „launchctl gedruckte Env → openclaw doctor-Pfad → Minimalnachricht mit Modell-Fingerprint“ fest verdrahten. Gateway läuft auch unter Windows/Linux; wer macOS-Skripte wiederverwenden will, kann Vorlagen auf einem MACGPU Apple-Silicon-Knoten isolieren — klare Ownership.
7. Provider- und Pfad-Gates
Nackte Aliase in agents.list[].model binden still an den Default-Provider. Sobald eine Session einmal vendor/model erfolgreich nutzt, entsteht im nächsten Turn gleicher Name, anderer Pfad. CI-jq erzwingt provider+model in Templates.
Telegram, Web UI und Cron parallel: Persona-Overrides gegen alte Session-Zeiger matrixprüfen. „Nur ein Kanal korrekt“ ist fast immer Session-Split. plist aktualisiert, Prozessenv alt? Nicht nur per SSH — launchctl bootstrap bzw. LaunchAgent-Reload ins Runbook.
8. Zahlenlimits (für Change-Tickets)
① Mindestens je drei Probenrunden vor/nach Reparatur inkl. Log-Fingerprint. ② Bei Provider-Wechsel Zeitstempel und HTTP-Status ins Ticket. ③ Mehr als zwei Disk-vs.-Intent-Mismatches pro Woche: Fallback-Topologie-Änderungen einfrieren bis Code-Audit. ④ Jede Sessions-Verzeichnis-Operation mit sha256-Backup.
FinOps: Tokenkosten vor/nach Zeitslots tabellieren und mit Label-Fehlerraten aus strukturierten Logs kombinieren — so erklärt sich Nebenwirkungen persistenter Fallbacks auch gegenüber Management.
9. FAQ
nur sessions löschen? nicht wenn JSON krumm.Docker? Volume- und Container-HOME angleichen.Upgrade zuerst? Reparatur und Mapping zuerst.mehrere Editoren? Lock oder Änderungsfenster; bei Konflikt Git-Intent-Blöcke.Fallback abschalten? lieber erlaubte Modellmenge verengen.Canary? Personas splitten, agents.list-Abschnitte duplizieren, CRs trennen.