Operators installing OpenClaw on headless NodeMac Mac mini M4 hosts often see the CLI succeed while the gateway LaunchAgent exits after a Homebrew Node upgrade. This 2026-05-21 matrix maps install-failure symptoms to root causes, compares bundled versus Homebrew Node runtimes, lists eight reproducible alignment steps, and includes FAQ answers you can paste into incident tickets.
Upstream installers can place Node.js under ~/.openclaw/tools/node/bin/node, while your SSH session may resolve /opt/homebrew/bin/node first. The gateway daemon started by launchd label ai.openclaw.gateway inherits yet another PATH. When those three binaries diverge, native add-ons load in the CLI but fail under the daemon—exactly the class of bugs reported against gateway install ignoring bundled Node on clean macOS hosts in 2026.
Install failures that look like “OpenClaw is broken” but are PATH drift
- CLI healthy, gateway down:
openclaw doctorpasses in SSH butlaunchctl print gui/$(id -u)/ai.openclaw.gatewayshows exit code 78 afterbrew upgrade node. - Version triple mismatch:
node -vprints v24.x in SSH, plist points at v22.19, bundled tools report another patch level. - npm EACCES on install:
npm i -g openclawfails with permission errors because global prefix is not writable for the service user. - Missing git on clean macOS: npm install aborts because git is required to fetch dependencies—common on fresh NodeMac images before baseline packages are applied.
Start from the headless onboard and daemon acceptance checklist if this is a first install. For region and SSH/VNC placement, see the 2026-05-19 region and SSH/VNC runbook. Deep diagnostics live in OpenClaw doctor and health diagnostics. Account setup: help center and pricing.
Symptom → cause → fix matrix (copy into runbooks)
Use this table during live incidents on leased Mac mini M4 nodes. Each row ends with a command you can run over SSH without opening VNC.
| Symptom | Likely cause | First fix (SSH) | Verify |
|---|---|---|---|
| npm EACCES | Global prefix not writable | npm config set prefix ~/.npm-global |
which openclaw |
| Gateway exit 78 | Plist node ≠ CLI node | Edit ~/Library/LaunchAgents/ai.openclaw.gateway.plist ProgramArguments node path |
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway |
| doctor warns Node | Below 22.19 | Install Node 22 via installer or pin bundled path | node -v ≥ 22.19 |
| npm install failed | git missing | xcode-select --install or brew install git |
git --version |
| Health timeout | Socket up, plugins crash | Tail ~/.openclaw/logs/gateway.log |
Health call 3000 ms OK |
Runtime source comparison: which Node should own the gateway?
Pick one primary runtime per host and document it in your fleet registry. Mixing sources without explicit plist paths is the dominant failure mode on headless Mac mini M4 leases in 2026.
| Runtime source | Typical path | Pros on NodeMac | Cons |
|---|---|---|---|
| Bundled (install-cli) | ~/.openclaw/tools/node/bin/node |
Matches upstream test matrix; survives brew churn | Easy to ignore if plist still points at Homebrew |
| Homebrew node@22 | /opt/homebrew/opt/node@22/bin/node |
Familiar to macOS admins; fast security patches | brew upgrade can desync gateway |
| User npm-global | ~/.npm-global/bin/openclaw |
Fixes EACCES without sudo | launchd must inherit PATH exports explicitly |
Eight-step alignment procedure (reproducible over SSH)
- Snapshot three Node paths: Run
which node; node -v; plutil -extract ProgramArguments xml1 -o - ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>/dev/null | headand paste into the ticket. - Run doctor first: Execute
openclaw doctor(add fix flags only after reading the report). - Pin Node ≥ 22.19: Install or select Node that meets upstream minimum; block accidental major downgrades.
- Fix npm prefix: For EACCES, set
npm config set prefix ~/.npm-globaland export PATH in~/.zprofilefor the service user. - Align plist node path: Point the first ProgramArguments entry at the chosen node binary; run
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plistthen bootstrap again. - Re-onboard daemon: Run
openclaw onboard --install-daemonfrom the same shell PATH you intend to keep. - Health probe: Call loopback health with 3000 ms timeout; archive output next to host serial.
- CMDB guardrail: Record chosen runtime source (bundled / brew / npm-global) and forbid brew upgrade windows without a gateway smoke test.
Business workflow note: Support teams routing Slack tickets through OpenClaw on a Singapore Mac mini M4 still fail if Node paths drift—fix runtime alignment before tuning model prompts. Stable gateway uptime matters more than shaving 50 ms on inference once messages queue behind a crashed daemon.
FAQ: OpenClaw Node.js PATH on Mac mini M4
Should I prefer bundled Node or Homebrew?
Prefer bundled Node on production gateways if you want install-cli and launchd to stay on the same binary. Use Homebrew only when you explicitly pin the plist path after every brew upgrade.
Will VNC help with npm install errors?
Rarely. PATH and permission fixes are SSH tasks. Use VNC only for macOS privacy prompts that block automation helpers—not for npm EACCES.
What numbers belong in the runbook appendix?
Record Node semver, npm prefix path, plist node absolute path, health timeout 3000 ms, and last successful openclaw doctor hash so the next on-call does not re-debate versions.
Fixing OpenClaw install paths on NodeMac is faster when you treat the Mac mini M4 as a long-lived gateway appliance, not a disposable laptop. Apple Silicon M4 delivers unified memory for Node-heavy tool chains; native macOS matches OpenClaw’s platform assumptions; SSH and VNC let you align plist and shell environments without shipping hardware. Leasing in Hong Kong, Japan, Korea, Singapore, or the United States places gateways near Slack and LLM APIs while avoiding capex, and dedicated metal prevents neighbor noise from masquerading as “random npm failures.” Compare monthly node cost on the pricing page before you burn another day on mismatched Node binaries.