2026-04-22 OpenClaw npm : modules obsolètes et redémarrage de passerelle sur Mac cloud sans tête loué

Les opérateurs qui exécutent OpenClaw via une installation npm globale sur des Mac Apple Silicon loués voient souvent, après une mise à jour, un schéma déroutant : openclaw --version affiche le nouveau semver, mais la passerelle charge encore d’anciens modules—webhooks instables, cœurs de chaîne manquants, journaux avec chemins mélangés. Cet article du 2026-04-22 documente une mise à jour en arrêt d’abord, la mitigation double redémarrage alignée sur les rapports communautaires de résolution Node obsolète, et un retour arrière associé à mise à niveau & rollback de passerelle. Il complète onboarding & daemon (premier boot) et variables & secrets (chemins d’état).

Signaux de modules obsolètes à journaliser

Capturez des preuves avant de modifier les globaux npm—vous remercierez plus tard, en débogage à 2h du matin.

Signal	Interprétation	Commande de capture
Le journal passerelle montre deux semver	Binaire à jour mais le worker importe encore l’ancien arbre	Archiver journalctl/stdout + which openclaw
Erreurs d’import ESM intermittentes après upgrade	Chemins de résolution node_modules mélangés	npm ls -g openclaw --all + dump d’env passerelle
Premier redémarrage sain, trafic encore bizarre	Deuxième rebond nécessaire pour vider le cache modules	Health curls horodatés vers 127.0.0.1

Instantané prévol & sauvegarde

1. Noter openclaw --version et node -v (cible Node 22.16+ ou 24.x selon l’upstream).
2. Archiver ~/.openclaw en tarball sur un chemin daté hors de l’arbre global npm—comme dans rollback passerelle.
3. Exporter les chemins plist launchd si vous les avez personnalisés pendant l’onboarding.
4. Vérifier OPENCLAW_STATE_DIR et la précédence des secrets via les notes launchd env.

Arrêt → Mise à jour → Redémarrage (l’ordre compte)

Ne laissez jamais npm réécrire les globaux tant que la passerelle verrouille encore des modules transpilés. Arrêtez d’abord, mettez à jour, puis redémarrez—comme pour tout démon Node en production sur macOS.

openclaw gateway stop && npm install -g openclaw@latest && openclaw gateway start

Double redémarrage passerelle pour modules obsolètes

Si les sondes montrent encore des versions mélangées, effectuez un second redémarrage propre : arrêt, attente de vidage des sockets, démarrage, nouvelles sondes locales. Cela reflète les mitigations publiques pour les upgrades npm globaux où Node garde une résolution obsolète jusqu’au second démarrage à froid. Entre les redémarrages, évitez de basculer trop tôt les upstreams nginx—suivez les sondes de santé avant de réexposer le trafic HK / JP / KR / SG / US.

À surveiller entre les redémarrages

Pendant la fenêtre calme, capturez les ports en écoute (lsof -nP -iTCP -sTCP:LISTEN filtré sur le port passerelle), confirmez qu’il ne reste pas d’enfants node orphelins, et vérifiez la pression inode sur le volume du préfixe npm global. Les équipes qui sautent cette étape « réussissent » souvent au premier rebond mais servent encore un graphe de modules mélangé si un worker long a survécu à SIGTERM. Horodatez : au moins 45–90 secondes entre stop et start sur hôtes chargés, et 120 secondes si antivirus ou indexation disputent les mêmes chemins—fréquent sur machines de build partagées.

Corrélez les logs applicatifs avec la charge système : si le load average reste au-dessus de 4× le nombre de cœurs pendant le redémarrage passerelle, repoussez la réouverture d’ingress jusqu’à ce que le CPU se calme ; sinon les health checks peuvent fluctuer pour des raisons hors npm. Pour les ponts de chat, envoyez un message « noop » synthétique via le webhook de staging après chaque redémarrage pour prouver la livraison bout-en-bout avant de promouvoir la route vers le DNS de production.

Enfin, capturez dans le ticket la racine globale npm (npm root -g) et le binaire résolu (which openclaw)—quand semver diverge, comparer ces deux chemins attrape tôt la dérive des symlinks. Les opérateurs multi-régions doivent répéter la même checklist par hôte ; des préfixes globaux différents entre nœuds JP et US expliquent souvent les rapports « ça ne marche que dans un DC » après upgrade.

Santé, journaux et réactivation de l’ingress

Après le second rebond, validez :

• curl local vers les endpoints admin/santé avec les champs JSON attendus.
• Continuité des journaux structurés selon le guide journalisation production.
• TLS ingress et chemins webhook via la config nginx reverse proxy.

Étendez avec des tests négatifs : cassez volontairement un jeton aval dans un agent bac à sable pour vérifier que les surfaces d’erreur correspondent aux gabarits du nouveau build—les semver mélangés apparaissent souvent d’abord comme texte d’erreur légèrement différent. Conservez au moins cinq métriques de base (latence p50/p95, taux d’erreur, profondeur de file, CPU, RSS) pendant 15 minutes après le changement pour comparer aux graphiques pré-upgrade ; sans historique, préparez les tableaux de bord avant npm.

Rollback quand semver ne converge pas

Si les doubles redémarrages échouent, réinstallez le dernier semver sain avec npm, restaurez le tarball ~/.openclaw et rejouez la séquence de démarrage passerelle. Documentez l’incident avec les versions npm et OpenClaw pour les fils de support. Pour l’accès mesh pendant la récupération, voir mesh Tailscale.

Scénario	Focus rollback	Temps attendu
Régression npm au niveau patch	Épingler le patch précédent avec npm	6–12 min
Dérive de config après upgrade	Restaurer le tarball + valider le schéma JSON	12–25 min
Incident multi-région	Basculer vers un second nœud MacXCode	Selon DNS/TTL

Runbooks associés

Les problèmes de canaux après upgrade peuvent recouper sous-agents & dépannage canaux ; l’empaquetage des skills diffère—voir Skills & ClawHub si l’upgrade incluait des migrations de skills.

FAQ : npm + passerelle sur Mac cloud

Question	Réponse
pnpm est-il pris en charge ?	Si votre org standardise pnpm, gardez la même discipline « arrêt d’abord » ; rendez les préfixes globaux explicites dans PATH.
Dois-je dockeriser à la place ?	Comparez dans Docker vs npm natif—les deux peuvent marcher ; cet article cible la location bare-metal.
Où suivre la santé en continu ?	Utilisez les liens aide pour les canaux support et maintenez des sondes synthétiques selon le guide production.

Pourquoi le Mac mini M4 est l’hôte stable pour les upgrades npm OpenClaw

Les nœuds bare metal Mac mini M4 offrent des temps de démarrage à froid déterministes pour les passerelles Node—crucial quand vous rebondissez volontairement deux fois. Face aux VM sur-souscrites, moins de cycles perdus à chasser des symptômes « CPU steal » qui ressemblent à des modules obsolètes. L’accès SSH-first MacXCode sur HK · JP · KR · SG · US, le NVMe optionnel 1–2 To pour les workspaces et un réseau prévisible simplifient les passerelles dupliquées pour blue/green. Quand npm s’accélère, ajoutez de la capacité via tarifs plutôt que d’empiler les expériences sur un hôte fatigué.