2026_OPENCLAW
UPGRADE_
BREAKING_
DOCTOR_AUTH_V2.

1. Pourquoi le binaire ne suffit pas

(1) Racine d’état qui dérive : anciens dépôts utilisaient ~/.moltbot ou CLAWDBOT_*/MOLTBOT_* ; les lignes actuelles attendent ~/.openclaw et des OPENCLAW_* canoniques. Mettre à jour le paquet sans migrer les données produit une double vérité.

(2) Limites de doctor --fix : il répare les dérives courantes, pas les jetons de canaux expirés, les chemins reverse-proxy ni les montages skills exotiques — lisez le diff avant d’appliquer.

(3) Auth appareil v2 : la signature nonce élève le plancher client ; des CLI obsolètes semblent « connectées » mais n’entrent pas dans le workflow. launchd sans le même environnement que le shell interactif amplifie « ça marche en local, pas sur le serveur ».

2. Matrice

3. Cinq étapes

1. Snapshot état, workspace, plist, version.
2. doctor sans --fix.
3. Tester --fix sur copie.
4. grep des préfixes obsolètes.
5. Fumée canaux + skill minimal ; rollback si besoin.

4. Seuils

5. RGPD & secrets

Documentez quels secrets atterrissent dans plist/units et qui peut les lire. Un Mac de staging avec les mêmes clés avant prod limite les messages de test personnels dans de vrais canaux.

5.1 Matrice launchd distante

6. FAQ

--fix touche le workspace ? Peut réécrire des pointeurs — snapshot d’abord.

Docker ? Une seule source de vérité entre bind host et conteneur ; double édition crée des courses pendant doctor --fix.

Revenir v1 ? Lab isolé avec date de fin ; en prod, montez les clients.

Supprimer ~/.moltbot tout de suite ? Après parité des secrets et canaux valides ; gardez le tarball un cycle.

Doctor vert mais canal muet ? Logs de livraison webhook et en-têtes côté SaaS — doctor ne voit pas la dérive amont.

7. Cas : Slack après deux mineurs

plist pointait encore vers un binaire ancien, jetons seulement dans .zshrc, en-tête Slack incompatible avec la signature par défaut. Réparer couche par couche a flaké ; diff d’environnement à zéro + re-pair a stabilisé.

Archiver sorties doctor et diffs plist par upgrade réduit les incidents répétés et rassure l’audit.

Joindre le shasum du binaire résolu ; rollback remet paquet et chemin plist. Sur hôte multi-utilisateur, UserName du daemon doit correspondre au compte qui détient les clés.

Homebrew + npm global imposent un gagnant PATH sinon doctor répare A pendant que launchd lance B.

Un Mac de staging qui reflète les plist prod réduit les renvois utilisateurs ; journalisez quels canaux y sont autorisés pour éviter des webhooks fantômes.

Les analyses d’impact RGPD doivent noter si les logs skills stockent des données personnelles issues des chats — un upgrade qui étend les logs peut changer la base légale même si le modèle est identique.

La rotation des secrets doit être découplée des calendriers majeurs OpenClaw ; sinon certificats TLS et bumps majeurs tombent la même nuit et le gateway semble « cassé » pour un simple empreinte manquante.

Surveillez les descripteurs de fichiers après upgrade : certains mineurs changent les limites de connexions webhook simultanées ; une montée d’EMFILE est plus rapide à diagnostiquer avec une baseline.

Les bots ChatOps internes doivent suivre la même chaîne d’auth que la prod ; un bot admin sur vieux build masque les problèmes v2 jusqu’à la démo live.

Avec l’IaC, sortez plist/unit du même commit que digest conteneur et entrées npm-lock ; trois SHAs différents sur un ticket annoncent la dérive nocturne.

Formez le support à distinguer « processus vivant » et « workflow qui consomme les événements » — healthchecks process-only mentent vert pendant que la file stagne.

Pausez les sauvegardes qui figent le dossier d’état pendant l’upgrade ou déplacez-les après la fenêtre ; des tarballs à moitié écrits rendent les restaurations impossibles.

Tenez une liste de commandes shell interdites en prod car absentes du runbook ; chaque hotfix non documenté devient incident suivant.

Multi-régions : répétez les sondes avec les mêmes scripts malgré DNS différents pour ne pas confondre latence réseau et régression d’auth.

