You run openclaw gateway start (or the gateway tries to launch on boot) and instead of a clean startup you get a wall of red: GatewayLockError: another gateway instance is already listening on the WebSocket port, or the classic Node error EADDRINUSE: address already in use. The gateway refuses to start, and retrying the same command gives you the same result.
The good news: this error is a guardrail, not a meltdown. OpenClaw is deliberately refusing to run two gateways on the same configuration and port. In practice it means one of two things. Either a gateway is already running and healthy (in which case you do not need to start it at all), or a leftover process is squatting on the port after a crash, an update, or a double start. Both are easy to fix, and neither one touches your agents, memory, or config.
That message appears the moment OpenClaw tries to bind its listener and finds the port taken. Here is what is actually going on, and the four steps that fix it.
Why OpenClaw throws EADDRINUSE
OpenClaw enforces a one-gateway-per-config rule with two independent layers that run at startup, and each layer throws its own GatewayLockError.
The first layer is a file lock in the state directory. Startup records its PID and probes the configured port for a live listener. If the previous owner crashed hard and left the lock behind, startup notices the process is gone or the port is silent, reclaims the lock, and continues. If another live gateway holds the lock, it retries for about five seconds and then gives up with a message like gateway already running (pid 3841); lock timeout after 5000ms.
The second layer is the socket bind. The gateway binds its HTTP/WebSocket listener (default ws://127.0.0.1:18789) as an exclusive TCP listener. If the bind fails with EADDRINUSE, it retries for roughly ten seconds to ride out a TIME_WAIT window left by a recently exited process. If the port is still occupied, you get the error from the top of this post.
One detail that trips people up: the default port is 18789, but many installs run a custom port. This guide was written on a machine whose gateway listens on port 19999 (set through the service environment). Do not assume the port. Read it from your own openclaw gateway status output before you hunt for the culprit.
Step 1: Check whether a gateway is already running
Before killing anything, confirm the actual state. OpenClaw ships a command for exactly this:
Read the output left to right:
- Service:
LaunchAgent (loaded)means the gateway is installed as a macOS background service (on Linux you will see a systemd unit here). - Runtime:
runningwith a PID andstate activemeans the process is alive right now. - Connectivity probe:
okmeans it is answering on its socket, which is the definition of healthy. - Gateway: shows the bind address and the real port (here
19999 (service args)). Use this number everywhere below.
If you see a running, healthy gateway, stop here. You do not have an EADDRINUSE problem. You have a start when you should restart problem: use openclaw gateway restart when you want to cycle it, and do not run start on top of a supervised service. If Runtime shows stopped or the service is loaded but the runtime is not responding, continue to step 2.
Step 2: Find the process holding the port
On macOS or Linux, list everything bound to your gateway port. Substitute your real port from step 1:
Two things matter here. First, the PID column (50819 in this capture). Second, the process name: the gateway runs as node with a command line that points at the OpenClaw install (.../openclaw/dist/index.js gateway), which you can confirm with ps -p <PID> -o command=.
On Windows the equivalent is:
C:\> netstat -ano | findstr :18789
C:\> taskkill /PID <PID> /F
If the PID on the port matches the Runtime: running PID from step 1, that is your healthy gateway. Do not kill it. Restart it instead. If the process is a leftover (an old gateway PID that nothing reports as running, or a node process from a previous OpenClaw version), that is the stale squatter to clear in step 3.
Step 3: Clear the stale process and restart
Kill the leftover process, then let the service supervisor bring the gateway back:
user@host:~$ kill 50819 user@host:~$ openclaw gateway restart
Then run openclaw gateway status again and confirm Runtime: running and Connectivity probe: ok. If the gateway is not installed as a service, openclaw gateway start is correct here because nothing else owns the port anymore.
Worth knowing: when a supervised gateway starts and finds a healthy instance already in control, it probes the existing process and steps aside instead of fighting it (on systemd it exits with code 78 so the unit does not restart-loop). That behavior is exactly why the fix is usually restart, not start.
Step 4: If it keeps coming back
A recurring EADDRINUSE after every reboot points at a structural double-start, not a one-off leftover. Work through these:
- Autostart plus manual start. If the service is set to launch on boot and you also run
openclaw gateway start(or the desktop app) after login, two instances race for the port. Keep the service, drop the manual start. - Shell profile lines. Check
~/.zshrc,~/.bashrc, and similar startup files for a leftoveropenclaw gateway startline from an old setup and remove it. - The service wrapper pins an old port. After an update or a config change, the installed supervisor can still point at the previous port. Run
openclaw doctor --fix, or force a clean reinstall of the service wrapper withopenclaw gateway install --forcefollowed byopenclaw gateway restart. This does not touch your config, agents, or workspace. It only rewrites the service metadata and clears stale lock state. - Duplicate service installs. If
openclaw doctorreports other gateway-like services on the machine, you have parallel launchd or systemd units. Most setups should keep exactly one gateway per machine. Remove the duplicate, or isolate it properly with its own port, config, and workspace if you genuinely need a second instance. - Moving the gateway to another port. If a different application legitimately owns the port, stop fighting it: reinstall the service on a new port with
openclaw gateway install --port <port>, then restart.
Quick reference
# 1. Is it actually down? Read the Runtime line openclaw gateway status # 2. Who holds the port? (macOS/Linux) lsof -i :18789 # Windows: netstat -ano | findstr :18789 # 3. Kill the stale PID, then restart through the supervisor kill <PID> openclaw gateway restart # 4. Keeps happening? Clean the wrapper and check for duplicates openclaw doctor --fix openclaw gateway install --force openclaw gateway restart
Related fixes
If the gateway will not start for a different reason, or misbehaves after an update, these sibling guides cover the rest of the troubleshooting cluster: gateway start blocked by the local mode config, CLI and service showing different configs, OpenClaw quiet on Telegram after an upgrade, and rolling back a broken update safely. New to the platform? Start with The Complete OpenClaw Guide.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting: your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.
About The Author
This fixed it for me instantly. I had been staring at that error for two hours thinking it was a port conflict with something else entirely. Thanks for writing this up.
Thanks for reading, Brigitte Hofer. On Fix Another Gateway Instance Already, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.