在無頭 NodeMac Mac mini M4 主機上安裝 OpenClaw 時，維運人員常遇到 CLI 正常而閘道在 Homebrew Node 升級後 LaunchAgent 退出的情況。本 2026-05-21 矩陣將安裝失敗症狀對應到根因，比較內建與 Homebrew Node 執行階段，列出八步可重現對齊流程，並提供可直接貼進事故單的 FAQ 答案。
上游安裝器可能將 Node.js 放在 ~/.openclaw/tools/node/bin/node，而 SSH 工作階段可能優先解析 /opt/homebrew/bin/node。launchd 標籤 ai.openclaw.gateway 啟動的閘道守護程序又繼承另一套 PATH。當這三處二進位不一致時，原生外掛在 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： npm install 因拉取相依性需要 git 而中止——在基線軟體套件尚未套用的全新 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 |
健康呼叫 3000 ms 通過 |
執行階段來源比較：哪個 Node 應擁有閘道？
每台主機選定一個主執行階段並在機隊登錄表中記錄。2026 年無頭 Mac mini M4 租賃環境中最常見的失敗模式，是在未明確指定 plist 路徑的情況下混用多種來源。
| 執行階段來源 | 典型路徑 | 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 匯出 |
八步對齊流程（可透過 SSH 重現）
- 快照三條 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。 - 對齊 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。僅在每次 brew upgrade 後明確固定 plist 路徑時才使用 Homebrew。
VNC 對 npm 安裝錯誤有幫助嗎？
很少。PATH 與權限修復是 SSH 任務。僅在 macOS 隱私提示阻止自動化助手時使用VNC——npm EACCES 不需要 VNC。
runbook 附錄應記錄哪些數字？
記錄 Node semver、npm prefix 路徑、plist node 絕對路徑、健康逾時 3000 ms，以及最近一次成功的 openclaw doctor 雜湊，以免下一班值班再次爭論版本。
在 NodeMac 上修復 OpenClaw 安裝路徑，更快的方式是把 Mac mini M4 當作長期運行的閘道設備，而非一次性筆電。Apple Silicon M4 的統一記憶體適合 Node 密集型工具鏈；原生 macOS 符合 OpenClaw 的平台假設；SSH 與 VNC 讓你無需寄送硬體即可對齊 plist 與 shell 環境。在香港、日本、韓國、新加坡或美國租賃可將閘道靠近 Slack 與大模型 API，同時避免資本支出；專屬實體機也能防止鄰居雜訊偽裝成「隨機 npm 失敗」。在因 Node 二進位不匹配再浪費一天之前，請先在定價頁比較月度節點成本。