Gateway fails to start

If your gateway shows a red Error or Stopped status in Settings > Gateway and won't start, a port conflict is the most common cause. The gateway port is configured in your OpenClaw configuration file (~/.openclaw/openclaw.json) — if port 18789 is taken, update the port value there, then click Restart gateway. If that doesn't help, work through the causes below.

Port conflict

Another process on your machine is already using port 18789 (the default gateway port). The gateway cannot bind to a port that's taken.

To fix:

1. Open ~/.openclaw/openclaw.json in a text editor.
2. Change the "port" value to an unused port (e.g. 18790).
3. Save the file and click Restart gateway in Settings > Gateway.
4. If you're on macOS or Linux and want to identify the conflicting process first, run lsof -i :18789 in your terminal.

Missing or corrupt OpenClaw binary

The OpenClaw binary was deleted, moved, or never fully downloaded. Without it, the gateway cannot run.

To fix:

1. Reinstall the MultiClaw desktop app from multiclaw.io/download — this restores the OpenClaw binary.
2. Once reinstalled, click Restart gateway in Settings > Gateway.

Empty or invalid workspace token

Your gateway token was cleared — this can happen after a failed sign-in or an app reset. The gateway won't start without a valid token.

To fix:

1. Open Settings > General and scroll to the Account card.
2. Click Log out.
3. Sign back in with your account credentials.
4. Your token is regenerated automatically. Click Restart gateway once signed in.

Binary not executable (macOS and Linux)

The OpenClaw binary exists but does not have execute permissions. This often happens after a manual file move or a filesystem restore.

To fix:

1. The OpenClaw binary is located at ~/.openclaw/bin/openclaw on macOS and Linux (or %APPDATA%\OpenClaw\bin\openclaw.exe on Windows).
2. In your terminal, run chmod +x ~/.openclaw/bin/openclaw.
3. Click Restart gateway in Settings > Gateway.

Data directory inaccessible

The OpenClaw data directory no longer exists or your user account cannot write to it. The gateway needs a writable directory to store its data.

To fix:

1. Open ~/.openclaw/openclaw.json in a text editor.
2. Update the "data_dir" value to a folder that exists and that you have write access to.
3. Click Restart gateway in Settings > Gateway.

Still not working?

Check the gateway log at ~/.openclaw/logs/gateway.log — it will usually identify the exact failure line.