OpenClaw ゲートウェイの npm ci、package-lock.json、再現可能インストール、およびクリーンリビルド規律（レンタル クラウド Mac、2026-05-09）

2026 年のコミュニティ issue では同じ失敗パターンが繰り返されます：ゲートウェイがファイルハンドルを握ったままの状態で npm install -g openclaw@latest を実行し、リネーム途中のツリー、不足したプラグイン実行時依存、Telegram ポーリングを飢えさせる再起動ループが残る。 香港、日本、韓国、シンガポール、米国から自動化を出荷する MacLogin テナントは、ゲートウェイを他の本番バイナリと同様に扱うべきです：ロックファイルをコミットし、npm ci 相当で導入し、先に launchd を止め、モジュール解決キャッシュが嘘をつくときの二重再起動緩和をリハーサルする。 本 2026年5月ランブックは行列、停止順序、9 ステップの CI、可観測性チェック、FAQ をまとめ、Apple Silicon リース上で OpenClaw を予測可能に保ちます。

併読：ピア依存ドリフトとクリーンリビルド、doctor 診断、macOS アプリと CLI のハンドオフ。ハブ：OpenClaw トピック索引。ヘルプ、料金、VNC（GUI 検証用）。

OpenClaw が「CLI だけ」と感じてもロックファイルが効く理由

ゲートウェイはトランスポート、プラグイン、モデルアダプタの推移依存を束ねます。グラフを固定しないと semver 範囲が同一でもレジストリ公開のあとに二台が静かに分岐します—再現可能 CI が潰したい悪夢そのものです。

npm ci 対 npm install（意思決定行列）

コマンド	ゲートウェイで使う場面	省略時のリスク
npm ci	CI イメージ、新規ワークスペース、リビルドパイプライン	決定的インストール、ロック／package 不一致で即失敗
npm install	ロックファイルを意図的に変える探索的アップグレード	再コミットしなければ JP と US ノードがドリフト
npm install --package-lock-only	スクリプトを実行せずロックだけ更新する PR 準備	推移バンプのレビューは依然必要

ゲートウェイ版とともに Node.js と npm を固定する

三つ組 (node -v, npm -v, openclaw --version) を CMDB に記録します。Volta、asdf、MacPorts のピンを ヘッドレス導入と Node 前提の揃え方に沿って揃え、CI とリース mini が同じエンジンを評価するようにします。

npm グローバルパスに触る前の launchd 停止順序

1. launchctl bootout gui/$UID/ai.openclaw.gateway（plist のラベルに合わせて調整）。
2. pgrep -fl openclaw で子 node が残っていないことを確認。
3. その後にのみ npm の変更を実行。

doctor が部分ツリーを報告するときのクリーンリビルド手順

ピアドリフト記事の精神に従い、node_modules を削除し、npm ci で再導入し、openclaw doctor を再実行して標準出力をサポートバンドルに含めます。グローバル導入では壊れた prefix パスを消してからクリーン再導入するコミュニティ回避策を踏襲します。

ゲートウェイ更新向け 9 ステップ CI ランブック

1. スナップショット：現行 plist、チェックサム、ヘルス JSON。
2. ブランチ：セマンティック版タグ付きで Git にロック更新。
3. ビルド：npm ci を使う短命 CI macOS ランナー。
4. テスト：doctor、合成 webhook、モデル ping。
5. ステージ：不変バージョンでオブジェクトストレージへ成果物。
6. 停止：launchd 方針どおり本番ゲートウェイを止める。
7. インストール：ステージした成果物から（浮動 latest ではない）。
8. ブートストラップ：ヘルスがフラップするなら二回（二重再起動緩和）。
9. 投稿：リリースノートとロールバック tarball の場所。

古いモジュール解決に対する二重再起動緩和

ヘルスは通るのに実行時が古いハッシュを参照するときは、短いスリープのあと即座に 2 回目の launchctl kickstart -k を予定します。症状を文書化し TLS やプロキシ障害と混同しないでください。

交差リンク：ピアドリフト記事と本ロックファイル記事

ピアドリフトガイドは依存グラフが爆発する側に焦点を当てます。本稿は固定する側です。日次ビルドはロック、緊急リビルドは上流が衝突するピアを公開したあとにドリフト記事を使います。

リージョン横断ゲートウェイ展開の成果物キャッシュ

香港と米西海岸のテナントが同じ時間帯に上げると、公開レジストリから同一 tarball を二度引き、レート制限とジターを招きます。不変アーティファクトを自社オブジェクトストレージ（S3 互換、Artifactory、GitHub Release アセット）へ昇格させ、各リースがコンテンツアドレス URL で取得するようにします。監査のため package-lock.json の git SHA とともに変更チケットに SHA256 を記録し、JP と SG ノードが同一バイトを実行したことを証明します。

リージョン	推奨キャッシュ	フォールバック
HK / SG	APAC バケットレプリカ	インストール同時実行を分あたり 2 に制限
JP / KR	東京隣接エッジキャッシュ	夜間ウィンドウでの導入を優先
US	米東プライマリ＋西ミラー	tarball キャッシュ時は npm ci --prefer-offline

FAQ

install.sh フローはまだ使えるか？ curl ブートストラップに限定し、繰り返し運用はコミット済みロックへ移行してください。

エアギャップは？ npm pack 出力でベンダ tarball を用意し、npm ci --offline の前に SHA256 を検証。

隔離ゲートウェイはどこで借りるか？ 騒がしいアップグレードを分離するなら JP と US プールを 料金で比較。

Dependabot が OpenClaw バンプを自動マージしてよいか？ doctor・webhook エコー・プラグイングラフを回すゲート付き CI がある場合のみ—そうでなければ週次の人間レビューが勝ちます。

OpenClaw ハブ、ヘルプ、リージョンキャパシティ

ロックファイル方針を OpenClaw ハブの内部節に掲載し、全リージョンが同じ停止順チェックリストを継承するようにしてください。ソウルがシンガポールと別プラグイン集合を要するなら 1 つのロックグラフで争わずリースを分割します。