2026 OpenClaw v2026.5.20 sur Mac VPS : recette de mise à niveau, nœud gateway géré, dérive protocole et runbook Policy/Doctor (matrice décision et FAQ)

1. Points de friction : multi-Node, protocole, dérive config

Sur un hôte Mac cloud, une panne OpenClaw est rarement « modèle sans crédit ». Plus souvent le processus passerelle écoute encore sur 18789, mais CLI et passerelle tournent sur des installations Node différentes — ou leurs versions protocole divergent d un cran. Symptômes : le premier gateway restart après upgrade échoue au healthcheck, canaux qui tombent aléatoirement, Cron marquant des jobs réussis en failed. Cela touche surtout les équipes stables depuis des semaines qui appliquent v2026.5.20 pour les notes de version — sans voir que le patch vise surtout la fiabilité multi-Node sur Mac VPS.

Si vous avez déjà lu le runbook passerelle ou la baseline de mai, le schéma est connu : tout semble sain tant qu aucun restart ni job Cron ne teste la frontière protocole. v2026.5.20 rend cette faille visible — à condition de mesurer chemin Node et running version dans la même fenêtre.

Quatre clusters reviennent le plus souvent en tickets production et se collent directement dans un change board :

1. Dérive silencieuse multi-Node : avec Homebrew, nvm et Node du script d install, l ancien openclaw update pouvait router les commandes suivantes vers un autre Node tandis que le service gateway géré gardait d anciens chemins.
2. Écart protocole CLI/passereelle : CLI en 5.20, passerelle en 5.18 — healthcheck de restart en échec apparent, équipes réinstallent des plugins au mauvais niveau.
3. Alertes doctor ignorées : depuis 5.20, clés API en clair dans openclaw.json, politique sandbox MCP, thinkingFormat invalide. Un doctor --fix aveugle peut supprimer des champs provider encore nécessaires.
4. Chemin Exec modifié : les Skills n acceptent plus cat SKILL.md en shell ; l outil read est obligatoire. L automation shell-cat casse avec « outil refusé ».

2. Matrice décision : quand passer à 5.20

3. Snapshot avant mise à niveau

Avant tout binaire, archivez ces sorties dans le ticket de changement — texte brut suffit pour comparer au rollback :

openclaw --version
openclaw gateway status --json | tee /tmp/gw-before.json
lsof -nP -iTCP:18789 -sTCP:LISTEN
which node; node -v
type -a node 2>/dev/null || true
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)
launchctl print gui/$(id -u)/ai.openclaw.gateway 2>/dev/null | head -80

Retenez le chemin Node absolu dans ProgramArguments et running Gateway version depuis gateway status --json — plus fiable depuis 5.20. Si la base diverge du runbook passerelle, réparez d abord.

Archivez l instantané dans le ticket avec horodatage et utilisateur SSH. Au rollback, comparez /tmp/gw-before.json ligne par ligne au post-upgrade — un écart sur runningVersion ou server signale souvent que le fix nœud géré n est pas actif. Même checklist sur staging pour reproduire la dérive avant la prod.

4. Runbook en sept étapes

Étape 1 : épingler la version et update

openclaw update --tag v2026.5.20
# ou npm global :
# npm i -g openclaw@2026.5.20

Attendez la fin du healthcheck de redémarrage. En échec, ne réinstallez pas les plugins tout de suite — étape 2 Node d abord.

Étape 2 : nœud gateway géré sans dérive

openclaw --version
which node
node -v
openclaw gateway status --json | jq '.server,.version,.runningVersion'

Correctif clé en 5.20 : les commandes après openclaw update doivent utiliser le même Node que le service gateway géré — pas « CLI Homebrew, launchd /usr/local ». Les versions majeures de node -v doivent correspondre.

Étape 3 : restart passerelle et 18789

openclaw gateway restart
sleep 3
lsof -nP -iTCP:18789 -sTCP:LISTEN
openclaw gateway status --deep

Si --deep échoue, runbook passerelle sur gateway.auth, loopback et token — ne changez pas le provider modèle en premier.

Étape 4 : openclaw doctor (plugin Policy)

openclaw doctor
openclaw doctor --fix   # seulement après revue du diff

Depuis 5.20 le plugin Policy bundled vérifie conformité canal et workspace. Sur alerte clé en clair, migrez vers env ou SecretRef, ne désactivez pas doctor.

Étape 5 : smoke canal

Un aller-retour sur Telegram, Feishu, Slack ou votre canal prod. Multi-canaux : phase mono-canal du runbook multi-canal — évitez trop de variables à la fois.

Étape 6 : essai Cron

openclaw cron list
# déclencher une tâche à faible risque, état final success sans override tool warning

5.20 corrige les Cron réussis marqués failed à cause de warnings tool en fin de trace, et les blocages entre main-session et cron wake lane. Log et état final doivent concorder.

Comptez dix à quinze minutes pour les étapes 1–6 sur un Mac VPS dédié sans npm global parallèle. Ne stoppez pas à l étape 2 si which node et launchd divergent — c est le cœur de v2026.5.20. Notez chaque commande avec code de sortie ; cela accélère l escalade si le smoke canal échoue alors que la passerelle est déjà verte.

5. Tableau d acceptation v2026.5.20

6. Erreurs et rollback

Rollback : backup JSON, tag précédent, gateway restart. Config non auditable : baseline mai sur nœud neuf.

Gardez la même rigueur qu à l upgrade : chemins Node, puis config, puis canaux. Erreur fréquente : relancer le pairing après rollback alors que le processus passerelle reste sur le mauvais binaire. Si vous connaissez le rollback ACP du site, combinez pin digest et restauration json dans une même note de ticket.

7. Trois signaux citables

• Cohérence Node : dans la même fenêtre, le Node launchd géré et celui rapporté par openclaw update partagent la même version majeure — sinon le fix 5.20 n est pas actif.
• Visibilité version : gateway status --json expose running Gateway version = 2026.5.20, alignée avec openclaw --version.
• État final Cron : un job réussi ne doit plus être écrasé par des tool warnings de queue ; une sonde avec flag delivered compte plus que le vert passerelle seul.

8. FAQ

Question : Docker vs chemin npm ? En conteneur, le Node de l image prime ; sur Mac VPS hôte npm+launchd, l épinglage Node de cet article est décisif. Upgrade Docker : aligner tag image et backup config volume.

Question : sauter 5.18/5.19 ? Oui, avec snapshot ; staging sept étapes puis production.

Question : lien avec le premier déploiement en cinq étapes ? Cinq étapes = zéro à en ligne ; cet article = upgrade sûr d une instance 7×24 vers 5.20. Installation neuve peut viser 5.20 directement, puis recette multi-canal.

9. Conclusion

v2026.5.20 apporte moins de vitrine fonctionnelle que des contrats Node et protocole stables sur Mac VPS — là où naît « la passerelle ne remonte plus après upgrade ». Notebook ou WSL2 conviennent aux essais courts ; veille, NAT et mélange multi-Node masquent la dérive update. Un VPS Linux pur peut héberger la passerelle mais manque launchd et la documentation Apple cumulée. Pour une entrée production 7×24, exécutez ce runbook en fenêtre de maintenance et inscrivez nœud géré, doctor et état Cron dans le modèle de changement — plutôt que des réinstall complètes en boucle. Les équipes voulant disque stable, launchd auditable et runbooks SSH gagnent avec un Mac VPS Apple Silicon VPSMAC qui regroupe 18789, backup config et recette upgrade — cohérent avec les guides passerelle, multi-canal et baseline du site.