ヘッドレス NodeMac Mac mini M4 ホストに OpenClaw を入れると、CLI は成功するのに Homebrew Node アップグレード後にゲートウェイ LaunchAgent が終了する、という現象がよく起きます。本 2026-05-21 マトリクスはインストール失敗の症状を根本原因にマッピングし、同梱と Homebrew Node ランタイムを比較し、8 ステップの再現可能な整合手順と、インシデントチケットに貼れる FAQ 回答を提供します。
上流インストーラは Node.js を ~/.openclaw/tools/node/bin/node に置く一方、SSH セッションは /opt/homebrew/bin/node を先に解決することがあります。launchd ラベル ai.openclaw.gateway で起動するゲートウェイデーモンは別の PATH を継承します。この 3 つのバイナリがずれると、CLI ではネイティブアドオンが読み込めるのにデーモン下では失敗する—2026 年のクリーン macOS ホストでゲートウェイインストールが同梱 Node を無視すると報告されるまさにそのクラスの不具合です。
「OpenClaw が壊れた」ように見えるが実は PATH ドリフトのインストール失敗
- CLI は正常、ゲートウェイダウン： SSH で
openclaw doctorは通るが、brew upgrade node後launchctl print gui/$(id -u)/ai.openclaw.gatewayが終了コード 78 を示す。 - バージョン三重不一致： SSH の
node -vが v24.x、plist が v22.19、同梱ツールが別パッチレベルを報告。 - インストール時 npm EACCES：
npm i -g openclawがグローバル prefix がサービスユーザーに書き込めないため権限エラー。 - クリーン macOS に git なし： 依存取得に git が必要で npm install が中断—ベースラインパッケージ適用前の新規 NodeMac イメージでよくある。
初回インストールならヘッドレス onboard とデーモン受け入れチェックリストから始めてください。リージョンと SSH/VNC 配置は2026-05-19 リージョン・SSH/VNC 手順書を参照。詳細診断はOpenClaw doctor とヘルス診断。アカウント設定：ヘルプセンターと料金。
症状 → 原因 → 修正マトリクス（runbook にコピー可）
リース Mac mini M4 ノードでのライブインシデント時に本表を使用してください。各行末尾は VNC なしで SSH から実行できるコマンドです。
| 症状 | 想定原因 | 第一修正（SSH） | 検証 |
|---|---|---|---|
| npm EACCES | グローバル prefix が書き込み不可 | npm config set prefix ~/.npm-global |
which openclaw |
| ゲートウェイ終了 78 | Plist node ≠ CLI node | ~/Library/LaunchAgents/ai.openclaw.gateway.plist の ProgramArguments node パスを編集 |
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway |
| doctor が Node を警告 | 22.19 未満 | インストーラで Node 22 を入れるか同梱パスを固定 | node -v ≥ 22.19 |
| npm install 失敗 | git 不足 | xcode-select --install または brew install git |
git --version |
| ヘルスタイムアウト | ソケットは起動、プラグインクラッシュ | ~/.openclaw/logs/gateway.log を tail |
ヘルス呼び出し 3000 ms OK |
ランタイムソース比較：どの Node がゲートウェイを所有すべきか
ホストごとに 1 つの主ランタイムを選び、フリートレジストリに記録してください。plist パスを明示せずソースを混在させることが、2026 年のヘッドレス Mac mini M4 リースで支配的な失敗モードです。
| ランタイムソース | 典型パス | NodeMac での利点 | 欠点 |
|---|---|---|---|
| 同梱（install-cli） | ~/.openclaw/tools/node/bin/node |
上流テストマトリクスと一致；brew 変動に強い | plist が Homebrew を指すと無視されやすい |
| Homebrew node@22 | /opt/homebrew/opt/node@22/bin/node |
macOS 管理者に馴染み；セキュリティパッチが速い | brew upgrade でゲートウェイがずれる |
| ユーザー npm-global | ~/.npm-global/bin/openclaw |
sudo なしで EACCES を修正 | launchd が PATH export を明示継承する必要 |
8 ステップ整合手順（SSH で再現可能）
- 3 つの Node パスをスナップショット：
which node; node -v; plutil -extract ProgramArguments xml1 -o - ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>/dev/null | headを実行しチケットに貼付。 - まず doctor：
openclaw doctorを実行（レポート確認後に fix フラグを追加）。 - Node ≥ 22.19 を固定： 上流最小要件を満たす Node をインストールまたは選択；意図しないメジャーダウングレードをブロック。
- npm prefix を修正： EACCES 時は
npm config set prefix ~/.npm-globalとサービスユーザーの~/.zprofileで PATH export。 - plist node パスを揃える： ProgramArguments 先頭を選んだ node バイナリに；
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist後に再 bootstrap。 - デーモンを再 onboard： 維持する shell PATH と同じ環境で
openclaw onboard --install-daemonを実行。 - ヘルスプローブ： 3000 ms タイムアウトでループバック health を呼び出し；出力をホストシリアルと共にアーカイブ。
- CMDB ガードレール： 選んだランタイムソース（同梱 / brew / npm-global）を記録し、ゲートウェイスモークテストなしの brew upgrade ウィンドウを禁止。
業務ワークフロー注記： シンガポール Mac mini M4 上の OpenClaw で Slack チケットをルーティングするサポートチームも、Node パスがずれると失敗します—モデルプロンプト調整の前にランタイム整合を直してください。クラッシュしたデーモンの後ろにメッセージがキューイングされるとき、推論で 50 ms 削るより安定したゲートウェイ稼働時間の方が重要です。
FAQ：Mac mini M4 上の OpenClaw Node.js PATH
同梱 Node と Homebrew、どちらを優先？
install-cli と launchd を同一バイナリに保ちたい本番ゲートウェイなら同梱 Node を優先。Homebrew は各 brew upgrade 後に plist パスを明示固定する場合のみ。
VNC は npm インストールエラーに役立つ？
ほとんど不要。PATH と権限修正は SSH 作業。macOS プライバシープロンプトが自動化ヘルパーをブロックするときだけVNC—npm EACCES には不要。
runbook 付録に記録すべき数値は？
Node semver、npm prefix パス、plist node 絶対パス、ヘルスタイムアウト 3000 ms、最後に成功した openclaw doctor ハッシュを記録し、次のオンコールがバージョン議論を繰り返さないように。
NodeMac で OpenClaw インストールパスを直すには、Mac mini M4 を使い捨てノート PC ではなく長寿命ゲートウェイアプライアンスとして扱う方が速いです。Apple Silicon M4 のユニファイドメモリは Node ヘビーなツールチェーンに適し、ネイティブ macOS は OpenClaw のプラットフォーム前提と一致します。SSH と VNC でハードウェアを送らず plist とシェル環境を揃えられます。香港・日本・韓国・シンガポール・米国でリースすれば Slack と LLM API に近いゲートウェイを置き、capex を避けられます。専用メタルは「ランダムな npm 失敗」に化けた隣接ノイズも防ぎます。Node バイナリ不一致でもう 1 日無駄にする前に料金ページで月額ノードコストを比較してください。