2026 OpenClaw openclaw update après upgrade : passerelle arrêtée, canaux vides, modèle 401 — update status, Update restart en attente et plugin load failed matrice de décision

Vous lancez openclaw update, npm affiche succès, et quelques minutes plus tard la passerelle refuse de démarrer, la liste des canaux est vide ou chaque appel modèle renvoie 401. La section officielle After an update prescrit update status, la surveillance du handoff Update restart, puis gateway status --deep, doctor --fix et gateway restart. Ce guide transforme cette échelle en matrice de décision pour la première heure — incluant plugin load failed: dependency tree corrupted, les ombres OAuth et le correctif v2026.5.20 qui empêche les hôtes multi-Node de basculer silencieusement le binaire Node de la passerelle.

1. Triage en quatre couches : ne confondez pas toutes les pannes post-upgrade

Les équipes créatives et techniques qui déploient OpenClaw sur MacBook ou VPS perdent parfois une après-midi à relancer launchd alors que la cause se situe une couche au-dessus ou en dessous du démon. Traitez les couches dans l'ordre ; sauter une étape produit des preuves contradictoires et des edits de config parallèles.

1. L0 paquet et handoff : l'installateur réussit, mais openclaw status --all affiche Update restart pending ou failed. Le problème est le handoff de mise à jour, pas le pare-feu Telegram.
2. L1 processus passerelle : Runtime: stopped, conflit de port ou dérive CLI/service. Commencez par le redémarrage passerelle macOS ou le guide systemd HOME drift Linux.
3. L2 plugins de canaux : le processus tourne mais channels status --probe est vide ou affiche plugin load failed. Section 6. Si la sonde est verte sans réponse : canal en ligne, sonde verte, sans réponse.
4. L3 identifiants modèle : canaux sains, chat en 401/403. doctor --fix et le guide credentials onboard. Binaire ancien refusant d'écrire le service : split brain.

Pour les incidents quotidiens hors fenêtre de upgrade, gardez l'échelle de dépannage officielle. Cet article se concentre sur la soixantaine de minutes qui suit openclaw update — moment critique pour les studios qui enchaînent livraisons client et agents IA sur le même parc.

Les scripts de mise à jour résolvent l'installation semver ; la production exige le handoff — recycle du service, reconstruction du registre plugins, nettoyage des ombres credentials, alignement du chemin Node. Les confondre explique des listes de canaux vides et des 401 intermittents traités comme des bugs sans lien.

Pour les studios qui monétisent des agents sur Mac mini partagés, la discipline compte : une preuve par couche avant d'ouvrir la suivante réduit le MTTR et alimente des post-mortems exploitables — semver actif, statut handoff, sortie doctor sur l'arbre plugins. Les équipes qui gravent cette séquence dans le runbook évitent les doubles rotations de clés après un seul upgrade.

2. Trois points de friction fréquents (numérotés)

Friction un : canaux vides pris pour une panne réseau. Après upgrade, la section Channels peut encore lister des messagers configurés, mais les instances ne s'enregistrent pas car le démarrage a loggé plugin load failed: dependency tree corrupted; run openclaw doctor --fix. Ajuster nginx ou Tailscale ne répare pas un arbre de dépendances plugins corrompu avant l'instanciation des canaux.

Friction deux : éditer la config pendant Update restart pending. Handoff incomplet : hot reload ignoré, Invalid config, ou unité de service pointant vers un état partiellement écrit. Exécutez d'abord la commande suggérée dans status --all.

Friction trois : faire tourner toutes les clés API au premier 401. La doc officielle rappelle que re-OAuth sur le profil partagé n'invalide pas automatiquement les ombres OAuth auth per-agent obsolètes. doctor --fix supprime les copies périmées — plus sûr qu'une rotation massive qui casse staging et CI.

Friction secondaire : lancer un second openclaw update pendant un handoff rouge empile des installations partielles. Gelez les changements parallèles jusqu'à ce que l'échelle de la section 4 soit verte.

3. Matrice symptôme → première preuve (citable)

Collez la ligne active dans le ticket incident avant que des répondeurs parallèles divergent. La matrice privilégie une commande de preuve à une réinstallation spéculative.

4. Échelle officielle post-mise à jour (How-to, cible quinze minutes)

1. Geler les edits parallèles : pas de nginx, pas de rotation jetons Telegram, pas de réinstall plugins optionnels pendant la fenêtre.
2. Statut complet : openclaw status --all ; capture de la ligne Update restart.
3. JSON update : openclaw update status --json ; sauver pending/failed, canal stable/beta, commande suivante.
4. Passerelle profonde : openclaw gateway status --deep ; Runtime, Config (cli) vs Config (service), port, version Gateway.
5. Réparation auto : openclaw doctor --fix pour arbres plugins, ombres OAuth, ports service obsolètes.
6. Redémarrage contrôlé : openclaw gateway restart ; si échec, openclaw gateway install --force puis restart.
7. Acceptation canaux : openclaw channels status --probe jusqu'à works / audit ok.

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart
openclaw channels status --probe

Observation continue : second terminal openclaw logs --follow. Rédiger les tokens avant pièce jointe — voir la checklist journalisation production.

Horodatez chaque étape. Sur un Mac distant dédié always-on, le handoff se cleared souvent en moins de cinq minutes ; un MacBook qui dort dépasse vingt minutes et fausse le diagnostic split brain — fréquent dans les petits studios sans hôte passerelle permanent.

5. Update restart pending et handoffs échoués

