OpenClaw stuck on starting, or the gateway will not come up
A gateway that hangs on starting is nearly always failing for a reason it already wrote to the logs. Read the logs first, because the five causes below have five different fixes and guessing between them wastes the most time.
The symptoms vary but the cause set is small:
openclaw service is loaded but not running (likely exited immediately)
gateway stuck on starting
openclaw not respondingRead the logs before anything else
A gateway that will not start has nearly always already explained why. Open two terminals, tail the log in one and trigger the start in the other:
openclaw logs --followThe five diagnostic commands worth knowing, in order:
openclaw status # overall status
openclaw gateway status # gateway health specifically
openclaw logs --follow # live logs
openclaw doctor # diagnose
openclaw channels status --probe # channel connectivityCause 1: something else holds port 18789
The classic symptom is EADDRINUSE. Usually it is an older OpenClaw
process that never shut down cleanly.
lsof -i :18789
openclaw gateway --force--force kills the existing listener and starts fresh. If the port is
held by something unrelated, move OpenClaw instead by setting
OPENCLAW_PORT rather than killing another application's process.
Cause 2: refusing to bind without auth
The gateway will not expose itself without a token when the bind mode calls for one. This is deliberate, and the message says so.
openclaw config set gateway.auth.token "YOUR_TOKEN"Use a real random value, not a placeholder. Anything that can reach the port can drive your agent with that token.
Cause 3: the wrong gateway mode
If the logs mention setting the gateway mode, the config is pointing at a remote gateway that does not answer, so startup waits on something that will never arrive.
openclaw config set gateway.mode localCause 4: a broken upgrade
If it worked before the upgrade and not after, treat that as the cause rather than a coincidence:
openclaw doctor --repair
openclaw gateway install --force
openclaw gateway restartRun plain openclaw doctor first so you see what it plans to do.
Reinstalling the gateway service rewrites the unit or agent definition, which is
exactly what you want after an upgrade changed paths, and exactly what you do not
want to run blindly on a working install.
If the upgrade that broke things was to 2026.7.1, the cause is probably not your install. That release requires Node 24.15 or newer and shipped with migration bugs that leave older installs unable to start. See what 2026.7.1 changed and how the migration bug behaves.
Cause 5: loaded but not running, meaning it exits immediately
This message misleads people because it reads like a service problem. It is not. The service manager started the process and the process quit, so the failure is in the program's own output and the service status will never show it.
| Platform | Where to look |
|---|---|
| Linux and WSL2 | journalctl --user -u <unit> -n 100 |
| macOS | The LaunchAgent bot.molt.gateway and its log paths |
The usual culprits are a PATH the service cannot resolve, a config file it cannot read, or a port it cannot bind. All three appear in the first few lines of output and none appear in the service status.
Two service-level gotchas worth knowing
- Linux, the service dies when you log out. User services stop
with the session unless lingering is enabled:
sudo loginctl enable-linger $USER - WSL2, systemd is off by default. Add
[boot]withsystemd=trueto/etc/wsl.conf, then runwsl --shutdownand start again.
macOS: persistent unauthorized errors
A stale token in the launchd environment survives config changes and keeps rejecting connections. Clear it:
launchctl unsetenv OPENCLAW_GATEWAY_TOKENStill stuck
Confirm the config the gateway is reading is the one you are editing, since a
stray OPENCLAW_CONFIG_PATH makes every edit look ignored. Our guide on
where the OpenClaw config file lives
covers how to check that.
Frequently asked questions
- How long should starting take?
- Seconds. If it sits on starting for more than about half a minute, it is not slow, it is stuck, and the reason is in the logs.
- The service says loaded but not running. What does that mean?
- It means the service manager launched the process and the process exited immediately. The service is fine, the program refused to stay up, so read its output rather than the service status.
- Should I run doctor?
- Yes, after you have read the logs. Run it without repair flags first so you see what it intends to change before it changes anything.
Related guides
- OpenClaw error: openclaw: command not foundIn almost every case the install worked and the binary exists. Your shell simply does not have the global npm bin directory on its PATH, which is a two-line fix once you know which shell file to edit.
- OpenClaw error: gateway connect failed, pairing requiredThis error means the gateway is running and reachable, but it does not trust the client that just connected. Nothing is broken. The device simply has no approved identity yet, and there are four different reasons that can happen.
- Where is the OpenClaw config file, and how do you change its location?The short answer is ~/.openclaw/openclaw.json, written in JSON5. The longer answer matters when your edits appear to be ignored, which is almost always a second config file or an environment variable winning over the one you edited.
- OpenClaw Gateway Token Missing or Unauthorized? Read the Detail Code FirstOpenClaw returns one of five auth detail codes when a gateway connection is refused, and each one needs a different fix. This guide maps AUTH_TOKEN_MISSING, AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH, AUTH_SCOPE_MISMATCH and PAIRING_REQUIRED to the exact commands that clear them.