OpenClaw npm Peer-Dependency-Drift und Clean-Rebuild auf Cloud-Mac 2026: ERESOLVE-Churn auf MacLogin Apple Silicon-Gateways stoppen

Wenn npm install auf einem MacLogin-Mini nach einem harmlosen Plugin-Bump von gruen auf rot springt, ist npm selten kaputt. Fast immer ist es Peer-Drift: optionale Peers, doppelte Majors oder Hoists, die von der dokumentierten Node-22-Basislinie abweichen. Dieses April-2026-Rebuild-Leitfaden fuehrt Plattformteams durch Snapshot, Loeschen, npm ci, doctor, launchd in HK, JP, KR, SG und US ohne Schneeflocken-Host. Symptommatrix, Disk-Mathematik, FAQ fuer Leser von Doctor-Runbook.

Installationsmodi: install.sh vs npm global ; Headless: Onboarding und Daemon ; Preise ; Hilfe ; VNC ; OpenClaw-Hub ; State-Backup ; Cutover-Checks.

Warum Peers auf geteilten Minis weh tun

Gemietete Minis sammeln 3 bis 7 parallele Experimente unter ~/.npm. Unvollstaendiges npm link zerstoert Hoisting.

• Geteilte Homes : --legacy-peer-deps vergiftet Folgeinstalls.
• Offline-Spiegel 24 bis 72 Stunden hinter oeffentlichem npm.
• LaunchAgents starten neu bevor Logs flushen.

Symptommatrix

Symptom	Wahrscheinliche Ursache	Erste Hilfe	Pruefen
ERESOLVE beim Start	Konfliktierende Plugin-Majors	Eltern-Plugin pinnen	npm explain
Gateway still exit 1	Fehlender optionaler Peer	npm ci mit dev deps	openclaw doctor
Hot-Reload-Schleifen	Teilinstallation	rm -rf node_modules	diskutil + df

Sieben Schritte Clean-Rebuild

1. Snapshot ~/.openclaw laut State-Guide.
2. LaunchAgent stoppen (15 s Grace).
3. Loeschen wenn Policy erlaubt.
4. npm cache verify ggf. prune.
5. npm ci optional-Policy wie Prod.
6. openclaw doctor --json.
7. launchd neu und Health 5 mal curl.

Lockfile-Politik und CI-Paritaet

Committen Sie package-lock.json auf denselben Branch wie das Gateway. Die CI sollte wenn moeglich npm ci auf macOS-Runnern ausfuehren ; Linux-only CI verpasst optionale Abhaengigkeiten, die macOS anders aufloest, in rund 12 % der MacLogin-Supporttickets vom April 2026.

Ergänzen Sie eine Zusammenfuehrungssperre, die fehlschlaegt, wenn npm ls --all --omit=dev fuer das Gateway-Profil nicht-null beendet, selbst wenn Dev-Installs gruen wirkten. Kombinieren Sie das mit einem woechentlichen Job auf dem gemieteten Mini, der denselben Befehl wiederholt, damit Drift zwischen CI-Image und APFS-Layout des Hosts auffaellt, bevor launchd den Dienst neu dreht.

Overrides, bundledDependencies und Engine-Disziplin

Wenn Peers kollidieren, greifen Teams zuerst zu Flags. Auf MacLogin-Hosts bevorzugen Sie deklarative Fixes, die Uebergaben ueberleben: overrides in package.json (Owner plus Ablaufdatum im Ticket), bundledDependencies fuer kleine Vendor-Shims, die Sie wortgetreu ausliefern muessen, sowie engines.npm- / engines.node-Bereiche passend zur Node-22-Baseline Ihrer Runbooks.

• Overrides-Audit: Jeder Override benennt CVE, Regression oder Upstream-Issue ; leere Overrides nur fuer Gruen werden beim naechsten Grooming entfernt.
• Gebundelte Deps: Nur fuer Pakete, die Sie legal weiterverteilen duerfen und deren Integritaet Sie im Ticket per Checksumme belegen.
• Private Registries: Wenn Verdaccio- oder Artifactory-Spiegel Metadaten umsortieren, pinnen Sie die Spiegelversion und loggen Sie npm view-Ausgabe neben dem Lockfile-Bump.
• Workspace-Layouts: Monorepo-Gateways sollten npx --no-install-Grenzen deklarieren, damit versehentliches npm link aus Geschwisterpaketen den Peer-Graphen zur Laufzeit nicht umschreibt.

Uebergabe-Vorlagenfelder

Bei Aenderungsantraegen angeben: Lockfile-Hash vor/nach, npm explain-Auszuege je Konfliktpaket, Doctor-JSON-Diff und Pfad des LaunchAgent-plist, den Sie neu gestartet haben. Die Sicherheitspruefung nutzt diese Felder, um temporaere Schulden von dauerhafter Policy zu trennen.

Disk-Budget fuer node_modules

Woechentlich du -sh ~/.openclaw/**/node_modules. Ueber 9 GB geplant rebuild ; Inodes und 7-Tage-Cleanup fuer _cacache.

Doctor-Gates vor launchd

Doctor-JSON als Release-Artefakt diffen. Mehr als 2 neue Warnungen ohne Owner : ablehnen. Mit Cutover-Artikel kombinieren.

FAQ

--force? Nur Wegwerfklone.

HK und US Node? Gleiche LTS-Minor laut Hilfe.

MacLogin loescht node_modules? Notreset ja ; Routine bleibt im Runbook fuer Pins.

Wann sind npm overrides sicherer als --legacy-peer-deps? Overrides werden im Review freigegeben, sind versioniert und in git blame sichtbar. Legacy-Flags verstecken sich in Shell-Historien und verschwinden, wenn der naechste Ingenieur ein schlichtes npm install ausfuehrt : auf geteilten gemieteten Minis daher verbieten, ausser in Wegwerfverzeichnissen.

Warum Mac mini M4

Schnelles npm-Extrahieren, genug Unified Memory fuer TS waehrend Reinstall. Multi-Region-Flotte reduziert Tarball-Bias. Mehr Disk bei Preisen nachbuchen.