2026 OpenClaw Upgrade Playbook : 3.22 → v2026.3.24 sur Mac cloud

1. Trois modes d'échec : pourquoi npm update seul casse la prod

Les parcours rapides du tutoriel supposent des machines jetables. Les passerelles de production reliées aux ponts Slack ou Discord et aux formes de déploiement spécifiques se comportent autrement :

1. Pas de snapshot : sans archive tarball de la config, plist et fichiers d'environnement, vous ne pouvez pas prouver que l'ancienne version démarrait—le rollback devient du hasard, pire sur comptes Mac cloud partagés.
2. Dérive des préfixes : 3.22 attend OPENCLAW_* ; les variables façon ClawdBot/MoltBot peuvent ne plus être honorées. launchd n'injecte que ce qui est dans EnvironmentVariables ; des configs partielles silencieuses imitent des échecs auth ou timeout.
3. SecretRef fail-fast et nouveaux défauts : les secrets manquants peuvent arrêter le démarrage volontairement. PDF et canaux exigent la configuration des fournisseurs ; sans doctor, les problèmes restent cachés jusqu'au trafic.

Sur un compte Mac cloud partagé, ces échecs sont plus difficiles à isoler : plusieurs opérateurs exportent des variables différentes en shell interactif pendant que launchd injecte encore d'anciennes clés. Avant upgrade : capturez launchctl print pour le job, le chemin plist sur disque et un dump redacted de l'environnement effectif (jamais de secrets dans les tickets—noms de clés seulement). Mettez à jour les scripts sidecar pour les ponts IM dans la même fenêtre de changement pour aligner chemins de logs et fichiers de jetons avec la nouvelle CLI.

2. Matrice delta des releases

Vérifiez les clés exactes avec votre CLI installée et les notes de version amont ; ce tableau résume les deltas opérationnels courants.

Les équipes multi-plateformes lisent déploiement multi-plateforme—l'ordre des upgrades suit Linux ; seule la supervision diffère.

3. Étapes : snapshot, arrêt, upgrade, migration, doctor, fumée, launchd

Exécutez dans l'ordre ; ne rechargez pas launchd tant que doctor et les tests de fumée ne passent pas en shell de premier plan sous le même utilisateur de service.

1. Snapshot : archiver le répertoire de config, plist launchd, fichiers env ; noter openclaw --version et les révisions de lockfile. Avec Git : taguer le commit ; sinon au moins SHA256 de la plist et du binaire CLI.
2. Arrêt : openclaw gateway stop ; vérifier lsof -i :18789 selon le guide port ; arrêter les sidecars IM si besoin.
3. Upgrade binaires/paquets via canal supporté (pnpm/npm global ou install projet épinglé)—éviter les mélanges root/utilisateur.
4. Migrer l'env : remplacer les préfixes legacy par OPENCLAW_* dans plist EnvironmentVariables et profils shell.
5. Doctor : aucun ERROR ; tri des WARN selon la politique.
6. Fumée : petit PDF ; test SecretRef négatif puis restauration ; optionnel curl vers /v1/models en loopback avec bearer.
7. launchd : launchctl unload/load ; suivre les logs 15 minutes ; conserver le tarball plist précédent pour rollback en une étape.

Pour le PDF, choisissez une fixture de deux pages sous vos plafonds octets/pages ; notez le temps réel et le RSS dans Moniteur d'activité pour comparer avant/après. Pour SecretRef, pointez volontairement une clé staging vers un chemin vault manquant et vérifiez une sortie non nulle—puis restaurez la référence valide et relancez doctor jusqu'à zéro erreur.

4. Notes techniques citables

Node 22+ reste obligatoire ; les montées OS ou toolchain peuvent changer les alias nvm par défaut. SecretRef fail-fast est volontaire—il évite un fonctionnement silencieux avec identifiants factices, plus dangereux qu'un échec visible au déploiement. Les limites PDF protègent la RAM et la facturation : augmenter pdfMaxBytesMb sans ajuster la concurrence peut pousser un nœud Mac cloud en swap lors de sessions qui se chevauchent.

Les clients peuvent mettre en cache /v1/models ; videz après upgrade pour que les outils tiers ne gardent pas d'anciens IDs de modèle. Sur Apple Silicon, surveillez la pression mémoire si PDF et canaux streaming sont actifs ensemble ; la mémoire unifiée aide mais n'est pas infinie. ThrottleInterval de launchd peut masquer des boucles de crash rapides—inspectez launchctl print si les changements de config semblent ignorés, et les journaux système pour un throttling type code 78.

5. Des mises à jour ad hoc vers un Mac cloud auditable

Faire tourner la passerelle uniquement sur un portable de dev ou uniquement dans Docker sur Linux générique sans chemins volumes/secrets alignés « fonctionne » souvent jusqu'à ce qu'il faille des upgrades reproductibles : les portables dorment, Docker Desktop modifie le réseau, les bind mounts dérivent. Il manque un contrat launchd stable, les chemins SecretRef sont difficiles à garder identiques, et les régressions IM ou PDF se compliquent car GPU bureau et profils d'énergie diffèrent d'un serveur 24/7.

Un compte Mac cloud dédié avec plist versionnée, doctor/smoke scriptés et snapshots immuables transforme les upgrades OpenClaw en tickets de changement. Louer des hôtes Mac cloud VPSMAC M4 pour le rôle passerelle conserve les chemins natifs Apple, un egress stable et l'isolation des portables de dev—les upgrades touchent une surface de service bornée plutôt qu'une station entière, et votre équipe peut montrer aux revues sécurité exactement quel binaire, quelle plist et quel environnement étaient actifs.

6. FAQ

La passerelle quitte silencieusement après upgrade ?

Vérifiez le statut launchd, ThrottleInterval, la sortie doctor et les conflits de port.

Conserver les variables env legacy ?

Non recommandé après 3.22 ; migrez vers OPENCLAW_* pour éviter les suppressions surprises.

Exposer la compat OpenAI au public ?

Non—loopback, tunnel SSH ou proxy authentifié uniquement.