openclaw - 💡(How to fix) Fix openclaw update leaves gateway down + unbootable on split Homebrew/nvm installs [1 comments, 2 participants]

Summary

openclaw update on macOS with a split Homebrew/nvm install (OpenClaw installed under /opt/homebrew/lib/node_modules/openclaw, but PATH-resolved npm belongs to nvm at ~/.nvm/versions/node/<v>/bin/npm) leaves the gateway service completely down and unbootable via launchctl. The update appears to "hang" or finish silently without actually updating, and the user is then locked out of launchctl until they manually run launchctl enable + load -w.

This happens because three bugs combine:

Bug 1: launchctl bootout writes a "disabled" override

After the update's stop step runs launchctl bootout gui/<uid>/ai.openclaw.gateway, the service appears in launchctl print-disabled gui/<uid> as:

"ai.openclaw.gateway" => disabled

Every subsequent launchctl bootstrap / load then fails with the cryptic:

Bootstrap failed: 5: Input/output error

The fix is launchctl enable gui/<uid>/ai.openclaw.gateway before bootstrap. The update script's restart logic at dist/update-cli-CycY__x8.js:584-587 already does this, but only if the script reaches that point.

Bug 2: npm install no-ops/hangs on split Homebrew/nvm prefix

When npm prefix -g resolves to nvm's path (~/.nvm/...) but OpenClaw is installed at Homebrew's path (/opt/homebrew/lib/node_modules/openclaw), the spawned npm install -g openclaw@<tag> either:

• silently no-ops (npm checks the nvm path, sees no openclaw, exits 0 without installing anywhere)
• or installs a fresh copy under the nvm path, leaving the Homebrew copy stale (and the LaunchAgent plist still points to /opt/homebrew/bin/node + /opt/homebrew/lib/.../openclaw/dist/index.js)
• or hangs indefinitely

The detected package root (installTarget.packageRoot in update-cli) correctly identifies /opt/homebrew/lib/node_modules/openclaw, but the install command isn't passing --prefix /opt/homebrew to override npm's global resolution.

Bug 3: Service never restarts if npm step fails/hangs

The restart logic at update-cli-CycY__x8.js:1968 (maybeRestartService) is downstream of the npm install. If the npm step hangs or errors, recovery never runs and the gateway is left bootout'd + disabled.

Reproduction

1. Install OpenClaw via Homebrew npm at /opt/homebrew/lib/node_modules/openclaw
2. Have nvm installed and on PATH such that which npm resolves to ~/.nvm/.../bin/npm (extremely common — nvm puts itself early in PATH)
3. Run openclaw update

Symptoms:

• Output shows "Stopping managed gateway service before package update..." then "Stopped LaunchAgent (degraded)"
• Process appears to hang or exits silently
• Gateway is now down: launchctl list | grep openclaw returns nothing
• Manual launchctl bootstrap or launchctl load returns 5: Input/output error
• cat /opt/homebrew/lib/node_modules/openclaw/package.json | grep version shows the same version as before

Recovery procedure (until fixed upstream)

launchctl enable gui/$(id -u)/ai.openclaw.gateway
launchctl load -w ~/Library/LaunchAgents/ai.openclaw.gateway.plist
sleep 3
curl -s http://localhost:18789/health   # should return {"ok":true,"status":"live"}

To actually update OpenClaw, run npm with explicit prefix:

npm install -g openclaw@latest --prefix /opt/homebrew

Suggested fix

1. Pass --prefix (or -C <packageRoot>) to the spawned npm install so it targets the detected install location regardless of npm's default global prefix. The packageRoot is already detected; just thread it into the install command.

2. Wrap the entire update flow in a try/finally that always restarts the service even on failure. Currently a failed/hung npm install leaves the user with a bootout'd, disabled service.

3. Run launchctl enable before launchctl bootout OR run it as part of the restart fallback. The script's bootstrap-after-bootout already has this at line 585 but it depends on the kickstart-first path failing — which it does, but only after the npm install has failed first.

4. Detect the split-prefix condition early and either (a) error out with a clear message + recovery command, or (b) explicitly use the resolved packageRoot's npm.

Environment

• macOS 26.3 (Darwin 25.3.0, arm64)
• OpenClaw 2026.4.29
• npm via nvm (Node 22.22.0)
• OpenClaw installed at /opt/homebrew/lib/node_modules/openclaw (Homebrew npm)