OPENCLAW 2026
POST_INSTALL_
GATEWAY_
PATH_FORCE.

After npm install -g openclaw or the official installer, many operators see no hard error—yet openclaw ask hangs, openclaw-gateway: command not found appears, or openclaw gateway status shows the gateway binary never registered. That is not a model outage first; it is a PATH / registration / Node 22 runtime split problem. This runbook gives a symptom-evidence-action matrix, a five-step cold-start checklist, numeric gates, and FAQ. Cross-read the MACGPU posts on install.sh to production, LaunchAgent gateway token, Chrome Relay 18792, and v2026.5.x layered ops. For a clean Apple Silicon control plane, replay the same steps on a dedicated remote Mac.

1. Pain decomposition

First, npm global prefix drift: binaries land under ~/.npm-global/bin or nvm shims while the shell PATH never loads them, so openclaw may resolve while openclaw-gateway does not. Second, gateway registration was skipped: the CLI prints help but no listener exists. Third, multiple Node installs: install scripts ran under Node A, operators run under Node B. Fourth, remote Mac launchd uses a minimal environment unlike your interactive SSH session—human login works, unattended launch fails. None of these should be diagnosed as API throttling until the base layer is green.

2. Symptom-evidence matrix

Signal	Primary suspect	Evidence
openclaw-gateway: command not found	PATH / prefix	which openclaw, npm prefix -g, echo $PATH
gateway status says not installed	missing registration	before/after openclaw gateway install --force
interactive OK, launchd fails	plist env	EnvironmentVariables, launchctl print
only on remote Mac	non-login shell	ssh -t, profile parity, whoami

3. Five-step first-run runbook

Step 1 Freeze the runtime triple

Record node -v (must satisfy 22+), npm -v, and the absolute path from which node. No vague “it works in my terminal” statements in tickets.

Step 2 Validate prefix and PATH

Run npm config get prefix, ensure global bin is in zshrc/bashrc. If you ever used sudo npm, stop: split ownership will poison later diagnosis.

Step 3 Register the gateway explicitly

Run openclaw gateway install in a maintenance window; if metadata is stale, use --force and align tokens with the LaunchAgent article.

Step 4 Ports and health semantics

Map default listeners to your exact version docs, then separate loopback checks from SSH-forwarded checks using the Chrome Relay runbook so you do not blame providers for a dead local listener.

Step 5 Cold restart and log slice

Fully stop the gateway, start clean, export openclaw logs for install/register/first-ask windows as separate attachments.

4. Three hard gates

Gate A: which openclaw-gateway must be non-empty and co-located with the CLI prefix tree before declaring success. Gate B: no production channel traffic until openclaw gateway status matches documented healthy signals. Gate C: no reliance on laptop tunnels until non-interactive launchd cold start passes on the remote Mac.

5. Case study: four hours blaming the wrong layer

A small team deployed OpenClaw on a remote Mac mini for 24/7 work in May 2026. Daytime SSH sessions sourced nvm and npm prefixes, so manual checks looked perfect. Overnight, launchd children inherited a minimal PATH, pointed at an older system Node, and the gateway unit never stayed up. They tuned model names and rebuilt workspaces until the matrix in this article forced a which audit and plist rewrite: Node 22 absolute path, explicit PATH entries, openclaw gateway install --force, then channels probe from the install.sh article. First-token latency stabilized and tickets now require cold-start evidence. The lesson: split interactive shell truth from launchd truth before opening provider dashboards.

The v2026.5.x layered ops article still assumes a healthy base layer. If plugins and startup semantics shift, PATH and registration remain the foundation; shaky foundations only amplify TTS and channel noise.

6. Industry view

Agent stacks in 2026 ship CLI, gateway, and plugins as independently versioned units. A single successful npm install no longer implies a closed runtime loop. Teams still using 2024-era “install then immediately ask” scripts will keep paying tuition on multi-user and remote launchd hosts. The cheaper lever is an auditable checklist, maintenance-window cold starts, and a gold Apple Silicon node with fewer variables than a mixed Windows/Linux/Mac lab.

Windows and Linux gateways are viable, but desktop session and browser-tooling variables climb fast. When you must prove “gateway never registered” versus “network jitter,” a remote Apple Silicon host with clean prefix, writable logs, and stable power is the fastest second site. If you want that control plane without buying hardware, rent a MACGPU remote Mac and bake this runbook into your release template.

Linux or Windows can be a dev sandbox, yet macOS remains the lowest-friction reference plane for several OpenClaw workflows. The recommendation is technical: fewer moving parts during base-layer certification, not brand absolutism.

7. Numeric thresholds

Cold start to healthy openclaw gateway status beyond 90s triggers an architecture review (disk scan, AV hooks). First local-loop openclaw ask probe beyond 25s without a reply must inspect gateway before models. More than two gateway install --force attempts in one window require a human diff—avoid scripted thrash. LaunchAgent PATH entries: treat fewer than three critical paths (node, npm-global bin, openclaw) as a default-fail configuration until documented otherwise.

Add disk gates: if log paths point to read-only volumes or network mounts, installers may report success while the service crashes in a loop. Serialize global npm/pnpm installs during maintenance to prevent races where which flips between engineers on a shared automation account.

8. FAQ

Doctor is green—skip which? No. Doctor validates config semantics; which validates executable visibility in the same shell. Token mismatch vs missing gateway? Tokens show 401-style auth signals; missing binaries show process-absent signals—use the token article after ruling out base layer. sudo npm? Avoid; it splits prefixes. Relay red while gateway green? Use the Chrome Relay article; do not reinstall the OS.

Mix install.sh with raw npm? Risky double metadata—pick one path per machine. Minimal remote change? plist PATH plus absolute Node plus fixed stdout/stderr paths. Still failing after five steps? Open WebSocket handshake and v2026.5.x layered docs, but keep this article’s attachments as foundation evidence.