OpenClaw Stuck on Starting (or the Control Panel Will Not Open)

You start OpenClaw and it just sits there. No error, no dashboard, no bound port, just "starting" forever. A hang is more annoying than a crash because there is no message to Google. The fix is to make OpenClaw tell you what it is waiting for, and then clear that one blocker. Here is the exact sequence.

OpenClaw Stuck on Starting: Read the Logs First

Never guess at a hang. OpenClaw logs almost always name the blocker. Check them in this order:

1. Stream the live logs: openclaw logs --follow. Leave it running while you start the gateway in another terminal.
2. If the CLI itself cannot connect, read the log files directly. On Linux they are daily JSONL files at /tmp/openclaw/openclaw-YYYY-MM-DD.log; on macOS check ~/Library/Logs/openclaw/gateway.log.
3. Run the gateway in the foreground with debug logging so nothing is swallowed by a service manager: OPENCLAW_LOG_LEVEL=debug openclaw gateway run.
4. Run openclaw doctor for a structured health report, and openclaw gateway status --deep for port and firewall checks.

One note before you panic: the very first start after installation legitimately takes longer, since OpenClaw initializes its state, loads channels, and reaches out to model providers. Give it up to 90 seconds before you call it stuck.

Cause 1: Something Else Owns Port 18789

If the log says another gateway instance is already listening, or the process hangs right at the bind step, the port is taken. A zombie gateway from a previous session is the usual suspect.

1. Find the process holding the port. Linux or macOS: lsof -i :18789. Windows: netstat -ano | findstr :18789.
2. If it is an old OpenClaw process, kill it, then start fresh with openclaw gateway restart.
3. If a different app owns the port, move OpenClaw: openclaw config set gateway.port 18790 and restart.

Cause 2: A Corrupt or Invalid Config File

OpenClaw reads its config from ~/.openclaw/openclaw.json (JSON5 format). A typo, a trailing edit from a crashed editor, or a bad merge can make the gateway stall while parsing or waiting on invalid settings.

1. Confirm which config file is actually loaded: openclaw config file.
2. Validate it: openclaw config validate. Fix anything it flags.
3. Watch for the startup message Gateway start blocked: set gateway.mode=local. That one means onboarding never finished; run openclaw onboard --mode local (or openclaw setup) to complete it.
4. If you bound the gateway to a LAN address and see refusing to bind gateway without auth, either bind back to loopback or configure token auth before it will start.

Cause 3: Wrong or Mismatched Node.js Version

OpenClaw requires Node 22 or newer. An older Node can hang during module loading rather than failing cleanly, which looks exactly like a freeze.

1. Check your version: node --version. Upgrade to Node 22+ if you are below it.
2. If you use a version manager (nvm, fnm, volta), be aware that version-manager Node paths break in service mode: the service starts with a different environment and finds no Node, or the wrong one. Install a system Node for the service to use.
3. After changing Node, reinstall the gateway service so it picks up the new path: openclaw gateway install --force, then openclaw gateway restart.

Cause 4: A Service Manager Is Hiding a Prompt

Gateways launched by launchd, PM2, systemd, or a Docker entrypoint sometimes hang because a startup check tried to render an interactive prompt, and there is no terminal to answer it. The process is not frozen; it is waiting for input that will never come.

1. Stop the service, then run the gateway once in the foreground: openclaw gateway run. Answer any prompt it shows (onboarding, mode selection, auth setup).
2. Confirm it now starts cleanly in the foreground, then stop it with Ctrl+C.
3. Reinstall and restart the supervised service: openclaw gateway install --force followed by openclaw gateway restart.

Cause 5: Not Enough Memory or No Outbound Network

On small VPS instances, two environmental issues mimic a startup hang.

1. Memory: OpenClaw wants roughly 2 GB of RAM. On a 1 GB box the process can stall or get OOM-killed silently during startup. Check with free -h and add swap or resize if you are at the limit.
2. Network: the gateway reaches out to model provider APIs on startup. If your firewall blocks outbound HTTPS, it waits on those connections. Test with curl https://api.anthropic.com (or your provider) from the same machine.

OpenClaw Control Panel Will Not Open: What to Check

