OpenClaw gateway not running? A 10-minute fix guide

Most OpenClaw failures collapse into one of five symptoms: the gateway will not start, it starts but nothing can reach it, the dashboard refuses to connect or loops on auth, the CLI says a command does not exist, or a channel stays silent. This guide walks each one using OpenClaw's own diagnostics, in the order that finds the cause fastest.

First 60 seconds

Run these before changing anything. They tell you which section below applies.

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

A healthy install prints Runtime: running, Connectivity probe: ok and a Dashboard: http://... line. openclaw triage bundles the same checks into a sanitized diagnosis you can paste into an issue.

Symptom 1: the gateway is not running

Read the last lines of openclaw logs --follow and match the message.

• "Gateway start blocked: set gateway.mode=local": the config is in remote mode or is missing the local-mode setting. Set gateway.mode=local and start again.
• "refusing to bind gateway ... without auth": you asked the gateway to listen on a non-loopback address without a token, password or trusted proxy. Either bind to loopback or configure authentication first. This refusal is a safety feature, not a bug.
• "another gateway instance is already listening" or EADDRINUSE: the port (18789 by default) is taken, usually by an older gateway that never exited. Find and stop the process, or move OpenClaw to another port with openclaw config set gateway.port <port>.
• Only "Starting OpenClaw gateway" and then silence: community guides report the gateway can take tens of seconds to boot on a first start. Wait, then probe again before assuming it failed.

Symptom 2: it runs but nothing can reach it

• "gateway connect failed:" from a client means the URL or port is wrong, or the gateway is bound to an address the client cannot see. Compare the client's target with the Dashboard: line from openclaw gateway status.
• If the gateway is on a VPS and you connect from a laptop, do not expose the port. Tunnel it (SSH port forwarding or a private network) so the loopback binding stays intact.

Symptom 3: the dashboard will not load or loops on auth

• "device identity required": device auth cannot complete over plain HTTP from a non-local origin. Use HTTPS or open the UI from localhost.
• "origin not allowed": the browser origin is not on the Control UI's allowlist. Add the exact origin (scheme, host and port) you are using.
• "AUTH_TOKEN_MISMATCH" with canRetryWithDeviceToken=true: the UI retries once with the device token on its own. If it keeps failing, the token is stale.
• Repeated "unauthorized": wrong token or password, an auth-mode mismatch, or a stale device token. Generate a fresh gateway token with openclaw doctor --generate-gateway-token, restart the gateway, show it with openclaw gateway auth-token --show, and paste it into the UI's connection settings. Re-pair if it still refuses.
• "too many failed authentication attempts (retry later)": you hit the rate limit. Wait it out; each localhost origin has its own bucket.
• Blank page after an update: a stale cache. Hard refresh (Ctrl+Shift+R, or Cmd+Shift+R on a Mac).
• Mixed content: the page is HTTPS but the gateway is HTTP. Match the schemes.

Symptom 4: "command not found" or "unknown command"

• The shell says openclaw: command not found: the install directory is not on your PATH for this shell. Open a new terminal, or add the global npm bin directory to PATH. On a fresh server this is the single most common cause.
• OpenClaw says unknown command 'browser' (or another tool): a plugins.allow list is set and does not include that tool. Add it, or remove the restrictive allowlist.
• Plugin install blocked: run openclaw doctor --deep, then openclaw plugins update --all. "blocked plugin candidate: suspicious ownership" means the config directory is owned by the wrong user; fix ownership (for Docker, sudo chown -R 1000:1000 on the config path).

Symptom 5: the gateway is fine but a channel is silent

Run openclaw channels status --probe and watch the log for these signatures: "pairing request" (the sender is not approved yet; approve the DM pairing), "blocked" or "allowlist" (the sender or room is filtered), "mention required" (the message did not mention the bot in a group that requires it), and "not_in_channel", "missing_scope", "Forbidden" or 401/403 (the channel token lacks a permission). openclaw pairing list --channel <channel> shows what is waiting.

Last resort

openclaw doctor --fix repairs common config damage. If the config is badly broken it is often faster to back it up, start from the minimal valid structure, and re-apply your settings one section at a time.

See it coming next time

Every symptom above was visible before someone noticed: a gateway that stopped answering its probe, a cron that stopped producing runs, a session that ended in an error. ClawMetry subscribes to the gateway's WebSocket for live status and reads OpenClaw's session and channel transcripts from disk, so it keeps showing what happened even while the gateway is down, and its health view shows the gateway, crons and sessions on one page. Install on the same machine:

pip install clawmetry && clawmetry

Sources

• OpenClaw docs: General troubleshooting (error strings and commands above are quoted from here)
• openclaw/openclaw issue #7905