OpenClaw gateway error: a complete troubleshooting guide

The Gateway is the long lived process behind OpenClaw: sessions, channels, tools, and the WebSocket and HTTP surface on 127.0.0.1:18789 (or the port you configured). When it fails, channels go quiet and logs repeat a small set of signatures. The search phrase "openclaw gateway error" covers all of them, so this page maps symptom to fix. For the full command ladder, see Gateway troubleshooting.

The sections below go deeper on each one.

Triage commands

Before you chase a single error string, run the triage sequence the docs recommend:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw gateway status tells you whether the process is running, how supervision is configured (launchd, systemd user unit, Windows scheduled task), and whether the connectivity probe succeeds. Add --deep when you suspect duplicate or stale services from an old install. Add --json when you paste output into a ticket.

Quick HTTP check when the port should be up:

curl -sS http://127.0.0.1:18789/health

With token auth enabled, pass the same secret the gateway expects:

curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" http://127.0.0.1:18789/health

"Port 18789 is already in use" / EADDRINUSE

This is the most common gateway failure. Usually the supervised gateway from onboarding already owns the port and a second openclaw gateway in a terminal collides with it. You see Port 18789 is already in use, another gateway instance is already listening, or listen EADDRINUSE: address already in use 127.0.0.1:18789.

When the service should be the only instance, reload it:

openclaw gateway restart

For foreground debugging, free the port first:

openclaw gateway stop
openclaw gateway --verbose

The CLI also supports openclaw gateway --force to kill whatever holds the selected port before start (see the gateway operations page).

Find a stray listener on macOS or Linux:

lsof -nP -iTCP:18789 -sTCP:LISTEN

The lsof manual documents flags. On Windows:

netstat -ano | findstr :18789
taskkill /PID <PID> /F

Microsoft documents netstat in the Windows command reference.

After killing a process, the port can sit in TIME_WAIT for thirty to sixty seconds before a new bind succeeds. Wait, or reboot on a stuck host. openclaw doctor --fix clears many port and service drift cases automatically.

Legacy installs sometimes leave a clawdbot or old gateway binary listening on 18789 after a rename. openclaw gateway status --deep can surface other gateway like services; remove stale launchd plists or systemd units from earlier profiles.

A stale ~/.openclaw/gateway.pid after a crash can confuse restarts. If status says running but nothing listens, stop the service, remove the pid file only when no listener shows in lsof, then openclaw gateway restart.

For two intentional gateways on one machine, give each a unique port, state dir, and config path (documented under multiple gateways):

openclaw config set gateway.port 28789
openclaw gateway install --force
openclaw gateway restart

Changing gateway.port without reinstalling the supervisor can leave the old port in the service unit until you run openclaw doctor --fix or openclaw gateway install --force.

WSL2 ghost EADDRINUSE. Some 2026.4.x builds on WSL2 reported EADDRINUSE while lsof showed no listener, a watchdog race during bind (openclaw/openclaw#72693). If you hit that pattern on WSL2 after an upgrade, check the issue thread for version guidance and try openclaw gateway status --deep before assuming a normal port conflict.

Gateway not running

When openclaw gateway status shows stopped or no service, install or reinstall supervision:

openclaw gateway install --force
openclaw gateway restart

On Linux user services, enable lingering so the gateway survives logout:

sudo loginctl enable-linger "$USER"

If the service starts then exits, read boot logs:

openclaw logs --follow

Common boot blockers include invalid JSON5 config, Gateway start blocked: set gateway.mode=local when remote mode is set without the expected local stamp, or plugin load failures after a partial upgrade (openclaw doctor --fix is the first repair pass).

"refusing to bind gateway without auth"

You see this when binding beyond loopback without a configured auth path. OpenClaw blocks that combination because exposed gateways without auth drove real incidents in 2026; see Stormshield's OpenClaw retrospective for the public exposure research context.

Fix paths:

1. Keep gateway.bind on loopback and reach the host through SSH (ssh -N -L 18789:127.0.0.1:18789 user@host) as described on the gateway page.
2. Set gateway.auth.token (or password / trusted proxy mode) before binding to LAN or 0.0.0.0, following the gateway exposure runbook.

Tunnels do not remove the need for a token when the gateway requires one; clients must still authenticate.

"AUTH_TOKEN_MISMATCH"

Clients must send the same secret the gateway stores under gateway.auth.token (or env OPENCLAW_GATEWAY_TOKEN). Regenerate and propagate:

openclaw doctor --generate-gateway-token

Update editors, scripts, and Control UI bookmarks that hardcoded the old value. Reload secrets if you use the secrets subsystem: openclaw secrets reload.

pairing required means an unapproved device, not a wrong token. See the pairing required fix for that flow.

Config errors on startup

Configs are JSON5, which allows comments and trailing commas, but syntax errors still prevent boot. Validate:

openclaw doctor --fix

If the gateway died immediately after editing openclaw.json, restore from backup or run openclaw reset --scope config --dry-run before destructive scopes.

Version mismatch after upgrade

After upgrades, meta.lastTouchedVersion in config can block an older openclaw binary from restarting the service. Symptoms include unexpected stops right after update. Check:

which openclaw
openclaw --version
openclaw config get meta.lastTouchedVersion

Align PATH with the newer install, then:

openclaw gateway install --force
openclaw gateway restart

The troubleshooting runbook documents OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS for emergency downgrade only.

Restart issues on Linux and Windows

On Linux with systemd, openclaw gateway restart can leave orphan gateway children in some versions; restarting the unit directly is more reliable (openclaw/openclaw#39222):

systemctl --user restart openclaw-gateway.service

On Windows, restart has failed to kill the old process before binding again, producing an EADDRINUSE loop (openclaw/openclaw#42679). Stop the scheduled task, confirm no openclaw process in Task Manager, then openclaw gateway restart. Staying on the latest release helps because restart handling continues to change.

On macOS, prefer openclaw gateway restart over chaining stop and start; gateway stop uses launchctl bootout so KeepAlive can recover after crashes, as noted in the gateway docs.

Channel probes fail

When the gateway is healthy but Telegram or Discord stays disconnected:

openclaw channels status --probe

Approve pending devices if policy requires it:

openclaw pairing list
openclaw pairing approve <channel> <code-or-id>

Verbose gateway logging helps DM pairing issues:

openclaw gateway --verbose

The managed option

The fixes above are real: most errors are a port collision, a stopped service, or auth/config mismatch. Operating that service through reboots, npm upgrades, and OS updates is ongoing work on a machine you own.

Operator.io runs the OpenClaw gateway as a managed service: port binding, token rotation, supervision, and restarts live on the hosted side. You connect channels from the dashboard instead of maintaining launchd or systemd units locally. See pricing for a trial, or keep self hosting with the command ladder at the top of this page.