Si vous exécutez déjà OpenClaw Gateway en démon sur un Mac distant, le moment risqué n'est pas de taper npm install -g une fois. C'est le faisceau frontières Node globales, sauvegardes atomiques de configuration et d'identifiants, probes post-upgrade qui séparent processus up de canaux sains, et pin npm réversible lorsque l'amont bouge vite. Cet article s'adresse aux équipes qui démarrent Gateway à la main et veulent une voie auditée : liste d'échecs franche, matrice in-place contre côte-à-côte, ossature de commandes copiables, six étapes opérationnelles et quatre références pour votre fiche de changement. Tarifs sur la page tarifs NOVAKVM, commandes via la page de commande, politique d'accès distant dans le centre d'aide. Croisez le runbook d'installation et l'article dépannage canaux de l'index du blog si vous touchez webhooks ou reverse proxy.
Après lecture vous saurez si vous revenez d'abord sur npm ou sur LaunchAgent quand les deux semblent suspects, comment traiter openclaw gateway probe comme seuil entre statut processus vert et canaux réellement sains, et comment utiliser des nœuds bare metal à Singapour, Japon, Corée du Sud, Hong Kong, US Est et US Ouest avec marge M4 Pro pour répéter les upgrades sans empoisonner les volumes de production. Les liens amont et le comportement de version changent ; rouvrez-les avant d'exécuter.
Points d'entrée amont, une URL par paragraphe pour faciliter la copie.
https://github.com/openclaw/openclaw
https://openclaws.io/docs/install/updating/
[ SECTION_01 ] // PAIN_MAP Où les upgrades OpenClaw laissent le Gateway en production
- Deux mondes PATH : les shells interactifs voient le nouveau préfixe bin global tandis que les jobs LaunchAgent pointent encore vers un préfixe ancien, produisant succès manuel et échec au reboot.
- JSON sans identifiants : copier seulement
openclaw.jsonoublie l'arbrecredentials; les canaux tombent avec des erreurs en forme d'identifiants qui ressemblent à des régressions. - Journaux et workspace sur un petit volume : migrations ou réindex amplifient l'écriture ; si les logs Gateway partagent ce volume, vous chassez des fantômes dans les notes de version.
- Sauter la probe après start : un exit zéro de
openclaw gateway startne prouve pas des webhooks ou listeners locaux sains ; reportergateway probedéplace la douleur vers le pic de trafic. @latestaveugle sans pin enregistré : le rollback devient deviner le tag au lieu d'une ligne npm.- Hôtes sous-dimensionnés pendant la fenêtre : pression mémoire et jitter disque pendant l'upgrade se déguisent en régressions amont ; du Apple silicon dédié avec marge isole les variables.
Documentez aussi quels comptes de service écrivent quels chemins et si l'identité du runner CI correspond à la production. Une pipeline verte qui met à jour le mauvais préfixe est pire qu'une fenêtre manuelle car elle masque le rayon d'effet jusqu'au trafic. Pour les copies froides susceptibles de contenir des jetons ou du contenu de canaux, fixez finalité, durée de conservation et accès conformément au RGPD et à votre politique interne, afin que les artefacts de maintenance ne dépassent pas le besoin.
[ SECTION_02 ] // DECISION_MATRIX Upgrade in-place, préfixe parallèle et rollback npm comparés
Cette matrice échange rayon de changement contre coût de rollback. Faites défiler horizontalement sur écran étroit.
| Stratégie | Meilleure fenêtre | Ancre de rollback |
|---|---|---|
| Upgrade npm in-place | Petits pas semver avec notes lisibles et budget probe de trente minutes | Capturer npm ls -g --depth=0 avant changement ; garder npm install -g openclaw@<previous> prêt |
| Bascule répertoire parallèle | Risque moyen quand deltas de config ou ABI de plugins comptent | Arbres workspace et config horodatés ; permuter symlink d'entrée ou argv sans piétiner les handles ouverts |
| Gel de version | Chevauchement audit avec semaine de release ou fils de régression connus | La fiche liste semver gelé plus owner pour la fenêtre de recovery et minutes d'indisponibilité acceptables |
La plupart des équipes survivent avec upgrade in-place plus probes strictes plus rollback npm épinglé. Les arbres parallèles aident quand surface de config ou de canal diverge assez pour répéter en parallèle.
Les hooks d'automation méritent la même rigueur que les binaires : si votre CI déclenche des scripts d'upgrade distant, l'identité du runner doit correspondre à l'utilisateur LaunchAgent de production et les secrets injectés ne doivent pas être plus larges que le besoin. Les liens de documentation font partie de l'artefact de changement : collez le commit ou tag exact que vous avez lu, pas seulement latest flottant, pour que les relecteurs reproduisent vos hypothèses. Gardez le paquet de liens à côté du transcript de probe dans le ticket pour audit et astreinte.
Ajoutez trois lignes de passation : ports actifs, healthchecks externes verts, et si la rotation des logs a bougé pendant la fenêtre. Cela épargne des heures quand le release suivant arrive le lendemain et que personne ne se souvient de la version intermédiaire réellement en ligne.
[ SECTION_03 ] // COMMANDS Upgrade npm global plus version, status et snippets de probe
Ces snippets illustrent la structure, pas votre ligne de sécurité finale. Confirmez les exigences de major Node contre le README amont avant exécution. Lancez les probes dans le même contexte utilisateur que la production pour éviter les faux positifs où root passe mais pas LaunchAgent. Relisez dans une fenêtre calme si Node 22 ou plus récent reste obligatoire pour votre cible.
npm install -g openclaw@latest
openclaw --version
openclaw status
openclaw gateway restart
openclaw gateway probe
Sous macOS avec LaunchAgent, si le redémarrage reste capricieux, utilisez launchctl dans la fenêtre de maintenance pour vérifier que la plist chargée pointe encore vers l'exécutable voulu. Les noms d'étiquette dérivent entre releases ; suivez les notes amont actuelles plutôt que des identifiants périmés.
Rédigez l'ordre de triage comme une courte pièce plutôt qu'une improvisation : confirmez existence du processus et liaison du listener, puis parcourez les queues de logs pour des erreurs en forme certificat ou DNS, seulement alors suspectez des régressions amont. Snapshottez semver, préfixe npm global et ProgramArguments LaunchAgent ensemble pour garder les discussions de garde factuelles.
Un autre angle mort est l'ordre entre upgrade et reconstruction de cache : certaines releases suggèrent réindexer ou migrer l'état local. Sous pic de trafic plus disque bas, l'attente I/O normale ressemble à un gel. Répétez l'upgrade complet plus probe d'abord sur un hôte de staging de même palier, rejouez ensuite le même script dans la fenêtre ; une location bare metal courte héberge cette répétition sans toucher les volumes de production. Comparez l'espace libre après la fenêtre et vérifiez que la rotation des logs reste alignée avec vos obligations.
[ SECTION_04 ] // BACKUP Checklist de sauvegarde à figer avant tout changement
- Config primaire : souvent
openclaw.json; copiez vers un nom horodaté et validez le parsing JSON. - Arbres d'identifiants :
credentialsou le chemin documenté amont ; faites revenir config et identifiants comme une seule unité. - Workspace et caches : enregistrez tailles et chemins ; décidez si les copies froides valent le temps face au risque mesuré.
- Définitions LaunchAgent : exportez la plist active ou l'équivalent installeur ; rétablissez le contexte de lancement avant de débattre des couches npm.
- Inventaire canaux et ports : listez Telegram, Discord ou autres URLs webhook et santé pour cases à cocher post-upgrade.
- Données personnelles : si journaux ou exports peuvent contenir des données issues des canaux, documentez finalité, lieu, durée de conservation et rôles autorisés selon le RGPD avant de stocker des copies hors du serveur de production.
Après sauvegardes, exécutez une répétition en lecture seule : importez les copies sous utilisateur temporaire ou préfixe sans écrire les chemins de production, lancez des status et probe minimaux, vérifiez que les chemins relatifs résolvent encore sous les répertoires de travail LaunchAgent. Beaucoup d'échecs post-upgrade sont une dérive de cwd, pas des paquets corrompus. L'exercice révèle aussi si des fichiers sensibles vivent là où le gestionnaire de paquets pourrait nettoyer.
[ SECTION_05 ] // RUNBOOK Six étapes de la répétition read-only au recovery LaunchAgent
- Geler la fiche de changement : semver cible, fenêtre de maintenance, owner du rollback, minutes d'indisponibilité acceptables.
- Artefacts en copie froide : config, identifiants, snapshot workspace et sortie
npm ls -g --depth=0. - Pause l'ingress : suspendez les webhooks ou affichez la maintenance en périphérie pour empêcher des écrivains mi-upgrade de toucher les données utilisateur.
- Exécutez l'upgrade npm et vérifiez :
openclaw --versionetopenclaw statusdoivent correspondre à l'intention de la note de version. - Redémarrez Gateway et probez :
openclaw gateway restartpuisopenclaw gateway probe; rechargez LaunchAgent selon l'amont avant une nouvelle probe. - Alignez la politique puis remontez le trafic : confirmez sessions distantes, parallélisme et journalisation contre le centre d'aide, validez le dimensionnement sur la page de commande si vous manquez de marge, tarifs faisant foi sur la page tarifs.
Étendez le runbook d'un court créneau post-mortem même en cas de succès : horloge murale par étape, semver exact avant et après, probes en échec transitoire ou persistant. Cette habitude transforme la prochaine fenêtre d'archéologie en diff. Si plusieurs régions partagent le même canal, notez quel tronc a porté l'ingress pendant la fenêtre pour corréler latence et état machine plutôt que blâmer aveuglément la release.
Quand les secrets tournent à un rythme différent des paquets, ajoutez une ligne explicite indiquant si cette fenêtre touche les jetons. Des répertoires d'identifiants mi-à-jour avec des binaires frais produisent souvent des pannes partielles déroutantes qui ressemblent à du réseau dans les logs.
[ SECTION_06 ] // HARD_FACTS Sources auditables, signaux de rollback, clôture production
- Releases et issues amont : GitHub Releases et Issues portent fils de régression et séquence recommandue ; lisez les éléments liés à votre tag cible avant changement. Source : page du dépôt GitHub ; rouvrez avant exécution.
- Docs officielles updating : décrivent upgrades globaux et ordre de redémarrage Gateway ; le texte bouge avec les releases. Source : page updating openclaws.io.
- Frontière de major Node : l'amont fixe des exigences runtime qui changent ; gardez la compatibilité Node 22 ou plus récent dans la même fiche. Source : README et notes de version.
- Empreinte NOVAKVM : Mac mini bare metal dédiés à Singapour, Japon, Corée du Sud, Hong Kong, US Est et US Ouest avec paliers M4 et M4 Pro pour triage basse latence pendant les fenêtres. Source : page tarifs et centre d'aide sur le site.
Virtualisation partagée ou production portable-only amplifie le risque d'upgrade via bruit voisin, politique de veille et dérive locale non auditée. Garder Gateway sur du bare metal Apple silicon dédié réduit les variables à version de paquet, configuration et contexte de lancement.
Le budget disque mérite sa ligne dans la fiche : espace libre avant upgrade, juste après installation des paquets, après le premier cycle de probe complet. Si la rotation des logs a changé entre releases, vérifiez la rétention contre vos obligations avant de déclarer victoire.
Pour la prochaine fenêtre OpenClaw, esquissez les paliers M4 Pro et disque disponibles sur la page tarifs NOVAKVM, puis répétez les probes sur un hôte obtenu via la page de commande qui reflète la topologie de production. Quand vous avez besoin de latence six régions, d'upgrades reproductibles et de frontières ops claires pour les agents, la location cloud bare metal Mac mini NOVAKVM est souvent une base plus reproductible que l'improvisation sur matériel grand public qui dérive. Poursuivez dans le centre d'aide et l'index du blog ingénierie.