Sometimes the gateway starts fine, yet the dashboard never loads: you open http://127.0.0.1:18789, the tab spins, shows "refused to connect", or renders a blank page. The Control UI is not a separate app. The Gateway process serves it at / on port 18789, so a dead panel means the gateway is down, the port is unreachable from your browser, or the session lost its auth token. One extra check sorts these apart: run curl http://127.0.0.1:18789 in a terminal on the machine where OpenClaw is installed.

If curl cannot connect, you are looking at a gateway or port problem, and the five causes above apply; the panel comes back the moment the gateway binds its port. If curl returns OpenClaw HTML but the browser still fails, work through the fixes below.

Fix 1: The Gateway Is Not Running

1. Check the current state with openclaw gateway status.
2. If it is stopped, restart it: openclaw gateway restart. If restart does not keep it alive, run openclaw gateway start and check status again. A gateway that refuses to stay up is the startup hang problem covered in the first half of this guide.
3. Once the gateway is up, open the panel with openclaw dashboard. This copies a fresh link, opens a browser when possible, and prints the URL if you are on a headless server.

Fix 2: The Port Works Locally but Is Blocked Remotely

Port conflicts were covered under Cause 1, but firewalls create a subtler version of the same symptom. On Windows in particular, Windows Firewall or Group Policy can block the LAN URL even when 127.0.0.1 works locally. The same openclaw gateway status --deep check from the diagnosis section reports likely-blocked ports and conflicting firewall rules. After changing anything, retest with curl http://127.0.0.1:18789.

Fix 3: The Tokenized Dashboard URL Expired

The link that openclaw dashboard gives you carries an auth token in the URL fragment. The Control UI stores that token in sessionStorage for the current tab and strips it from the address bar after load. That means an old bookmarked link, or a link opened in a new browser session, can land you on a page that refuses to authenticate.

1. Do not reuse old links. Generate a fresh one: openclaw dashboard.
2. If you need to authenticate manually, read your gateway token with openclaw config get gateway.auth.token and paste it into the Control UI connection settings.
3. Open the clean URL http://127.0.0.1:18789/ directly and enter the token when prompted, rather than relying on a stale deep link.

Fix 4: Browser and Relay Issues

If curl proves the gateway is serving HTML but your browser still shows a broken panel, the problem is on the browser side. The Control UI talks to the gateway over a WebSocket, and stale tab state can leave that connection dead.

1. Open http://127.0.0.1:18789/ in a fresh tab (not a restored one) and navigate from the dashboard.
2. Try a private or incognito window to rule out cached state and extensions.
3. Watch the gateway logs while the page loads. Messages like origin not allowed, device identity required, or device nonce mismatch mean the browser origin or device auth flow is being rejected, not the network.
4. If you see those auth messages, load the page from 127.0.0.1 (a secure context) instead of a LAN IP, or complete device pairing first.

Accessing the Panel on a Remote Server or VPS

If OpenClaw runs on a VPS, do not expose port 18789 to the internet without authentication. The standard approach is an SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 your-server

Then open http://127.0.0.1:18789 in your local browser. The panel behaves exactly as if it were local, and nothing is publicly exposed.

Frequently Asked Questions

How long should OpenClaw normally take to start?

After the first run, a healthy gateway binds port 18789 within a few seconds. The first start after installation can take up to about 90 seconds while it initializes state and contacts model providers. Anything beyond that, with no log output, is a genuine hang worth debugging.

Does restarting fix a gateway stuck on starting?

Sometimes, especially when a zombie process held the port. Run openclaw gateway restart once; if the hang comes right back, stop restarting and read the logs, because a config, Node, or prompt issue will hang identically every time until the root cause is fixed.

What is the default URL for the OpenClaw control panel?

The Control UI is served by the Gateway at http://127.0.0.1:18789/ by default (or http://localhost:18789/). The quickest way to open it with authentication included is to run the openclaw dashboard command, which generates a fresh tokenized link.

Why does the panel load but show "disconnected"?

The page itself is static; the live data comes over a WebSocket to the gateway. A "disconnected" banner means the WebSocket handshake failed, usually due to a missing or mismatched auth token, or the gateway restarting. Run openclaw dashboard for a fresh token and check the logs for the rejection reason.

If chasing ports, Node versions, tokens, and firewalls is not how you want to spend an afternoon, a managed OpenClaw host keeps the gateway and Control UI running, reachable, and monitored for you.