2026 OpenClaw v2026.5.3–5.7 micro-versions Runbook : config invalide fail-closed, doctor --fix, plugins npm, launchd, Gateway distant

Après une chaîne OpenClaw v2026.5.3–5.7 en mai 2026, le Gateway peut quitter immédiatement sur configuration invalide (fail-closed) alors que la CLI semble saine. Causes fréquentes : validation de schéma plus stricte, chargement npm des plugins durci, dérive entre variables LaunchAgent et shell interactif. Cet article détaille les irritants, une matrice de décision, un runbook en cinq étapes, une étude de cas, une lecture production, des seuils chiffrés et une FAQ, avec des liens vers faux upgrade et alignement PID, passerelle manquante et npm, ops v2026.5.x canaux/TTS. Joignez un triplet de preuves au ticket et répétez les mêmes étapes sur un hôte Gateway Apple Silicon distant si besoin.

1. Irritants : fail-closed, changement de sémantique d’exploitation

Les builds récents refusent plus tôt les JSON partiellement invalides pour éviter des sessions semi-initialisées. Les arbres npm cassés échouent souvent au chargement runtime. macOS ne synchronise pas automatiquement les variables LaunchAgent avec zshrc. Si doctor --fix déplace des répertoires d’état mais le plist pointe encore vers un ancien workspace, on obtient CLI verte, démon rouge. Sur un Mac distant 7×7, les boucles de redémarrage effacent l’histoire : figez d’abord la surface d’écriture et capturez des extraits de logs. Contrairement au faux upgrade (binaire ancien), priorisez ici chemins JSON et messages de schéma.

2. Matrice de décision

Signal	Action principale	Secours
invalid/schema/fail-closed, sortie immédiate	Sauvegarde, doctor --fix, diff openclaw.json	Stopper la boucle, conserver 200 lignes
échec plugin uniquement	Réinstallation npm de l’ID plugin	Boot avec ensemble minimal
shell ok, launchd KO	Comparer PATH/NODE du plist avec which	unload/load ou kick
audit exige fenêtre reproductible	Deuxième Mac distant pour répétition	Snapshot lecture seule puis canari

3. Runbook en cinq étapes

Step 1 Geler la surface d’écriture

Noter version, port Gateway, label LaunchAgent ; joindre openclaw status, openclaw gateway status et un extrait de log.

Step 2 Classer les logs

Séparer refus de configuration et refus de plugin. Si un chemin JSON est nommé, corriger partiellement.

Step 3 Ordre doctor --fix

Arrêter Gateway avant migrations ; snapshot tar obligatoire. doctor est un migrateur avec effets de bord.

Step 4 Réparation npm

Réinstaller l’ID cité ; aligner npm prefix -g sur l’environnement du processus supervisé. Fenêtre de stabilité 30 minutes avec jeu minimal.

Step 5 Redémarrage launchd à froid

Après plist, unload/load ; trois contrôles de santé consécutifs et channels.probe sans rouge.

tail -n 200 ~/.openclaw/logs/gateway.log 2>/dev/null || openclaw logs --since 30m
for i in 1 2 3; do openclaw gateway status || exit 1; sleep 5; done
                

4. Trois garde-fous

Pas de « production rétablie » tant que doctor liste des points ouverts. Pas de retour plugins complet sans fenêtre 30 minutes en configuration minimale. PATH/NODE/OPENCLAW_GATEWAY_TOKEN plist vs shell sans écart.

5. Étude de cas

« Mac mini distant : trois micro-mises à jour en une semaine, Gateway quitte en boucle ; le portable démarre avec le même openclaw.json—le plist pointe encore vers l’ancien workspace. »

Correctif : gel, diff plist/JSON, reload launchd à froid, fenêtre 30 minutes plugins minimaux. Leçon : traiter plist et shell comme deux interfaces OS distinctes. Chaque ticket d’upgrade doit contenir version, sortie doctor, diff plist, extrait de log.

Le portable interactif suffit pour itérer seul ; pour chaînes micro et fail-closed, louez un MACGPU Mac distant comme hôte de répétition pour comparer les journaux et stabiliser un Gateway Apple Silicon dédié aux workflows créatifs exigeants.

6. Lecture production

Les correctifs sécurité courts impliquent des micro-migrations hebdomadaires. Un nœud unique fait entrer en collision doctor et pics métier ; un second hôte distant en basse charge réduit le risque documentaire, utile pour les studios qui doivent tracer résidence données et fenêtres de changement.

7. Seuils chiffrés

Stabilité plugins minimaux ≥30 min. Santé 3/3. Extrait log par défaut 200 lignes ou 30 minutes. Plus de deux correctifs doctor non revus la même nuit sur le même hôte déclenchent un gel de changement.

8. FAQ

Downgrade sans doctor ? Peut soulager mais laisser des migrations partielles. Erreur plist à distance ? Diff sur clone d’abord.