在无头 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 二进制不匹配再浪费一天之前，请先在定价页对比月度节点成本。