{"id":640,"date":"2026-03-21T22:52:58","date_gmt":"2026-03-21T14:52:58","guid":{"rendered":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/tools-browser-wsl2-windows-remote-cdp-troubleshooting\/"},"modified":"2026-03-21T23:30:57","modified_gmt":"2026-03-21T15:30:57","slug":"tools-browser-wsl2-windows-remote-cdp-troubleshooting","status":"publish","type":"post","link":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/tools-browser-wsl2-windows-remote-cdp-troubleshooting\/","title":{"rendered":"WSL2 + Windows + \u8fdc\u7a0b Chrome CDP \u6545\u969c\u6392\u67e5"},"content":{"rendered":"<h1>WSL2 + Windows + remote Chrome CDP troubleshooting<\/h1>\n<p>This guide covers the common split-host setup where:<\/p>\n<ul>\n<li>OpenClaw Gateway runs inside WSL2<\/li>\n<li>Chrome runs on Windows<\/li>\n<li>browser control must cross the WSL2\/Windows boundary<\/li>\n<\/ul>\n<p>It also covers the layered failure pattern from <a href=\"https:\/\/github.com\/openclaw\/openclaw\/issues\/39369\">issue #39369<\/a>: several independent problems can show up at once, which makes the wrong layer look broken first.<\/p>\n<h2>Choose the right browser mode first<\/h2>\n<p>You have two valid patterns:<\/p>\n<h3>Option 1: Raw remote CDP from WSL2 to Windows<\/h3>\n<p>Use a remote browser profile that points from WSL2 to a Windows Chrome CDP endpoint.<\/p>\n<p>Choose this when:<\/p>\n<ul>\n<li>the Gateway stays inside WSL2<\/li>\n<li>Chrome runs on Windows<\/li>\n<li>you need browser control to cross the WSL2\/Windows boundary<\/li>\n<\/ul>\n<h3>Option 2: Host-local Chrome MCP<\/h3>\n<p>Use <code>existing-session<\/code> \/ <code>user<\/code> only when the Gateway itself runs on the same host as Chrome.<\/p>\n<p>Choose this when:<\/p>\n<ul>\n<li>OpenClaw and Chrome are on the same machine<\/li>\n<li>you want the local signed-in browser state<\/li>\n<li>you do not need cross-host browser transport<\/li>\n<\/ul>\n<p>For WSL2 Gateway + Windows Chrome, prefer raw remote CDP. Chrome MCP is host-local, not a WSL2-to-Windows bridge.<\/p>\n<h2>Working architecture<\/h2>\n<p>Reference shape:<\/p>\n<ul>\n<li>WSL2 runs the Gateway on <code>127.0.0.1:18789<\/code><\/li>\n<li>Windows opens the Control UI in a normal browser at <code>http:\/\/127.0.0.1:18789\/<\/code><\/li>\n<li>Windows Chrome exposes a CDP endpoint on port <code>9222<\/code><\/li>\n<li>WSL2 can reach that Windows CDP endpoint<\/li>\n<li>OpenClaw points a browser profile at the address that is reachable from WSL2<\/li>\n<\/ul>\n<h2>Why this setup is confusing<\/h2>\n<p>Several failures can overlap:<\/p>\n<ul>\n<li>WSL2 cannot reach the Windows CDP endpoint<\/li>\n<li>the Control UI is opened from a non-secure origin<\/li>\n<li><code>gateway.controlUi.allowedOrigins<\/code> does not match the page origin<\/li>\n<li>token or pairing is missing<\/li>\n<li>the browser profile points at the wrong address<\/li>\n<\/ul>\n<p>Because of that, fixing one layer can still leave a different error visible.<\/p>\n<h2>Critical rule for the Control UI<\/h2>\n<p>When the UI is opened from Windows, use Windows localhost unless you have a deliberate HTTPS setup.<\/p>\n<p>Use:<\/p>\n<p><code>http:\/\/127.0.0.1:18789\/<\/code><\/p>\n<p>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 <a href=\"\/web\/control-ui\">Control UI<\/a>.<\/p>\n<h2>Validate in layers<\/h2>\n<p>Work top to bottom. Do not skip ahead.<\/p>\n<h3>Layer 1: Verify Chrome is serving CDP on Windows<\/h3>\n<p>Start Chrome on Windows with remote debugging enabled:<\/p>\n<p>&#8220;`powershell  theme={&#8220;theme&#8221;:{&#8220;light&#8221;:&#8221;min-light&#8221;,&#8221;dark&#8221;:&#8221;min-dark&#8221;}}<br \/>\nchrome.exe &#8211;remote-debugging-port=9222<\/p>\n<pre><code>\nFrom Windows, verify Chrome itself first:\n\n```powershell  theme={&quot;theme&quot;:{&quot;light&quot;:&quot;min-light&quot;,&quot;dark&quot;:&quot;min-dark&quot;}}\ncurl http:\/\/127.0.0.1:9222\/json\/version\ncurl http:\/\/127.0.0.1:9222\/json\/list\n<\/code><\/pre>\n<p>If this fails on Windows, OpenClaw is not the problem yet.<\/p>\n<h3>Layer 2: Verify WSL2 can reach that Windows endpoint<\/h3>\n<p>From WSL2, test the exact address you plan to use in <code>cdpUrl<\/code>:<\/p>\n<p>&#8220;`bash  theme={&#8220;theme&#8221;:{&#8220;light&#8221;:&#8221;min-light&#8221;,&#8221;dark&#8221;:&#8221;min-dark&#8221;}}<br \/>\ncurl http:\/\/WINDOWS_HOST_OR_IP:9222\/json\/version<br \/>\ncurl http:\/\/WINDOWS_HOST_OR_IP:9222\/json\/list<\/p>\n<pre><code>\nGood result:\n\n* `\/json\/version` returns JSON with Browser \/ Protocol-Version metadata\n* `\/json\/list` returns JSON (empty array is fine if no pages are open)\n\nIf this fails:\n\n* Windows is not exposing the port to WSL2 yet\n* the address is wrong for the WSL2 side\n* firewall \/ port forwarding \/ local proxying is still missing\n\nFix that before touching OpenClaw config.\n\n### Layer 3: Configure the correct browser profile\n\nFor raw remote CDP, point OpenClaw at the address that is reachable from WSL2:\n\n```json5  theme={&quot;theme&quot;:{&quot;light&quot;:&quot;min-light&quot;,&quot;dark&quot;:&quot;min-dark&quot;}}\n{\n  browser: {\n    enabled: true,\n    defaultProfile: &quot;remote&quot;,\n    profiles: {\n      remote: {\n        cdpUrl: &quot;http:\/\/WINDOWS_HOST_OR_IP:9222&quot;,\n        attachOnly: true,\n        color: &quot;#00AA00&quot;,\n      },\n    },\n  },\n}\n<\/code><\/pre>\n<p>Notes:<\/p>\n<ul>\n<li>use the WSL2-reachable address, not whatever only works on Windows<\/li>\n<li>keep <code>attachOnly: true<\/code> for externally managed browsers<\/li>\n<li>test the same URL with <code>curl<\/code> before expecting OpenClaw to succeed<\/li>\n<\/ul>\n<h3>Layer 4: Verify the Control UI layer separately<\/h3>\n<p>Open the UI from Windows:<\/p>\n<p><code>http:\/\/127.0.0.1:18789\/<\/code><\/p>\n<p>Then verify:<\/p>\n<ul>\n<li>the page origin matches what <code>gateway.controlUi.allowedOrigins<\/code> expects<\/li>\n<li>token auth or pairing is configured correctly<\/li>\n<li>you are not debugging a Control UI auth problem as if it were a browser problem<\/li>\n<\/ul>\n<p>Helpful page:<\/p>\n<ul>\n<li><a href=\"\/web\/control-ui\">Control UI<\/a><\/li>\n<\/ul>\n<h3>Layer 5: Verify end-to-end browser control<\/h3>\n<p>From WSL2:<\/p>\n<p><code>bash  theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}<br \/>\nopenclaw browser open https:\/\/example.com --browser-profile remote<br \/>\nopenclaw browser tabs --browser-profile remote<\/code><\/p>\n<p>Good result:<\/p>\n<ul>\n<li>the tab opens in Windows Chrome<\/li>\n<li><code>openclaw browser tabs<\/code> returns the target<\/li>\n<li>later actions (<code>snapshot<\/code>, <code>screenshot<\/code>, <code>navigate<\/code>) work from the same profile<\/li>\n<\/ul>\n<h2>Common misleading errors<\/h2>\n<p>Treat each message as a layer-specific clue:<\/p>\n<ul>\n<li><code>control-ui-insecure-auth<\/code><\/li>\n<li>UI origin \/ secure-context problem, not a CDP transport problem<\/li>\n<li><code>token_missing<\/code><\/li>\n<li>auth configuration problem<\/li>\n<li><code>pairing required<\/code><\/li>\n<li>device approval problem<\/li>\n<li><code>Remote CDP for profile \"remote\" is not reachable<\/code><\/li>\n<li>WSL2 cannot reach the configured <code>cdpUrl<\/code><\/li>\n<li><code>gateway timeout after 1500ms<\/code><\/li>\n<li>often still CDP reachability or a slow\/unreachable remote endpoint<\/li>\n<li><code>No Chrome tabs found for profile=\"user\"<\/code><\/li>\n<li>local Chrome MCP profile selected where no host-local tabs are available<\/li>\n<\/ul>\n<h2>Fast triage checklist<\/h2>\n<ol>\n<li>Windows: does <code>curl http:\/\/127.0.0.1:9222\/json\/version<\/code> work?<\/li>\n<li>WSL2: does <code>curl http:\/\/WINDOWS_HOST_OR_IP:9222\/json\/version<\/code> work?<\/li>\n<li>OpenClaw config: does <code>browser.profiles.&lt;name&gt;.cdpUrl<\/code> use that exact WSL2-reachable address?<\/li>\n<li>Control UI: are you opening <code>http:\/\/127.0.0.1:18789\/<\/code> instead of a LAN IP?<\/li>\n<li>Are you trying to use <code>existing-session<\/code> across WSL2 and Windows instead of raw remote CDP?<\/li>\n<\/ol>\n<h2>Practical takeaway<\/h2>\n<p>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.<\/p>\n<p>When in doubt:<\/p>\n<ul>\n<li>verify the Windows Chrome endpoint locally first<\/li>\n<li>verify the same endpoint from WSL2 second<\/li>\n<li>only then debug OpenClaw config or Control UI auth<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>WSL2 + Windows + remote Chrome CDP troubleshooting This [&hellip;]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-640","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/640","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=640"}],"version-history":[{"count":4,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/640\/revisions"}],"predecessor-version":[{"id":896,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/640\/revisions\/896"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=640"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=640"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=640"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}