2026 OPENCLAW
FALLBACK_
CONFIG_
DRIFT.
Primaire + secours protège la disponibilité jusqu’à ce qu’un fallback réussisse et réécrive openclaw.json, figeant le secours comme primaire déclaré. Ce guide sépare dérive disque / dérive session / parsing fournisseur, propose cinq étapes (arrêt Gateway → sauvegarde trio → restaurer l’intention → purge mappings → redémarrage échelonné) et rappels launchd pour Mac distant. Liens : 429 failover, sessions, token LaunchAgent.
1. Douleurs
Persistance runtime non gardée, IDs qualifiés divergents, sessions.json obsolète, SSH ≠ plist.
Le piège : les métriques de dispo restent vertes. Les webhooks répondent 200, les canaux livrent — mais étiquettes conformité ou ventilation coûts dérivent discrètement. Sans hash agents.list[].model au tableau de bord, on croit vite à un « fournisseur instable » et les correctifs durables glissent. Multi-fuseaux, un correctif jq de nuit peut redevenir une autre version au matin : double vérité.
Ce runbook traite donc trio sauvegarde, diff structuré, purge mappings et redémarrage échelonné comme un seul geste. Plus le fallback est quotidien, plus « écriture autorisée ? » doit passer revue de code et feature flags.
2. Matrice
| Signal | Cause | Éviter |
|---|---|---|
| Primaire renommé secours | écriture fallback | revert sans purge sessions |
| Un canal faux | session runtime provider | réinstall aveugle |
| doctor incohérent | JSON vs session | npm en boucle |
| Remote seulement | env plist vieux | plist partielle |
3. Cinq étapes
Step 1 Arrêt Gateway
systemd/launchctl, fermer WS.
Step 2 Sauvegarde trio
openclaw.json, sessions.json, jsonl.
Step 3 Restaurer intention
agents.list[].model, defaults.primary, fallbacks.
Step 4 Purger mappings
Supprimer clés non approuvées, journaliser.
Step 5 Redémarrage
doctor→Gateway→3 sondes.
4. Décisions
| Déclencheur | Priorité | Secours |
|---|---|---|
| Vivant mais mauvais modèle | allowlist + JSON | wipe sessions |
| Plusieurs personas | gel par persona | override global |
| launchd vieux env | WorkingDirectory | export ad hoc |
5. Note terrain et angle audit
« Sauvé la nuit — deux semaines après audit : primaires miniatures. »
Le failover multi-fournisseur a sauvé la dispo, mais la session runtime a réécrit agents.list[0].model vers un petit modèle ; après retour du primaire, le résolveur est resté bloqué sur « dernier modèle réussi ». Sauvegarde→réparation JSON→purge mappings sessions→redémarrage Gateway ; gabarit MR avec interdiction de persistance silencieuse issue du fallback — tickets similaires à zéro.
L’audit a classé la gravité en intégrité de configuration (pas panne canal, risque étiquette/contrat). Depuis, hash quotidien du bloc models dans le reporting interne ; diff sans numéro de CR → revue secondaire auto.
6. Gouvernance et observabilité
Traiter les diffs JSON comme du Terraform : même circuit d’approbation. Chaque tour réussi journalise le modèle qualifié (namespace) en structuré ; le SIEM alerte si agents.list change sans CR. Le seul texte libre bloque l’analyse post-mortem trois semaines plus tard.
launchd sur Mac distant stabilise thermique et alimentation, mais un export SSH ressemble à la vérité. Garde : « env imprimée launchctl → chemin openclaw doctor → message minimal avec empreinte modèle ». Gateway tourne aussi sous Windows/Linux ; pour réutiliser scripts macOS, héberger les templates sur un nœud MACGPU Apple Silicon clarifie les périmètres.
7. Garde-fous fournisseur et chemins restreints
Alias nus dans agents.list[].model s’attachent implicitement au fournisseur par défaut. Dès qu’une session réussit une fois en vendor/model, le tour suivant peut router même nom, autre chemin. CI + jq pour imposer provider+model dans les templates.
Telegram, Web UI, Cron cohabitent : vérifier en matrice que les overrides persona ne pointent pas vers d’anciens pointeurs session. « Un seul canal correct » = quasi toujours scission de sessions. plist à jour mais env processus vieille ? Pas finir en SSH seul — inclure launchctl bootstrap ou reload LaunchAgent.
8. Seuils (à coller au ticket de changement)
① Au moins trois rondes de sondes avant/après réparation + empreinte logs. ② Lors d’un bascule fournisseur : horodatage et statut HTTP dans le ticket. ③ Plus de deux incohérences disque vs intention par semaine : geler la topo fallback jusqu’audit code. ④ Toute opération sur le dossier sessions : backup sha256.
FinOps : comparer coût tokens par créneau avant/après avec taux d’erreur d’étiquettes (logs structurés) — utile pour expliquer au management les effets secondaires d’une persistance de fallback.
9. FAQ
sessions seules ? JSON peut rester faux.Docker ? aligner HOME volume et conteneur.Mise à jour d’abord ? réparer et mappings d’abord.plusieurs éditeurs ? verrou ou fenêtre de change ; conflits → blocs d’intention Git.désactiver fallback ? plutôt réduire l’ensemble de modèles autorisés.canari ? séparer personas, dupliquer blocs agents.list, CR distincts.