diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e1c7c6f48d..243a379e2b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,7 @@ Docs: https://docs.openclaw.ai - Browser/CDP: rewrite wildcard `ws://0.0.0.0` and `ws://[::]` debugger URLs from remote `/json/version` responses back to the external CDP host/port, fixing Browserless-style container endpoints. (#17760) Thanks @joeharouni. - Browser/extension relay: wait briefly for a previously attached Chrome tab to reappear after transient relay drops before failing with `tab not found`, reducing noisy reconnect flakes. (#32461) Thanks @AaronWander. - Browser/extension relay: add `browser.relayBindHost` so the Chrome relay can bind to an explicit non-loopback address for WSL2 and other cross-namespace setups, while preserving loopback-only defaults. (#39364) Thanks @mvanhorn. +- Docs/browser: add a layered WSL2 + Windows remote Chrome CDP troubleshooting guide, including Control UI origin pitfalls and extension-relay bind-address guidance. (#39407) Thanks @Owlock. - Context engine registry/bundled builds: share the registry state through a `globalThis` singleton so duplicated bundled module copies can resolve engines registered by each other at runtime, with regression coverage for duplicate-module imports. (#40115) thanks @jalehman. ## 2026.3.7 diff --git a/docs/docs.json b/docs/docs.json index 35e2f37a4a7..8592618cd7d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1013,7 +1013,8 @@ "tools/browser", "tools/browser-login", "tools/chrome-extension", - "tools/browser-linux-troubleshooting" + "tools/browser-linux-troubleshooting", + "tools/browser-wsl2-windows-remote-cdp-troubleshooting" ] }, { diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md index c2cb1a4312b..e051f77f589 100644 --- a/docs/help/troubleshooting.md +++ b/docs/help/troubleshooting.md @@ -290,6 +290,7 @@ flowchart TD - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails) - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting) + - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting) - [/tools/chrome-extension](/tools/chrome-extension) diff --git a/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md b/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md new file mode 100644 index 00000000000..d63bb891c48 --- /dev/null +++ b/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md @@ -0,0 +1,242 @@ +--- +summary: "Troubleshoot WSL2 Gateway + Windows Chrome remote CDP and extension-relay setups in layers" +read_when: + - 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 +title: "WSL2 + Windows + remote Chrome CDP troubleshooting" +--- + +# 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](https://github.com/openclaw/openclaw/issues/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](/tools/browser) and [Chrome extension](/tools/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](/web/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 +chrome.exe --remote-debugging-port=9222 +``` + +From Windows, verify Chrome itself first: + +```powershell +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`: + +```bash +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: + +```json5 +{ + 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: + +```json5 +{ + 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](/web/control-ui) + +### Layer 6: Verify end-to-end browser control + +From WSL2: + +```bash +openclaw browser open https://example.com --browser-profile remote +openclaw browser tabs --browser-profile remote +``` + +For the extension relay: + +```bash +openclaw browser tabs --browser-profile chrome +``` + +Good result: + +- the tab opens in Windows Chrome +- `openclaw browser tabs` returns the target +- later actions (`snapshot`, `screenshot`, `navigate`) work from the same profile + +## Common misleading errors + +Treat each message as a layer-specific clue: + +- `control-ui-insecure-auth` + - UI origin / secure-context problem, not a CDP transport problem +- `token_missing` + - auth configuration problem +- `pairing required` + - device approval problem +- `Remote CDP for profile "remote" is not reachable` + - WSL2 cannot reach the configured `cdpUrl` +- `gateway timeout after 1500ms` + - often still CDP reachability or a slow/unreachable remote endpoint +- `Chrome extension relay is running, but no tab is connected` + - extension relay profile selected, but no attached tab exists yet + +## Fast triage checklist + +1. Windows: does `curl http://127.0.0.1:9222/json/version` work? +2. WSL2: does `curl http://WINDOWS_HOST_OR_IP:9222/json/version` work? +3. OpenClaw config: does `browser.profiles..cdpUrl` use that exact WSL2-reachable address? +4. Control UI: are you opening `http://127.0.0.1:18789/` instead of a LAN IP? +5. Extension relay only: do you actually need `browser.relayBindHost`, and if so is it set explicitly? + +## Practical takeaway + +The setup is usually viable. The hard part is that browser transport, Control UI origin security, token/pairing, and extension-relay topology 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 diff --git a/docs/tools/browser.md b/docs/tools/browser.md index 633b2633a33..d632e713068 100644 --- a/docs/tools/browser.md +++ b/docs/tools/browser.md @@ -649,6 +649,9 @@ Strict-mode example (block private/internal destinations by default): For Linux-specific issues (especially snap Chromium), see [Browser troubleshooting](/tools/browser-linux-troubleshooting). +For WSL2 Gateway + Windows Chrome split-host setups, see +[WSL2 + Windows + remote Chrome CDP troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting). + ## Agent tools + how control works The agent gets **one tool** for browser automation: diff --git a/docs/tools/index.md b/docs/tools/index.md index 0f311516dcd..6552d6f9118 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -531,6 +531,9 @@ Browser tool: - `profile` (optional; defaults to `browser.defaultProfile`) - `target` (`sandbox` | `host` | `node`) - `node` (optional; pin a specific node id/name) +- Troubleshooting guides: + - Linux startup/CDP issues: [Browser troubleshooting (Linux)](/tools/browser-linux-troubleshooting) + - WSL2 Gateway + Windows remote Chrome CDP: [WSL2 + Windows + remote Chrome CDP troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting) ## Recommended agent flows