Après une mise à niveau OpenClaw, quel « type de casse » voyez-vous ? gateway ne démarre pas, les sondes RPC échouent, ou la CLI annonce une version à jour alors que le service utilisateur systemd pointe encore vers un ancien chemin ? Pour l’exploitation : sept hypothèses implicites pour démasquer le split brain (binaires ancien/nouveau), un tableau des symptômes (empreinte de config vs. jeton / URL distante), un runbook sûr en six étapes (PATH → gateway install --force → gateway restart → doctor) et quand ouvrir la vanne des variables d’environnement destructrices. Liens : cron et régression après upgrade, mode distant, observabilité production.
Le dépannage officiel : une OpenClaw plus récente écrit openclaw.json et des marqueurs comme meta.lastTouchedVersion, mais si le vieux binaire openclaw reste résolu dans le PATH, les lectures peuvent encore passer — tandis que pour installer/redémarrer/désinstaller le gateway, la CLI refuse les écritures destructrices afin d’éviter des métadonnées à moitié neuves : en production on appelle ça split brain.
« npm a réussi » équivaut à « le service utilise le nouveau binaire » : npm install -g ne met à jour que le préfixe global ; dans launchd/systemd --user un chemin absolu ancien peut subsister — au prochain reboot c’est la même chose.
Mélanger le PATH du shell de login et celui du service : un which openclaw correct en interactif n’implique pas le même PATH pour le démon.
Ignorer plusieurs sources d’installation : Homebrew, script officiel et npm global peuvent coexister ; l’ordre vient du préfixe du PATH.
Sauter gateway install --force après upgrade : la doc recommande de réécrire l’emballage du service quand il dérive du binaire ; ne lancer le gateway à la main qu’une fois laisse une mine pour le reboot suivant.
Prendre toute erreur doctor pour une config corrompue : souvent c’est un décalage gardien / binaire : aligner les versions avant de retoucher des clés.
Basculer entre mode distant et local sans captures d’écran de config : comme l’article mode distant : openclaw config get gateway.mode d’abord, puis viser le bon hôte pour les sondes.
Après upgrade ne regarder que les canaux et pas la planification : cron et gateway partagent la famille de processus — voir la check-list cron.
« La config se lit » n’équivaut pas à « l’exécution est cohérente ». Le bon réflexe : le tampon ne dit que qui a écrit en dernier ; l’identité du binaire en service doit être vérifiée à part.
Table pour faire passer une garde de « je sens que l’upgrade a cassé » à une branche qu’on peut signer :
| Indice | plutôt split brain | plutôt auth / session | plutôt URL distante / topologie |
|---|---|---|---|
| Mots-clés doctor | parle d’écarts de binaires, bloque une action gateway destructrice | erreurs token / appareil, peu liées à la version du binaire | échec des sondes RPC et gateway status --deep montre un hôte inattendu |
| gateway status | comportement runtime très différent de la CLI --version | runtime vivant mais unauthorized | arrêté localement alors que le distant tourne vraiment |
| Premier geste | aligner PATH → gateway install --force → restart | rotation de jeton ou handshake appareil | vérifier gateway.remote.url et les variables avec l’article mode distant |
Phrase d’or pendant la nuit de mise à niveau : (A) quel binaire tourne ? (B) quel tampon a été écrit par qui ? Une fois les deux alignés seulement on parle canaux et cron.
Avec Tailscale / tunnels privés, ne confondez pas « tunnel OK » et « RPC OK » ; validez les deux extrémités comme dans l’article Tailscale exposition privée.
Sensibilité à l’ordre : si ancien/nouveau divergent, revenir à l’étape précédente au lieu d’éditer config et binaire en parallèle.
Geler la scène : openclaw --version, chemin binaire visible dans l’unité si présent, captures doctor.
Corriger PATH et alias : hors session interactive which openclaw doit pointer vers la release cible ; retirer les alias.
Une seule source de vérité pour l’installation : canal documenté (npm/script) — éviter le mélange chronique brew ancien / npm neuf.
Réinstaller l’emballage du service : pour le même utilisateur, après PATH vérifié, openclaw gateway install --force — rafraîchit launchd/systemd.
Redémarrage à froid du gateway : openclaw gateway restart, puis gateway status et sondes RPC.
Contrôle de régression : openclaw doctor → channels status --probe → toujours inscrit dans cron list ?
openclaw --version command -v openclaw openclaw gateway status openclaw doctor openclaw gateway install --force openclaw gateway restart openclaw channels status --probe
Info : en cas de port occupé, pic mémoire ou ordre compose, lire aussi Gateway not ready et closed(1000) RPC — ne pas prendre une panne ressource pour du split brain.
Le dépannage officiel traite « config neuve + vieux binaire » comme dangereux : un vieux processus qui écrit encore les métadonnées du gateway peut laisser un disque illisible. Les versions récentes peuvent verrouiller les opérations destructrices sur gateway — variables OPENCLAW_* seulement pour un secours ponctuel avec l’ancien binaire (noms et sens selon la doc courante).
Attention : ce n’est pas un passe-partout ; c’est le cas étroit où vous acceptez de risquer l’emballage du service. Par défaut laisser non défini sauf entrée de rollback documentée.
En pratique : réparer PATH → réinstaller le service → upgrade complet avec le nouveau binaire ; le downgrade reste un change ticket séparé avec audit si le fournisseur bloque les paquets.
Points de mesure internes :
openclaw --version en shell interactif et dans l’unité systemd/launchd — identiques après récupération.doctor propre ensuite.Sur laptop partagé ou machine qui dort, le gateway dérive vite. Héberger OpenClaw sur un Mac distant dédié 24/7, SSH stable, disque et réseau contractualisés évite la boucle « upgrade puis à nouveau split ». NodeMini location Mac Mini cloud : SSH fixe et CPU exclusif — voir tarifs location Mac Mini et prise en main via le centre d’aide. Suite de lecture dans le fil OpenClaw : observabilité → cron → mode distant → ce fork upgrade.
Tampon « quelle génération OpenClaw a fini par écrire la config » — si le PATH résout encore un binaire plus ancien, les gardes peuvent bloquer les écritures de service. Corriger PATH et le runbook avant d’éditer la JSON ligne à ligne.
Tant que le split brain n’est pas écarté, la liste cron peut sembler OK alors que la couche d’exécution refuse — finir la section trois puis le guide cron. Plus de textes sous le fil OpenClaw.
Comparer gateway.mode, gateway.remote.url et gateway status — détails dans dépannage mode distant; capacité sous tarifs location.