OpenClaw npm ピア依存ドリフトとクラウド Mac クリーンリビルド 2026：MacLogin Apple Silicon ゲートウェイで ERESOLVE 揺れを止める
小さなプラグイン更新のあとに MacLogin ミニで npm install が赤に変わるとき、原因はめったに壊れた npm ではありません。 ほぼ常に ピア依存ドリフト です：オプショナルピア、重複メジャー、ドキュメント化された Node 22 基線と食い違うホイスト。この 2026 年 4 月ガイドはスナップショット、削除、npm ci、doctor、launchd の再現手順を HK/JP/KR/SG/US で示し、スノーフレーク化を避けます。 症状表、ディスク計算、FAQ を含みます。doctor 診断 読者向けです。
インストール比較は install.sh vs npm -g、ヘッドレスは オンボードとデーモン。料金 pricing、ヘルプ help、VNC VNC、ハブ OpenClaw ハブ。状態 バックアップ、カットオーバー ヘルスチェック。
共有ミニでピアが痛い理由
使い捨てコンテナと違い、レンタルミニは ~/.npm に 3–7 の並行実験を蓄積します。未完の npm link がホイストを壊し、ゲートウェイは誤った深さからプラグインを解決します。
- 共有ホームで誰かの
--legacy-peer-depsが次を汚染。 - オフラインミラーは公開 npm より 24–72 時間遅い。
- LaunchAgents がログフラッシュ前に再起動し最初の ERESOLVE を隠す。
node_modules ボリュームに最低 18 GB 空き。症状マトリクス
| 症状 | 根っこ | 最初の手当 | 確認 |
|---|---|---|---|
| 起動時 ERESOLVE | プラグインメジャー衝突 | 親を固定 | npm explain |
| サイレント exit 1 | 欠落オプショナルピア | dev 込み npm ci | openclaw doctor |
| ホットリロードループ | 部分インストール | rm -rf node_modules | diskutil + df |
7 ステップクリーンリビルド
- スナップ
~/.openclawとロック：状態ガイド。 - 停止 LaunchAgent（15 秒猶予）。
- 削除
node_modulesと lock は方針次第。 - npm cache verify、破損なら prune。
- npm ci、optional は本番と一致させる。
- openclaw doctor --json を ~/Logs に。
- launchd 再起動後、ヘルスを 5 回 curl。
pnpm と npm を混ぜない。ロックファイル方針と CI 同等性
package-lock.json をゲートウェイをデプロイするのと同じブランチにコミットする。CI は可能なら macOS runner で npm ci を実行する；Linux のみだと macOS が異なる方法で解決する optional を取りこぼし、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 ミラーがメタデータを並べ替えるならミラー版を固定し、ロックファイル更新と一緒に
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 と .npm/_cacache の 7 日 TTL 掃除も。
launchd 前の doctor ゲート
doctor JSON をリリース成果物として diff。新規警告がオーナーなしで 2 件超なら却下。カットオーバー記事 と併用。
FAQ
--force？ 捨てクローンのみ。共有リースでは禁止。
HK と US の Node は？ help の同じ LTS マイナーに揃える。
MacLogin が消してくれる？ 緊急リセットはあるが日常は自前 runbook でピンを守る。
npm overrides はいつ --legacy-peer-deps より安全か？ overrides はレビューされバージョン管理され git blame で見える。legacy のフラグはシェル履歴に潜み、次のエンジニアが素の npm install をすると消える——使い捨てディレクトリ以外では共有レンタルミニで禁止が無難。
Mac mini M4 が速い理由
M4 は npm 展開が速く、再インストール中も TS 言語サーバを暖かく保てる。多地域フリートで tarball の地理歪みを減らし、ディスクが詰まったら pricing で大型ミニへ。
