OpenClaw npm 對等依賴漂移與雲端 Mac 乾淨重建 2026：在 MacLogin Apple Silicon 閘道上終結 ERESOLVE 抖動
當 MacLogin 迷你主機上的 npm install 在一次看似無害的外掛小版本後由綠轉紅，根因很少是「npm 壞了」。 幾乎都是 對等依賴漂移：可選對等、重複大版本，或與閘道文件化的 Node 22 基線不一致的提升樹。本篇 2026 年 4 月重建指南帶平台團隊走過可複現的擦洗——快照、刪除、npm ci、doctor、launchd——涵蓋香港、日本、韓國、新加坡與美國，且不把主機磨成雪花機。 內含症狀矩陣、磁碟估算與 FAQ，適合已讀 doctor 診斷手冊 仍遇啟動不穩者。
安裝模式比較見 安裝指令稿對 npm 全域；無頭 onboard 見 無頭安裝與守護行程。容量見 定價；清單見 說明中心；GUI 見 VNC；專題見 OpenClaw 專題。狀態目錄見 狀態目錄指南；割接見 健康檢查與回滾。
共享迷你機上對等為何刺痛
與可丟棄的 CI 容器不同，租用迷你會在 ~/.npm 與開發者全域前綴下累積 3–7 個並行實驗。未完成的 npm link 留下搞亂提升的符號連結，閘道從錯誤深度載入外掛，對等看似缺失。
- 共享家目錄使某人的
--legacy-peer-deps毒害下一次安裝。 - 離線鏡像落後公開 npm 24–72 小時。
- LaunchAgents 在日誌刷盤前重啟閘道，掩蓋第一條 ERESOLVE。
node_modules 的卷至少 18 GB 可用。症狀矩陣
| 症狀 | 可能根因 | 首要緩解 | 驗證 |
|---|---|---|---|
| 啟動時 ERESOLVE | 外掛主版本衝突 | 釘選父外掛 | npm explain |
| 閘道以代碼 1 靜默退出 | 缺少可選對等 | 含 dev 的 npm ci | openclaw doctor |
| 熱重載迴圈 | 部分安裝 | rm -rf node_modules | diskutil + df |
七步乾淨重建
- 快照
~/.openclaw與鎖檔，見 狀態備份指南。 - 停止 LaunchAgent（15 秒優雅期）。
- 刪除
node_modules與 lock 若政策允許；否則僅npm ci。 - 執行
npm cache verify必要時 prune。 - 安裝：鏡像保證可選對等時方用
npm ci --omit=optional。 - 執行
openclaw doctor --json > ~/Logs/openclaw-doctor.json。 - 重啟 launchd 並 curl 健康端點 5 次。
pnpm 與 npm。鎖檔政策與 CI 一致性
將 package-lock.json 提交到部署閘道的同一分支。CI 儘量在 macOS runner 執行 npm ci；純 Linux CI 會漏掉 macOS 以不同方式解析的可選依賴，在 2026 年 4 月約占 MacLogin 支援工單 12%。
於合併閘道加入：閘道設定下若 npm ls --all --omit=dev 非零結束即失敗，即使開發機安裝看似正常。並排每週排程在租用迷你本機重播同一指令，讓 launchd 回收服務前就能發現 CI 映像與主機 APFS 版型之間的漂移。
overrides、bundledDependencies 與 engines 紀律
同伴打架時團隊常先抓旗標。在 MacLogin 主機上宜採可交接的宣告式修復：overrides 寫入 package.json（工單附負責人與到期日）、必須逐字交付的小型廠商墊片用 bundledDependencies，以及與運維手冊一致的 Node 22 基線下的 engines.npm / engines.node 區間。
- overrides 稽核： 每條 overrides 應指名緩解的 CVE、迴歸或上游議題；僅為「刷綠」而留的空 overrides 在下次整理時移除。
- bundled 依賴： 僅用於法律允許再發行且您在工單附件已做完整性校驗的套件。
- 私有 registry： 若 Verdaccio 或 Artifactory 鏡像重排 metadata，請釘選鏡像版本並在鎖檔 bump 旁保存
npm view輸出。 - 工作區版型： 單體儲庫閘道應宣告
npx --no-install邊界，避免兄弟套件的意外npm link在執行期改寫同伴圖。
.npmrc 啟用 engine-strict=true；小版本不一致常是「CI 同伴滿足、迷你上卻不滿足」的隱形根因。交接模板欄位
開變更請附：鎖檔雜湊前後、各衝突套件的 npm explain 摘錄、doctor JSON 差異，以及您重啟過的 LaunchAgent plist 路徑。安全審查依這些欄位判斷 overrides 是暫時債務或長期政策。
node_modules 磁碟預算
每週 du -sh ~/.openclaw/**/node_modules。總和逾 9 GB 即排程重建；並檢查 inode 與 7 天清理 .npm/_cacache 的任務。
launchd 前的 doctor 門檻
將 doctor JSON 當發布產物 diff；新增警告超過 2 條且無負責人則拒絕。搭配 割接健康檢查 做 JP→US 推進。
常見問題
--force？ 僅拋棄式複本；勿在共用租用上使用。
HK 與 US Node 要一致嗎？ 要，與 說明中心 同一 LTS 小版本。
MacLogin 能代刪 node_modules 嗎？ 緊急可平台重置，例行仍應由 runbook 持有以保留釘選。
何時 npm overrides 比 --legacy-peer-deps 更安全？ overrides 經審閱、納版控且可在 git blame 看到。legacy 旗標躲在 Shell 歷程，下一位工程師純跑 npm install 時會悄悄消失——故除可拋棄目錄外，共用租用迷你應禁用。
為何 Mac mini M4 加速重建
M4 單執行緒解壓更快、統一記憶體讓 TS 服務在閘道重裝時仍暖。MacLogin 多區讓你在工作負載旁重建，減少跨區 tarball 偏差。租用可在磁碟瓶頸時自 定價 換更大迷你機。
