AI / Automation 2026年4月22日

2026-04-22 OpenClaw npm アップグレード、ステールモジュール参照とヘッドレスのレンタルクラウド Mac 上のゲートウェイ再起動

MacXCode エンジニアリングチーム 2026年4月22日 約17分で読めます

レンタルの Apple Silicon Mac で グローバル npm として OpenClaw を運用する担当者は、アップグレード後にこんな混乱をよく見る：openclaw --version は新しい semver を示すのに、ゲートウェイは古いモジュールを読み込む—Webhook が不安定、チャネルのハートビートが欠け、ログに混在パスが出る。本2026-04-22稿は 先に停止する更新、コミュニティのステール Node 解決報告に沿った二重启動緩和、そして ゲートウェイ更新とロールバック と組み合わせるロールバックをまとめる。オンボードと install-daemon（初回起動）と 環境と秘密情報（状態パス）を補完する。

ログに残すべきステールモジュールの兆候

npm グローバルを変更する前に証拠を残す—深夜 2 時にデバッグする未来の自分が感謝する。

兆候 解釈 取得コマンド
ゲートウェイログに 2 つの semver バイナリは新しいがワーカーが旧ツリーを import journalctl/stdout を保存 + which openclaw
更新後の断続的な ESM import エラー 混在した node_modules 解決パス npm ls -g openclaw --all + ゲートウェイ環境ダンプ
1 回目は健全だがトラフィックが異常 モジュールキャッシュ排出のため 2 回目が必要 127.0.0.1 へのタイムスタンプ付きヘルス curl
リスクの数値化：変更ログに少なくとも直近 3 つの npm semver を残し、リスクの高い更新では地域間で 2 台の健全なゲートウェイを維持し、混雑ホストでは npm + ゲートウェイ循環に 8〜22 分のメンテ窓を見込む。

プリフライトのスナップショットとバックアップ

  1. openclaw --version と node -v を記録（上流推奨 Node 22.16+ または 24.x）。
  2. ~/.openclaw を npm グローバルツリーの外の日付付きパスに tarball — ゲートウェイのロールバックと同じバックアップ規律。
  3. オンボードでカスタマイズした launchd plist パスをエクスポート。
  4. launchd 環境のメモで OPENCLAW_STATE_DIR と秘密情報の優先順位を確認。

停止 → 更新 → 再起動（順序が重要）

ゲートウェイがトランスパイル済みモジュールのファイルロックを保持している間に npm でグローバルを書き換えない。先に停止し、更新し、再起動する—macOS 上の任意の Node デーモンと同じ本番手順。

openclaw gateway stop && npm install -g openclaw@latest && openclaw gateway start

先に doctor：重複 LaunchAgents の警告が出たら更新前に plist の散乱を直す—さもないと誤ったプロセスツリーを再起動する。

ステールモジュール向けの二重ゲートウェイ再起動

ヘルスチェックにまだバージョン混在が出る場合、2 回目のクリーン再起動を行う：停止し、ソケット排出を待ち、起動し、ローカルプローブを再実行。npm グローバル更新で Node が 2 回目のコールドスタートまで stale 解決を保持するという公開議論の緩和と一致する。再起動の間に nginx アップストリームを早合点で切り替えない—HK / JP / KR / SG / US のトラフィックを再公開する前に ヘルスプローブに従う。

再起動の間に見るもの

静かなウィンドウで待受ポート（ゲートウェイポートに絞った lsof -nP -iTCP -sTCP:LISTEN）を取得し、孤児の node 子が残っていないこと、グローバル npm 接頭辞のボリュームの inode 圧力を確認する。この確認を飛ばすチームは 1 回目で「成功」しても混合モジュールを配信し続ける—長寿命ワーカーが SIGTERM を生き延びたため。タイムスタンプを残す：混雑ホストでは stop と start の間に少なくとも 45〜90 秒、同じパスをアンチウイルスやインデックスが奪い合う場合は 120 秒を推奨—共有ビルド機ではよくある。

アプリログとシステム負荷を相関させる：ゲートウェイ再起動中に load average がコア数の 4 倍を超え続けるなら CPU が落ち着くまで入口再開を遅らせる—さもないと npm と無関係な理由でヘルスが不安定になる。チャットブリッジでは各再起動後にステージング webhook で合成 noop を送り、本番 DNS に昇格する前に E2E を証明する。

最後にnpm グローバルルート（npm root -g）と解決されたバイナリ（which openclaw）をチケットにスナップショット—semver が分岐したとき、この 2 パス比較で symlink ドリフトを早期捕捉する。複数リージョンを借りる担当者はホストごとに同じチェックリストを繰り返すこと。JP と US でグローバル接頭辞が食い違うと、アップグレード後に「片方の DC だけ動く」報告の典型原因になる。

ヘルス、ログ、入口の再有効化

2 回目のバウンス後に検証：

ネガティブテストで検証を拡張する：サンドボックス agent で意図的に下流トークンを壊し、エラー表示が新ビルドの文字列テンプレートと一致するか確認—混合 semver は明示バナーではなく微妙に違うエラーコピーで先に現れることが多い。変更後 15 分は少なくとも5 つのベースライン（p50/p95、エラー率、キュー深度、CPU、RSS）を残し、更新前チャートと比較する。履歴がなければ npm を触る前にダッシュボードを用意する。

semver が収束しないときのロールバック

二重启動でも失敗する場合、npm で最後の良好な semver を再インストールし、~/.openclaw の tarball を復元し、ゲートウェイ起動シーケンスを再生する。サポートスレ向けに npm と OpenClaw の両バージョンを記録する。復旧中のメッシュアクセスは Tailscale メッシュ。

シナリオ ロールバックの焦点 想定時間
npm のパッチ回帰 npm で前のパッチに固定 6–12 min
更新後の設定ドリフト tarball 復元 + JSON schema 検証 12–25 min
リージョン全体の障害 2 台目の MacXCode ノードへフェイルオーバー DNS/TTL 依存

更新後のチャネル問題は サブエージェントとチャネルのトラブルシュートと重なることがある。スキルのパッケージングは別—スキル移行を含む更新なら Skills と ClawHub を参照。

FAQ：npm とクラウド Mac のゲートウェイ

質問 回答
pnpm は？ 組織が pnpm を標準化しているなら同じ先停めの規律を踏襲し、PATH でグローバル接頭辞を明確に。
Docker にすべき？ Docker とネイティブ npmのトレードオフを比較—どちらも可だが本文はベアメタル租用向け。
継続的なヘルス監視は？ ヘルプのサポートチャネルを使い、本番ガイドに沿った合成プローブを維持。

OpenClaw npm アップグレードの定常ホストとしての Mac mini M4

Mac mini M4 ベアメタルは Node ゲートウェイのコールドスタート時間が決定的—意図的に二回バウンスする場合に重要。過剰割当 VM と比べ “CPU steal” のように見える幽霊症状を追う時間が減る。MacXCode の SSH 優先アクセス（HK · JP · KR · SG · US）、ワークスペース向け任意の 1〜2TB NVMe、予測可能なネットワークがブルー/グリーン用の重複ゲートウェイを簡素化。npm の変動が加速したら 料金から容量を足し、疲れた 1 台に実験を積まない。

専用 M4 ゲートウェイで OpenClaw を実行

SSH · マルチリージョン · エージェント向け