openclaw/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md at main

vultr/openclaw

Fork 0

mirror of https://github.com/openclaw/openclaw.git synced 2026-03-12 07:20:45 +00:00

Files

Peter Steinberger 9d467d1620 docs: add WSL2 + Windows remote Chrome CDP troubleshooting (#39407 ) (thanks @Owlock)

2026-03-08 19:21:42 +00:00

7.2 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Troubleshoot WSL2 Gateway + Windows Chrome remote CDP and extension-relay setups in layers

Running OpenClaw Gateway in WSL2 while Chrome lives on Windows

Seeing overlapping browser/control-ui errors across WSL2 and Windows

Deciding between raw remote CDP and the Chrome extension relay in split-host setups

WSL2 + Windows + remote Chrome CDP troubleshooting

This guide covers the common split-host setup where:

OpenClaw Gateway runs inside WSL2
Chrome runs on Windows
browser control must cross the WSL2/Windows boundary

It also covers the layered failure pattern from issue #39369: 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

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

Choose this when:

you only need browser control
you are comfortable exposing Chrome remote debugging to WSL2
you do not need the Chrome extension relay

Option 2: Chrome extension relay

Use the built-in chrome profile plus the OpenClaw Chrome extension.

Choose this when:

you want to attach to an existing Windows Chrome tab with the toolbar button
you want extension-based control instead of raw --remote-debugging-port
the relay itself must be reachable across the WSL2/Windows boundary

If you use the extension relay across namespaces, browser.relayBindHost is the important setting introduced in Browser and Chrome extension.

Working architecture

Reference shape:

WSL2 runs the Gateway on 127.0.0.1:18789
Windows opens the Control UI in a normal browser at http://127.0.0.1:18789/
Windows Chrome exposes a CDP endpoint on port 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
gateway.controlUi.allowedOrigins does not match the page origin
token or pairing is missing
the browser profile points at the wrong address
the extension relay is still loopback-only when you actually need cross-namespace access

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:

http://127.0.0.1:18789/

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:

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

From Windows, verify Chrome itself first:

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 cdpUrl:

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

Good result:

/json/version returns JSON with Browser / Protocol-Version metadata
/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:

{
  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 attachOnly: true for externally managed browsers
test the same URL with curl before expecting OpenClaw to succeed

Layer 4: If you use the Chrome extension relay instead

If the browser machine and the Gateway are separated by a namespace boundary, the relay may need a non-loopback bind address.

Example:

{
  browser: {
    enabled: true,
    defaultProfile: "chrome",
    relayBindHost: "0.0.0.0",
  },
}

Use this only when needed:

default behavior is safer because the relay stays loopback-only
0.0.0.0 expands exposure surface
keep Gateway auth, node pairing, and the surrounding network private

If you do not need the extension relay, prefer the raw remote CDP profile above.

Layer 5: Verify the Control UI layer separately

Open the UI from Windows:

http://127.0.0.1:18789/

Then verify:

the page origin matches what 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 6: Verify end-to-end browser control

From WSL2:

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

For the extension relay:

openclaw browser tabs --browser-profile chrome