Si vous exécutez OpenClaw sur un Mac mini M4 Pro bare metal à Singapour, Japon, Corée du Sud, Hong Kong, US Est ou US Ouest et êtes passé à 2026.5.2+, un Gateway qui refuse de démarrer faute de paquets plug-in externes relève rarement des clés modèle. Après le déplacement de la racine d’installation du npm global vers ~/.openclaw/npm, les configs pointant encore l’ancien arbre affichent missing plugin même si npm install -g @openclaw/discord réussit. Cet article vise les équipes en upgrade depuis 4.x ou début 5.x : matrice de chemins, runbook en dix étapes, limites de openclaw doctor --fix, --lint et --non-interactive, plus le découpage disque OPENCLAW_PLUGIN_STAGE_DIR sur Mac distant. Tarifs sur la page tarifs NOVAKVM ; commande sur la page commander ; politique de session dans le centre d’aide. À lire aussi : premier run, upgrade npm, santé 2026.5.x.
À la fin vous devez répondre avec preuves à trois questions : où doit vivre chaque plug-in activé, sous npm global ou ~/.openclaw/npm/node_modules ; comment installer les paquets hors ligne avant doctor quand Gateway ne boote pas ; comment répartir stage plug-in, logs et artefacts modèle sur Mac distants 256 Go contre 512 Go pour qu’un pic npm install ne sature pas le volume système. Sous-commandes CLI, noms de paquets et contrats de répertoires : vérifier la documentation officielle OpenClaw et les release notes GitHub au moment du gel de changement.
[ SECTION_01 ] // PLUGIN_FAILURE Cinq causes et coûts cachés quand Gateway échoue sur les plug-ins externes après 2026.5.x
Première cause : dérive du chemin d’installation — npm install -g en fenêtre de maintenance, mais Gateway après 2026.5.2 scanne ~/.openclaw/npm/node_modules en manifest-first. Logs « configured plugin not found » pendant que l’équipe cherche dans l’arbre global. Deuxième cause : décalage nom de paquet et id de config — certains plug-ins canal ont des scopes npm qui ne correspondent pas exactement aux ids dans openclaw.json ; doctor liste des stale install sans que personne n’applique fix par crainte de supprimer un canal prod.
Troisième cause : dépendance circulaire doctor et Gateway — Gateway refuse le boot, l’équipe redémarre en boucle au lieu de finir openclaw doctor --fix ou un npm install manuel dans la bonne racine. Sur Mac distant, un fix non interactif sans backup de config peut retirer des plug-ins allow-only du manifeste et laisser des cron silencieux. Quatrième cause : contention disque sur hôtes 256 Go — stage, cache pnpm et logs Gateway sur un volume système ; pics npm et snapshots APFS, install OK mais Gateway en timeout. Cinquième cause : copie cross-nœud à moitié migrée — rsync de ~/.openclaw sans sous-arbre npm.
- Dérive de chemin : npm global et
~/.openclaw/npmcoexistent ; config non migrée. - Ambiguïté d’id : Brave, Discord, Voice — scopes et ids manifeste divergent.
- Mauvais ordre de réparation : redémarrage Gateway avant les paquets ; doctor non fixable.
- Risque non interactif :
doctor --fixsupprime des entrées allow-only en migration. - Marge disque : stage et logs sur un volume ; pics d’install déclenchent des alertes.
- Sync cross-nœud partielle : config copiée sans sous-répertoire
npm.
Les incidents plug-in externes se résument à une règle : chaque id en config doit pointer vers un seul paquet physique dans un seul répertoire convenu, pas une autre install CLI globale.
[ SECTION_02 ] // PATH_MATRIX npm global, ~/.openclaw/npm et ClawHub : matrice de chemins d’installation
2026.5.x pousse de nombreux plug-ins canal et extension vers npm-first tandis que les métadonnées manifeste réduisent le coût de scan au cold start. Figez un répertoire source de vérité avant d’épingler les versions.
| Dimension | A · npm global (-g) | B · ~/.openclaw/npm (défaut recommandé) | C · ClawHub / canaux intégrés |
|---|---|---|---|
| Usage | CLI seul, essais, transition doc 4.x | Gateway prod 2026.5.2+ multi-canaux | Intégrés officiels ou extensions ClawHub épinglées |
| Visibilité Gateway | Souvent installé, non scanné | Aligné avec la logique doctor | Selon manifeste et interrupteurs canal |
| Rollback | Moyen : arbre global et config ensemble | Faible : tarball du sous-arbre npm |
Faible à moyen : par id plug-in |
| Disque Mac distant | Souvent node_modules global système | Associé à STAGE_DIR sur volume données | Cache croît avec le nombre de plug-ins |
Si vous avez déjà épinglé ClawHub par projet dans la note multi-workspace, les plug-ins npm externes restent enregistrés par workspace pour qu’une montée Discord sur le projet A n’écrase pas le répertoire partagé du projet B.
[ SECTION_03 ] // DOCTOR_STAGE Modes de réparation openclaw doctor et couche OPENCLAW_PLUGIN_STAGE_DIR
Doctor propose inspection en lecture seule et réparation automatique. En fenêtre de changement, lancer d’abord openclaw doctor --lint pour archiver paquets manquants, installs obsolètes et config vers des répertoires inexistants, puis openclaw doctor --fix en maintenance. Si Gateway ne démarre pas, installer les paquets @openclaw/* manquants dans ~/.openclaw/npm sans démarrer Gateway, puis fix. Les migrations autour de 2026.5.2 montraient souvent des paquets lobster en global ignorés par le scan ; install manuelle puis fix bat les boucles de redémarrage.
OPENCLAW_PLUGIN_STAGE_DIR sépare la racine d’extraction npm de la racine de chargement runtime. Sur Mac distant, pointer le stage vers un disque données ou volume d’extension et garder les chemins chauds sur SSD. Après chaque release, vérifier que le plist launchd exporte encore la variable.
Rouvrir la documentation doctor et les release notes officielles après chaque tag adopté.
https://docs.openclaw.ai/gateway/doctor
https://github.com/openclaw/openclaw/releases
openclaw doctor --lint > /tmp/oc-doctor-lint.txt
cd ~/.openclaw/npm && npm install @openclaw/discord@<pinned>
export OPENCLAW_PLUGIN_STAGE_DIR="/Volumes/data/openclaw-stage"
openclaw doctor --fix --non-interactive
openclaw gateway status
[ SECTION_04 ] // RUNBOOK Dix étapes pour terminer la migration plug-ins externes 4.x vers 2026.5.x sur Mac distant
- Figer le manifeste plug-in : exporter ids activés, versions et dépendances canal dans le ticket de changement.
- Sauvegarde complète : tarball
~/.openclawavec sous-arbrenpmet plists launchd ; noteropenclaw --version. - Mettre à jour la CLI : suivre les release notes officielles ; ne pas sauter les indications de migration entre lignes majeures.
- Créer la racine npm : s’assurer que
~/.openclaw/npm/package.jsonexiste ; ne pas compter sur le global seul. - Installer depuis la liste : pour chaque plug-in externe,
npm installversion figée sous~/.openclaw/npm; allow-only avant canaux optionnels. - Définir STAGE_DIR : dès 512 Go, stage hors volume système ; sur 256 Go réserver au moins 20 Go pour plug-ins et cache.
- Lint puis fix :
doctor --lintsans entrées configured-but-missing, puis--fix. - Vérifier Gateway :
openclaw gateway statuset sondes port 18789 selon la note santé. - Tests fumée canal : un message test par canal activé ; latence et chemins de logs.
- Réécrire le runbook : arborescence finale, versions épinglées et emplacement du tarball de rollback ; revue trimestrielle.
Cas d’équipe anonymisé : trois personnes sur M4 Pro Tokyo, passage de 2026.4.27 à 2026.5.4 ; paquet discord manquant malgré npm i global répété. En suivant cette séquence, paquets sous ~/.openclaw/npm et stage sur volume d’extension ; doctor --fix vert en une fois ; indisponibilité estimée de 90 à 28 minutes.
[ SECTION_05 ] // DATA_FAQ Paramètres citables, budget disque et FAQ
Les intervalles ci-dessous sont des fourchettes de planification pour revues de capacité, pas des mesures garanties sur votre hôte. Réconcilier avec la doc officielle après chaque release.
- Racine plug-in : en prod 2026.5.2+, traiter
~/.openclaw/npm/node_modulescomme chemin de vérité ; éviter le mélange avecnpm root -g. - Budget disque : sur Mac distants 256 Go, réserver au moins 20 Go pour stage et cache npm ; multi-workspaces et logs lourds : voir extension 1 To ou 2 To.
- Modes doctor :
--lintpour CI et contrôles en lecture seule ;--non-interactivepour maintenance sans présence ;--deeppour arbres d’install dupliqués. - Rythme de release : 2026.5.3 à 5.4 ajoutent outils de transfert fichier et lazy loading Gateway ; plus de plug-ins rendent le cache manifeste et le découpage de répertoires plus utiles.
FAQ :
- Q : Garder les paquets installés en global ? R : Pas en défaut prod. Migrer vers
~/.openclaw/npmet aligner la config. - Q : Lancer doctor si Gateway est arrêté ? R : Oui. Doctor n’exige pas que Gateway écoute ; installer les paquets manquants avant fix.
- Q : Différence avec la note upgrade ? R : La note upgrade couvre CLI et LaunchAgent ; celle-ci couvre chemins npm plug-ins externes et migration 4.x.
- Q : Quelle région pour l’install ? R : Même machine que Gateway ; pour le dépannage transfrontalier, placer la console près des opérateurs ; voir la page tarifs.
Les alternatives ont des limites réelles. Les essais plug-in sur portable local ne prouvent pas l’héritage d’environnement launchd sur bare metal distant. Des arbres plug-in sur volume système non extensible finissent par heurter les mises à jour npm répétées. Les Mac de bureau offrent rarement changement de région ou upgrade stockage rapide en fenêtre de migration. Pour les équipes qui livrent des plug-ins externes OpenClaw 2026.5.x avec CI iOS et agents IA et ont besoin de chemins doctor et ~/.openclaw/npm auditables et rollback-friendly, la location cloud Mac mini NOVAKVM est en général la meilleure option : Apple Silicon dédié, six régions bare metal, validation jour ou semaine avant montée en gamme M4 Pro et extension stockage. Avant le prochain minor OpenClaw, tarballer manifeste plug-in et sous-arbre npm — cela vaut mieux que deviner à deux heures du matin où les paquets se trouvent vraiment.