Derive des dependances npm pairs OpenClaw et rebuild propre sur Mac cloud 2026 : arreter ERESOLVE sur les passerelles Apple Silicon MacLogin

Quand npm install passe au rouge sur un mini MacLogin apres un bump de plugin anodin, la cause est rarement npm cassee. C est presque toujours la derive des pairs : peers optionnels, majeurs dupliques, arbres hoistes en desaccord avec la ligne Node 22 documentee. Ce guide avril 2026 propose un gommage reproductible : snapshot, suppression, npm ci, doctor, launchd pour HK, JP, KR, SG et US sans floconner l hote. Matrice de symptomes, budget disque, FAQ pour equipes ayant deja lu le runbook doctor.

Comparez les modes dans install.sh vs npm global, alignez l onboarding avec installation sans tete et daemon. Capacite : tarifs ; checklists : aide ; GUI : VNC ; hub : page OpenClaw. Etat : sauvegarde ~/.openclaw ; prod : health check rollback.

Pourquoi les pairs blessent les minis partages

Contrairement aux conteneurs jetables, les minis loues accumulent 3 a 7 experiences paralleles sous ~/.npm. Chaque npm link incomplet laisse des symlinks qui cassent le hoist.

• Homes partages : un --legacy-peer-deps empoisonne l installation suivante.
• miroirs hors ligne retardes de 24 a 72 heures.
• LaunchAgents redemarrent avant flush des logs.

Matrice symptomes

Symptome	Racine probable	Attenuation	Verifier
ERESOLVE au demarrage	Majeurs de plugins en conflit	Epinglez le parent	npm explain
Passerelle quitte code 1	Peer optionnel manquant	npm ci avec dev deps	openclaw doctor
Boucles hot reload	Installation partielle	rm -rf node_modules	diskutil + df

Sept etapes rebuild propre

1. Snapshot ~/.openclaw et lockfiles : guide etat.
2. Arreter LaunchAgent (15 s de grace).
3. Supprimer node_modules si la politique le permet.
4. npm cache verify puis prune si corruption.
5. npm ci avec ou sans optional selon prod.
6. openclaw doctor --json vers ~/Logs.
7. Relancer launchd et curl le health 5 fois.

Politique lockfile et parite CI

Commitez package-lock.json sur la meme branche que le gateway. La CI doit executer npm ci sur runners macOS quand c est possible ; une CI Linux-only rate des optionnels resolus differemment sur macOS dans environ 12 % des tickets MacLogin d avril 2026.

Ajoutez une barriere de fusion qui echoue lorsque npm ls --all --omit=dev sort en erreur pour le profil passerelle, meme si les installs de dev semblaient saines. Couplez-la a une tache hebdomadaire qui rejoue la meme commande sur le mini loue lui-meme pour attraper la derive entre image CI et layout APFS avant que launchd ne recycle le service.

overrides, bundledDependencies et discipline engines

Quand les pairs se battent, on attrape les flags en premier. Sur les hotes MacLogin, preferez des correctifs declarifs qui survivent a la passation : overrides dans package.json (proprietaire + date d expiration dans le ticket), bundledDependencies pour les petits shim vendeur a livrer mot pour mot, et plages engines.npm / engines.node alignees sur la ligne Node 22 deja citee dans vos runbooks.

• Audit overrides : chaque override nomme le CVE, la regression ou le ticket amont qu il attenue ; les overrides vides pour forcer le vert partent au prochain grooming.
• Deps bundlees : reserve aux paquets que vous pouvez redistribuer legalement et dont l integrite est checksumee dans le ticket.
• Registries prives : si un miroir Verdaccio ou Artifactory reordonne les metadonnees, epinglez la version du miroir et archivez la sortie npm view avec le bump de lockfile.
• Layouts workspace : les passerelles en monorepo doivent declarer des frontieres npx --no-install pour qu un npm link fraternel ne reecrive pas le graphe de peers au runtime.

Champs du modele de passation

Lorsque vous ouvrez une demande de changement, incluez : hash du lockfile avant/apres, extraits npm explain pour chaque paquet en conflit, diff du JSON doctor, et le chemin du plist LaunchAgent redemarre. La revue securite s appuie sur ces champs pour trancher dette temporaire ou bascule de politique durable.

Budget disque node_modules

Suivez du -sh ~/.openclaw/**/node_modules chaque semaine. Au-dela de 9 Go planifiez un rebuild ; surveillez aussi les inodes et purgez .npm/_cacache avec TTL 7 jours.

Garde doctor avant launchd

Traitez le JSON doctor comme artefact de release : diff contre le dernier vert. Rejetez si plus de 2 nouveaux avertissements sans proprietaire. Coupez avec health checks de coupure JP vers US.

FAQ

--force ? Clones jetables seulement ; jamais sur hotes partages.

HK et US doivent matcher Node ? Oui, meme LTS documente dans aide.

MacLogin peut effacer node_modules ? Reset d urgence oui ; hygiene courante reste dans votre runbook pour garder les epingles custom.

Quand les npm overrides sont-ils plus surs que --legacy-peer-deps ? Les overrides sont revus, versionnes et visibles dans git blame. Les flags legacy se cachent dans lhistoire du shell et disparaissent quand le prochain ingenieur lance un simple npm install : bannissez-les sur les minis loues partages sauf repertoires jetables.

Pourquoi Mac mini M4 accelere

M4 extrait npm vite et garde les services TS chauds pendant la reinstallation. Flotte multi-region MacLogin pour rebuild a cote des charges. Louer permet de monter un mini plus large via tarifs si le disque coince.