Problem

When upgrading OpenClaw via npm install -g openclaw@latest, the old gateway process continues to hold the WebSocket port (ws://127.0.0.1:18789) even after the binary is replaced.

Symptoms:

• New gateway process fails to start: Gateway failed to start: another gateway instance is already listening on ws://127.0.0.1:18789
• PM2 enters a crash loop (1600+ restarts observed)
• Old process is in a half-dead state — listening on the port but not processing messages
• Regular kill does not terminate it cleanly; openclaw gateway stop is required

Steps to reproduce

1. Running OpenClaw gateway via PM2 (e.g. pm2 start openclaw --name potebot -- gateway)
2. Run npm install -g openclaw@latest to upgrade
3. Run pm2 restart potebot
4. New process crashes with port conflict; old process still holds the port

Root cause

npm install -g replaces the binary but does not signal the running gateway to stop. The old process keeps the port open. PM2 restart spawns the new binary, which cannot bind to the already-occupied port.

Expected behavior

Either:

• The upgrade process (openclaw update or post-install hook) gracefully stops any running gateway before replacing the binary, or
• The gateway detects a newer version is available and performs a graceful handoff, or
• At minimum: a clear warning/error with instructions to run openclaw gateway stop before upgrading

Workaround

openclaw gateway stop   # must use this — regular kill is not enough
npm install -g openclaw@latest
pm2 restart potebot

Environment

• OpenClaw 2026.3.11 → 2026.3.12
• Ubuntu 24.04 LTS, running as root via PM2
• Gateway started with: pm2 start openclaw --name potebot -- gateway