solution gateway high macos linux windows

Gateway fails to start: EADDRINUSE / another gateway instance is already listening

Fix OpenClaw gateway port conflicts (EADDRINUSE) by stopping the other process or choosing a new gateway port/profile.

By CoClaw Team • February 3, 2026

Symptoms

Gateway startup fails with EADDRINUSE.
You see GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:18789").

Cause

The gateway enforces single-instance by binding its WebSocket/HTTP port early. If something already uses the port (another gateway instance or any other process), startup fails.

Fix

Option A: Stop the other gateway instance

Run:

openclaw gateway status

If you have multiple installs (e.g. macOS app + CLI), stop the one you don’t want running.

Option B: Use a different port

openclaw gateway --port 18790

For a permanent change, set gateway.port in your config (or OPENCLAW_GATEWAY_PORT).

Option C: If you actually need multiple gateways

Only do this when you need real isolation/redundancy. You must isolate:

config path
state dir / profile
gateway port

Verify

openclaw status

Open http://127.0.0.1:<port>/ (and use openclaw dashboard for the tokenized link if needed).

Verification & references

Reviewed by:CoClaw Code Team
Last reviewed:March 14, 2026
Verified on: macOS · Linux · Windows

References

Official docs

Want to explore more? Browse all solutions or ask in the Community Forum .

Report a problem

Related Resources

Linux/systemd: OpenClaw leaves orphan gateway processes or port 18789 conflicts

Fix Linux hosts where CLI-triggered gateway respawn collides with a systemd-managed OpenClaw gateway, causing orphan processes, EADDRINUSE, or 'another gateway instance is already listening'.

Gateway: CLI/UI is probing the wrong machine (local vs remote mode mismatch)

Fix confusing 'gateway unreachable' states by aligning gateway.mode, gateway.remote.url, profiles/state dirs, and the URL you probe.

Gateway won't start: 'refusing to bind ... without auth'

Fix gateway startup failures when binding to LAN/tailnet without token/password auth configured.

Gateway: service says running but the CLI/UI can't connect (probe fails)

Fix 'running but unreachable' gateway states by checking you're probing the right URL, confirming the port is listening, and aligning auth/bind settings.

OpenClaw Remote Browser Setup: Gateway on One Machine, Browser on Another

Choose a stable remote-browser topology for OpenClaw, pin the right browser-capable node, and verify that gateway routing, relay startup, and browser takeover all land on the machine you intended.

OpenClaw Configuration Guide: openclaw.json, Models, Gateway, Channels, and Plugins

Set up openclaw.json without guesswork: confirm the active config path, choose a safe baseline, add providers and channels in the right order, and verify each change before it becomes a production problem.