OpenClaw on Windows: 10 Common Issues and How to Fix Them

If you followed the OpenClaw Windows setup guide and something still is not working, you are not alone. The Windows launch has been mostly smooth, but a handful of issues keep appearing in community threads. Most of them have a clear fix once you know where to look.

This post collects the ten most common Windows problems I have seen, what causes them, and how to resolve them. It is written for the Windows Hub path first, with notes for PowerShell and WSL2 setups where they differ.

1. Setup appears to freeze at "Starting setup..."

Symptom: The Windows Hub setup dialog stays on "Starting setup" for several minutes.

Cause: The app is provisioning an app-owned WSL distro and installing the Gateway inside it. On first run, Windows may prompt you to install or update WSL silently in the background. If that prompt is hidden behind another window, the setup looks stuck.

Fix:

• Check the Windows taskbar for a WSL or Store notification.
• Open PowerShell as a normal user and run wsl --update, then restart the Hub.
• Make sure virtualization is enabled in BIOS/UEFI (Hyper-V or Windows Subsystem for Linux depends on it).
• If it stays stuck longer than ten minutes, close the app, run wsl --list --verbose to confirm no OpenClawGateway distro exists, then restart setup.

2. Gateway disconnected / dashboard will not load

Symptom: The tray icon is red or gray, and the Command Center shows the Gateway as disconnected.

Cause: The Gateway service is not running, the app is pointing at the wrong endpoint, or something else is using the Gateway port.

Fix:

• Open Command Center → Connections and confirm the endpoint matches your setup path.
• If you chose Set up locally, the endpoint should be the local WSL Gateway. Try Repair from the tray menu.
• If you used the PowerShell installer, run openclaw status and openclaw gateway status in a fresh terminal.
• Check if another process is using the Gateway port. In PowerShell: netstat -ano | findstr 18789 (replace with your configured port). If another app owns it, stop that app or reconfigure OpenClaw to use a different port.

3. "openclaw" is not recognized as a command

Symptom: After the PowerShell install, typing openclaw returns a command-not-found error.

Cause: The installer added OpenClaw to your user PATH, but the current terminal session loaded the old PATH before the change took effect.

Fix: Close the terminal and open a new one. If you are using Windows Terminal, open a new tab. Do not reuse the same session.

If it still fails, verify the install location:

where.exe openclaw

If that returns nothing, reinstall with the PowerShell script or use the Windows Hub instead, which does not depend on PATH.

4. API key or configuration not loading

Symptom: Commands fail with an authentication or missing-config error even though you set an API key.

Cause: OpenClaw config files are stored under your user profile. If you set the key in one shell but ran the command in another, or if the config file was written to an unexpected location, the Gateway may not see it.

Fix:

• Run openclaw config get to see the current config path and values.
• If the key is missing, set it again: openclaw config set providers.<name>.apiKey <value>.
• Make sure you are running the command as the same Windows user who configured the key.
• Restart the Gateway after changing config.

5. WSL version mismatch with the Hub

Symptom: Windows Hub shows a "WSL version mismatch" error, or the app-owned gateway fails to start.

Cause: The Hub provisions its own lightweight WSL distro. If your system WSL kernel is older than what that distro expects, you get a mismatch.

Fix:

• Run wsl --update from PowerShell and reboot if it asks.
• After reboot, open the Hub and choose Repair from the tray menu.
• Do not manually convert the OpenClawGateway distro to WSL1. The Hub expects WSL2.

6. PATH issues in hybrid setups

Symptom: You installed with the PowerShell installer, then installed Windows Hub, and now commands behave differently depending on which terminal you use.

Cause: Two install paths can leave you with different PATH entries, different Node versions, or stale shell sessions.

Fix:

• Decide which path you want to keep. For most users, Windows Hub is the simpler surface.
• If you keep the PowerShell install, remove duplicate or old OpenClaw entries from your user PATH.
• Open a fresh terminal after every install or uninstall.

7. Callback timeout or redirect URI errors

Symptom: During onboarding, the browser redirect back to OpenClaw times out or lands on a blank page.

Cause: Some providers use OAuth callbacks to localhost. If the Gateway is not listening on the expected port, or if a firewall/antivirus blocks the loopback request, the callback fails.

Fix:

• Confirm the Gateway is running and the port in your config matches the redirect URI.
• Temporarily disable third-party antivirus or firewall rules for localhost/127.0.0.1.
• If you are on a corporate machine, the browser-to-loopback path may be blocked by policy. In that case, use a manual token or ask your IT admin to allow localhost callbacks for openclaw.ai.

8. Port already in use

Symptom: The Gateway fails to start with an address-in-use error.

Cause: Another service is bound to the Gateway's default port.

Fix:

• Find the process: netstat -ano | findstr 18789
• Either stop the conflicting process or change OpenClaw's port in openclaw.json.

9. The tray icon is green but commands do not work

Symptom: Everything looks connected, but running openclaw commands returns no response or session errors.

Cause: The Hub is connected to a Gateway, but the current shell session is pointing at a different Gateway, or the CLI is not authenticated against the paired Gateway.

Fix:

• Run openclaw status and compare the Gateway URL with what the Hub shows in Connections.
• If they differ, either reconnect the Hub to the same Gateway or configure your shell to point at the Hub's Gateway.
• Re-pair if needed: openclaw devices approve <request-id>.

10. WSL vs native confusion

Symptom: You are unsure whether you should be using the Hub's app-owned WSL Gateway, a separate WSL2 Gateway, or a native Windows Gateway.

Fix: Use this decision tree:

• Windows Hub + Set up locally: Best for most users. WSL is handled automatically. You do not need to manage it.
• PowerShell installer: Best for CLI-first users who want the Gateway running directly on Windows without the companion app.
• Separate WSL2 Gateway: Best if you already run your dev environment in WSL2 and want the Gateway there for Linux compatibility.

Pick one and stick with it. Mixing them is where most confusion starts.

If none of these match your error

Reply with:

• The exact error message
• Which setup path you chose (Hub local, PowerShell, or WSL2)
• Your Windows version
• Whether the issue started immediately after install or after an update

Most Windows setup problems fall into one of the buckets above. The faster we can document the edge cases, the faster the next person avoids them.