Update restart apparaît sur openclaw status et status --all. Pending : handoff n'a pas fini de recycler le processus supervisé. Failed inclut la prochaine commande — souvent gateway restart manquant, unité service avec ancien chemin Node, ou bootout launchd incomplet.

Handoff échoué : ne relancez pas immédiatement openclaw update. Lisez update status --json pour canal, tag cible et bloqueur. Production : pin stable et semver de rollback dans le ticket. Beta autour de v2026.5.19-beta a signalé des boucles respawn silencieuses.

Si gateway status --deep montre une santé WebSocket stable plus de dix secondes mais canaux vides, vérifiez la taille des fichiers session — le guide v2026.4.26 chat.history décrit des blocages qui imitent un restart raté.

Sous Linux, corrélez journalctl avec update status --json. Schéma fréquent : upgrade sous utilisateur admin, systemd lance la passerelle sous compte service dont HOME a dérivé.

6. plugin load failed: dependency tree corrupted

Les entrées canaux existent en config, mais l'enregistrement plugin échoue avant construction des instances. Réparation supportée : openclaw doctor --fix, pas suppression aveugle de node_modules.

Repro minimale : commentez les entrées non essentielles de plugins.entries, gardez un messager plus provider cœur, restart, probe. Réactivez un par un pour isoler un paquet ou une dérive globale du arbre modules Node chargé par le service.

Distinguez échec au démarrage et fuites MCP runtime. Les erreurs dependency tree apparaissent dans les premières secondes ; mémoire qui monte après des heures → autres runbooks.

7. Provider 401 et ombres OAuth après upgrade

Sous-ensemble d'agents en 401, agent principal ok → ombres OAuth. Re-auth sur profil partagé n'invalide pas garanti les shadows per-agent. doctor --fix supprime les copies obsolètes.

Tous les modèles en 401 : ~/.openclaw/credentials/ vide ? EnvironmentFile systemd ou env launchd injecte les secrets avant démarrage ? Les réécritures d'unités après upgrade exposent des bugs d'ordre masqués en terminal interactif.

Cloudflare AI Gateway + Anthropic (2026.5.6–5.7) : régression sur en-têtes dual-auth. Après upgrade, vérifiez le forwarding plutôt qu'une rotation de clé unique.

Croisez avec le guide onboard : variables d'environnement, profils fichier, switching provider — après recycle service, la sonde peut être verte alors que le chat résout une autre route.

8. Multi-Node et v2026.5.20

v2026.5.20 corrige le basculement silencieux du Node passerelle quand plusieurs installations Node coexistent et que openclaw update s'exécute. Le chemin Node reste une décision d'infrastructure explicite :

• Chemin Node absolu dans ProgramArguments launchd ou ExecStart systemd.
• Avant/après upgrade : which openclaw, openclaw --version, version Gateway dans gateway status --deep.
• CLI et service divergent : gateway install --force puis restart.

Upgrades Node Homebrew sur macOS et bascules nvm sur Linux restent les déclencheurs majeurs de CLI neuf, démon ancien — même après le garde-fou v2026.5.20. Documentez les digests attendus dans votre runbook studio.

9. Métriques pour post-mortems

• Durée handoff : minutes jusqu'à Update restart cleared (cible < 5 sur hôte dédié).
• Temps probe : secondes jusqu'à channels probe tout vert (cible < 120).
• Fenêtre rollback : artefact tag stable précédent conservé 72 h minimum.
• Churn config : lignes diff non générées par fenêtre (cible < 50).
• Récupération 401 : minutes jusqu'au chat agent après doctor --fix si shadows (cible < 10).

Exportez ces cinq chiffres dans votre modèle de change. Si la durée handoff grimpe trimestre après trimestre, auditez les politiques de veille sur MacBook passerelle et envisagez un Mac distant always-on — meilleure continuité pour pipelines créatifs et agents IA 24/7.

10. FAQ

Q : Sauter update status et restart tout de suite ? Déconseillé. Restart avec handoff incomplet boucle souvent ; status montre le chemin plus court.

Q : doctor --fix réécrit openclaw.json ? Peut réparer préfixe, ports, arbres plugins. Snapshot avant releases majeures. Invalid → .rejected.*.

Q : Lien avec split brain ? Split brain : vieux binaire n'écrit pas la nouvelle config. Ici : nouveau binaire, handoff/plugins/credentials pas alignés. Les deux peuvent s'enchaîner.

11. Conclusion : update installe le semver ; le handoff restaure la production

openclaw update avance le semver. La disponibilité dépend du handoff Update restart terminé, d'arbres plugins cohérents, d'unités service liées au bon Node et d'ombres OAuth alignées sur le profil partagé fraîchement ré-autorisé. MacBook en veille, WSL hiberné, VPS sous-dimensionnés et postes partagés studio/dev gonflent les échecs de handoff — canaux vides et 401 intermittents pendant des heures de debug messagerie.

Ancrer la passerelle sur un Mac distant macOS always-on avec chemins Node explicites dans launchd, plus snapshots SFTP/rsync de ~/.openclaw, rend l'échelle de quinze minutes répétable et auditable. SFTPMAC location Mac distant s'adresse aux équipes OpenClaw et CI/CD sur Apple Silicon qui restent en ligne pendant les fenêtres de upgrade — en lien avec notre échelle officielle, recovery split brain, redémarrage passerelle et journalisation production. Louer un Mac dédié surpasse généralement l'hébergement passerelle sur une machine qui dort, met à jour Node au gré du vent ou manque de discipline snapshot — surtout quand la compatibilité écosystème Apple et la stabilité 24/7 alimentent vos workflows créatifs et vos agents.