WSL2 + Windows + remote Chrome CDP troubleshooting

In the common split-host setup, OpenClaw Gateway runs inside WSL2, Chrome runs on Windows, and browser control must cross the WSL2 and Windows boundary. The layered failure pattern from issue #39369 means several independent problems can show up at once, which makes the wrong layer look broken first.

Choose the right browser mode first

You have two valid patterns:

Option 1: Raw remote CDP from WSL2 to Windows

Use a remote browser profile that points from WSL2 to a Windows Chrome CDP endpoint.

Choose this when:

• the Gateway stays inside WSL2
• Chrome runs on Windows
• you need browser control to cross the WSL2/Windows boundary

Option 2: Host-local Chrome MCP

Use

/ only when the Gateway itself runs on the same host as Chrome.

Choose this when:

• OpenClaw and Chrome are on the same machine
• you want the local signed-in browser state
• you do not need cross-host browser transport
• you do not need advanced managed/raw-CDP-only routes like
  text

  Copy

  responsebody
  , PDF export, download interception, or batch actions

For WSL2 Gateway + Windows Chrome, prefer raw remote CDP. Chrome MCP is host-local, not a WSL2-to-Windows bridge.

Working architecture

Reference shape:

• WSL2 runs the Gateway on
  text

  Copy

  127.0.0.1:18789
• Windows opens the Control UI in a normal browser at
  text

  Copy

  http://127.0.0.1:18789/
• Windows Chrome exposes a CDP endpoint on port
  text

  Copy

  9222
• WSL2 can reach that Windows CDP endpoint
• OpenClaw points a browser profile at the address that is reachable from WSL2

Why this setup is confusing

Several failures can overlap:

• WSL2 cannot reach the Windows CDP endpoint
• the Control UI is opened from a non-secure origin
• text

  Copy

  gateway.controlUi.allowedOrigins
  does not match the page origin
• token or pairing is missing
• the browser profile points at the wrong address

Because of that, fixing one layer can still leave a different error visible.

Critical rule for the Control UI

When the UI is opened from Windows, use Windows localhost unless you have a deliberate HTTPS setup.

Use:

Do not default to a LAN IP for the Control UI. Plain HTTP on a LAN or tailnet address can trigger insecure-origin/device-auth behavior that is unrelated to CDP itself. See Control UI.

Validate in layers

Work top to bottom. Do not skip ahead.

Layer 1: Verify Chrome is serving CDP on Windows

Start Chrome on Windows with remote debugging enabled:

powershell
Copy
chrome.exe --remote-debugging-port=9222

From Windows, verify Chrome itself first:

powershell
Copy
curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list

If this fails on Windows, OpenClaw is not the problem yet.

Layer 2: Verify WSL2 can reach that Windows endpoint

From WSL2, test the exact address you plan to use in

:

bash
Copy
curl http://WINDOWS_HOST_OR_IP:9222/json/version
curl http://WINDOWS_HOST_OR_IP:9222/json/list

Good result:

• text

  Copy

  /json/version
  returns JSON with Browser / Protocol-Version metadata
• text

  Copy

  /json/list
  returns JSON (empty array is fine if no pages are open)

If this fails:

• Windows is not exposing the port to WSL2 yet
• the address is wrong for the WSL2 side
• firewall / port forwarding / local proxying is still missing

Fix that before touching OpenClaw config.

Layer 3: Configure the correct browser profile

For raw remote CDP, point OpenClaw at the address that is reachable from WSL2:

json5
Copy
{
  browser: {
    enabled: true,
    defaultProfile: "remote",
    profiles: {
      remote: {
        cdpUrl: "http://WINDOWS_HOST_OR_IP:9222",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

Notes:

• use the WSL2-reachable address, not whatever only works on Windows
• keep
  text

  Copy

  attachOnly: true
  for externally managed browsers
• text

  Copy

  cdpUrl
  can be
  text

  Copy

  http://
  ,
  text

  Copy

  https://
  ,
  text

  Copy

  ws://
  , or
  text

  Copy

  wss://
• use HTTP(S) when you want OpenClaw to discover
  text

  Copy

  /json/version
• use WS(S) only when the browser provider gives you a direct DevTools socket URL
• test the same URL with
  text

  Copy

  curl
  before expecting OpenClaw to succeed

Layer 4: Verify the Control UI layer separately

Open the UI from Windows:

Then verify:

• the page origin matches what
  text

  Copy

  gateway.controlUi.allowedOrigins
  expects
• token auth or pairing is configured correctly
• you are not debugging a Control UI auth problem as if it were a browser problem

Helpful page:

• Control UI

Layer 5: Verify end-to-end browser control

From WSL2:

bash
Copy
openclaw browser open https://example.com --browser-profile remote
openclaw browser tabs --browser-profile remote

Good result:

• the tab opens in Windows Chrome
• text

  Copy

  openclaw browser tabs
  returns the target
• later actions (
  text

  Copy

  snapshot
  ,
  text

  Copy

  screenshot
  ,
  text

  Copy

  navigate
  ) work from the same profile

Common misleading errors

Treat each message as a layer-specific clue:

• text

  Copy

  control-ui-insecure-auth
  • UI origin / secure-context problem, not a CDP transport problem
• text

  Copy

  token_missing
  • auth configuration problem
• text

  Copy

  pairing required
  • device approval problem
• text

  Copy

  Remote CDP for profile "remote" is not reachable
  • WSL2 cannot reach the configured
    text

    Copy

    cdpUrl
• text

  Copy

  Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable
  • the HTTP endpoint answered, but the DevTools WebSocket still could not be opened
• stale viewport / dark-mode / locale / offline overrides after a remote session
  • run
    text

    Copy

    openclaw browser stop --browser-profile remote
  • this closes the active control session and releases Playwright/CDP emulation state without restarting the gateway or the external browser
• text

  Copy

  gateway timeout after 1500ms
  • often still CDP reachability or a slow/unreachable remote endpoint
• text

  Copy

  No Chrome tabs found for profile="user"
  • local Chrome MCP profile selected where no host-local tabs are available

Fast triage checklist

1. Windows: does
   text

   Copy

   curl http://127.0.0.1:9222/json/version
   work?
2. WSL2: does
   text

   Copy

   curl http://WINDOWS_HOST_OR_IP:9222/json/version
   work?
3. OpenClaw config: does
   text

   Copy

   browser.profiles.<name>.cdpUrl
   use that exact WSL2-reachable address?
4. Control UI: are you opening
   text

   Copy

   http://127.0.0.1:18789/
   instead of a LAN IP?
5. Are you trying to use
   text

   Copy

   existing-session
   across WSL2 and Windows instead of raw remote CDP?

Practical takeaway

The setup is usually viable. The hard part is that browser transport, Control UI origin security, and token/pairing can each fail independently while looking similar from the user side.

When in doubt:

• verify the Windows Chrome endpoint locally first
• verify the same endpoint from WSL2 second
• only then debug OpenClaw config or Control UI auth

Related

• Browser
• Browser login
• Browser Linux troubleshooting