Capturez des captures d’écran de configuration Slack avec les fichiers doctor ; la dérive UI SaaS est pénible à diff mais les paires avant/après sauvent des heures.

8. Observabilité pendant la fenêtre

Codes de sortie, taux de succès des sondes, médiane du cold-start skill, erreurs auth/h — les quatre en baisse : racine/env ; auth seul : matrice clients.

Corrélez avec user-agents si les logs les exposent ; un vieux build mobile peut dominer les erreurs.

8.1 CI, staging, « latest »

CI avec npm i -g openclaw@latest ne prouve rien : Node du runner, PATH du shell, métadonnées digest manquantes. Épinglez version ou digest, enregistrez chemin absolu + shasum dans l’artefact, citez-les dans le ticket.

Staging ne partage pas le même Slack sans bots/canaux séparés. Clonez plist, changez secrets/ports, rejouez smokes complets. Un bloc EnvironmentVariables supplémentaire seulement en staging signale dérive prod — remontez la structure, ne « corrigez » pas le staging dans le vide.

Pendant gel : interdisez deux interprétations de OPENCLAW_CONFIG_ROOT. Une surface autoritaire, diff -u joint.

Les scripts de santé qui appellent openclaw suivent la génération CLI sinon faux critiques et tempêtes de restart.

Répétez le rollback avec snapshot, ancien digest, sondes — sans sortie doctor, rollback incomplet.

Les outils CM rendent parfois templates login et daemon avec minutes d’écart — commentez la révision plist pour corréler Git.

Les scanners de secrets doivent couvrir shell et plist ; les clés migrent silencieusement pendant les fix de dérive.

Avec Zero Trust terminal, vérifiez que shell interactif et daemon voient le même contexte certificat appareil sinon v2 échoue par intermittence.

Les jobs batch qui supposent d’anciennes sous-commandes vont dans la même liste de dépréciation que l’API publique.

Stockez la version Node de l’agent qui a fait les installs globales — elle influence modules natifs et chemins binaires.

Vérifiez post-gel que les dashboards pointent encore vers les bons labels launchd.

Plusieurs gateways : numérotez les dossiers d’état et évitez symlinks croisés sinon doctor « soigne » le mauvais arbre.

Les accès d’urgence prod doivent notifier un second ingénieur ; hotfix sans témoin se reproduit mal en post-mortem.

Hyperviseurs ajoutent des sources d’horloge ; comparez offsets NTP si les nonces sont sensibles au temps.

Antivirus temps réel sur le dossier d’état peut ralentir doctor — documentez exceptions avec la sécurité.

Miroir interne des release notes si l’amont est indisponible ; sinon décision à l’intuition fatiguée.

Pair-review des plist : fautes XML minuscules, effets massifs.

Notez quelles règles pare-feu webhook ont été ouvertes pour les audits futurs.

9. Windows / Linux : couches multiples

Sans contrat d’état gelé, les gestionnaires de services multiplient les échecs. Les Mac Apple Silicon distants restent proches des exemples launchd — MACGPU loue des nœuds à faible friction, CTA sans login.

WSL, snap, chemins Node distro : la même clé OPENCLAW_* peut apparaître trois fois avant alignement daemon/CLI/skill.

Après v2, tempêtes de reconnexion courtes saturent petits CPU VPS — déploiement client échelonné ou hôte plus large temporairement.

Les revues demandent ls -le avant/après si doctor --fix a pu élargir des ACL.

10. Chaînes d’install & Docker prod

npm global, Compose, pnpm source ont des racines différentes. Le digest Compose fait partie du contrat ; bump npm hôte ne bouge pas le binaire conteneur.

Bind ~/.openclaw + édition hôte : sérialisez ou copie staging pour éviter courses sur fix.

CI qui shell-out openclaw : épinglez AMI avec minor serveur sinon prod verte, nightly rouge.

Carte d’upgrade : chemin binaire, label plist, racine données, liste canaux — première pièce jointe incident.

Vérifiez que le miroir d’artefacts interne pointe toujours vers le même upstream — changement silencieux de miroir, hashes nouveaux sans bump semver.

Documentez qui signe quels binaires quand brew et npm coexistent — chaîne d’approvisionnement compte autant que la version.

Sessions WebSocket longues peuvent survivre à un upgrade tout en signant v1 alors que les nouveaux événements attendent v2 — forcez reconnect contrôlé après major.

Bibliothèque de payloads webhook anonymisés pour régressions sans spam utilisateur.

