Gateway LaunchAgent Silently Crashes After pnpm Update Due to Entrypoint Path Mismatch

Following a pnpm update of OpenClaw, the Gateway service exhibits the following symptoms:

• openclaw status reports the gateway as running with an active PID and state.
• openclaw gateway probe returns Connect: failed - timeout, indicating the gateway is unreachable.
• tail -20 ~/.openclaw/logs/gateway.log shows no startup entry for the current session.
• No user-visible error, warning, or crash notification is displayed.
• openclaw doctor emits a warning: Gateway service entrypoint does not match the current install. (/dist/entry.js → /dist/index.js)
• Additionally, openclaw doctor warns: Gateway service embeds OPENCLAW_GATEWAY_TOKEN and should be reinstalled.

The root cause lies in how pnpm handles binary entrypoints during package updates:

• Pre-update: The installed LaunchAgent plist (~/Library/LaunchAgents/ai.openclaw.gateway.plist) references dist/entry.js as the binary entrypoint.
• Post-update: pnpm relocates the entrypoint from dist/entry.js to dist/index.js in the new package version.
• Execution failure: On session start, launchd spawns the Node process pointing to the now-nonexistent entry.js file. Node.js exits immediately with a module-not-found error.
• State misrepresentation: launchd reports the job state as active because launchd itself remains running; the spawned child process (OpenClaw Gateway) exits silently before any logging occurs.
• Logging gap: Since the process terminates before the application's logging subsystem initializes, no error record appears in gateway.log for the failed session.

This behavior is specific to LaunchAgent-based deployments on macOS where launchd's job state reflects the launchd job itself, not the actual health of the child process it spawns.

To restore Gateway functionality, execute the following commands in sequence:

1. Stop the gateway service:
   openclaw gateway stop
2. Unload the stale LaunchAgent:
   launchctl bootout gui/$UID/ai.openclaw.gateway
3. Remove the outdated plist configuration:
   rm ~/Library/LaunchAgents/ai.openclaw.gateway.plist
4. Reinstall the gateway with the corrected entrypoint:
   openclaw gateway install --force
5. Verify gateway reachability:
   openclaw gateway probe
   Expected output: Reachable: yes

Preventive measure for future updates: Run openclaw gateway install --force immediately after any OpenClaw version upgrade that modifies the package structure.