11. Semaine zéro après doctor vert

J0 second tarball après trafic réel, diff. J1 sondes compte daemon et admin. J2 skill le plus lent froid + retries. J3 cluster erreurs auth par build, fenêtre d’upgrade forcée si besoin. J4 restauration alignée sur label plist actuel. J5 rétro 15 minutes, ligne sur la carte.

Déploiements échelonnés avec au moins un cycle jour entre étapes ; gels marketing et vacances on-call priment sur la date npm.

Rotation des exécutants de checklist et versionnement Git à côté du code infra ; alias personnels faussent les smokes.

Si timeouts sporadiques, mesurez DNS/TLS séparément du processus gateway.

Petit journal wiki trois puces par release évite la connaissance en DM.

Surveillez taille du dossier d’état — croissance inattendue signale logs debug ou nettoyage manquant.

Ne oubliez pas clients mobile : modèle de fumée séparé.

Pour FinOps, montrez heures incident évitées, pas seulement bannière de version.

Exercice trimestriel de rollback volontairement raté pour apprendre sans panique.

Listez alertes mises en sourdine pendant l’upgrade — sinon sourdine éternelle.

Alignez certs reverse-proxy et bumps quand possible pour éviter doubles nuits blanches.

Notez fuseau des logs sur le ticket ; équipes globales évitent fausses pistes.

Les équipes créatives doivent cosigner la définition des lanes avec la plateforme, sinon les deadlines de rendu écrasent toujours les fenêtres réservées aux embeddings et la lane interactive paie sans bruit.

Prévoyez chaque mois une revue conjointe digest modèle et version proxy même sans release applicative — la stabilité perçue dépend souvent de ces couches oubliées.

Les mises à jour fantômes via Homebrew ou npm global sans ticket associé sont exactement ce que la checklist hebdomadaire doit attraper.

Quand plusieurs fournisseurs DNS coexistent, documentez TTL et dates de rotation ; un basculement réseau imite une régression modèle si la chronologie manque.

Les post-mortems courts avec propriétaire trimestriel valent mieux que des PDF de vingt pages jamais relus.

Si un incident « s’est résolu tout seul », capturez ce qui a changé dans l’environnement ce jour-là : navigateur, MDM, sauvegarde nocturne.

Comparez post-mortems entre équipes : symptômes identiques sur laptops différents pointent souvent vers un proxy corporate commun.

Pour nœuds distants, ajoutez température rack et fenêtres maintenance datacenter aux rapports — explique des creux rares non reproductibles en local.

Ne mélangez pas dans un même ticket changement de modèle et changement de route réseau ; le rollback devient une loterie.

Liens vers CSV sources nommés dans le ticket plutôt que « archive.zip » anonyme — la recherche post-incident s’accélère.

Formez les nouveaux sur un post-mortem réel la première semaine : plus efficace qu’un cours abstrait sur les signatures.

Sans tâche backlog datée, la rétro est du bruit — assignez toujours un propriétaire et une échéance.

Relisez semestriellement d’anciens post-mortems : les motifs se répètent tant que les lanes ne sont pas écrites noir sur blanc.

Remerciez publiquement les équipes pour analyses honnêtes sans chasse aux coupables, sinon le prochain incident part en messages privés et les métriques disparaissent.

Ajoutez au template le champ « ce que nous n’avons pas mesuré » — il révèle les trous de culture observabilité mieux que la liste des succès.

Si plusieurs Mac distants sont loués, comparez leurs échelles mensuellement : la dérive de configuration entre nœuds reste invisible jusqu’à bascule de charge.

La fin de trimestre augmente souvent les tâches de fond sur postes de travail et peut déplacer la p99 sans toucher au stack ML — notez-le clairement au calendrier partagé.

12. Synthèse

Les Mac Apple Silicon distants alignent mieux launchd et docs. MACGPU propose des nœuds loués pour répéter les upgrades — CTA sans login. Upgrades sans snapshots ni journaux doctor restent vraiment incomplets.

Une fois la discipline en place, les mineurs suivants coûtent nettement moins cher grâce aux artefacts et seuils déjà posés, pas grâce à une magie release.

Consignez chaque succès comme motif réutilisable dans une bibliothèque interne plutôt que simple message de chat.

Cela réduit fortement l’onboarding et la dépendance aux héros du dernier incident — beaucoup plus durable qu’un simple drame ponctuel sans apprentissage structuré.