Browser WSL2/Windows 远程 CDP 故障排查

概述

WSL2 运行 OpenClaw Gateway、Windows 运行 Chrome 的跨主机浏览器控制故障排查指南。多个独立问题（CDP 传输、Control UI 源安全、token/pairing）可能同时出现，需分层排查。

核心功能

两种有效模式

模式	适用场景
原始远程 CDP（WSL2 → Windows Chrome）	Gateway 在 WSL2，Chrome 在 Windows，需跨主机控制
Host-local Chrome MCP（existing-session）	OpenClaw 和 Chrome 在同一台机器，需要本地已登录会话

WSL2 + Windows Chrome 推荐使用原始远程 CDP，Chrome MCP 是 host-local 的，不是 WSL2-to-Windows 桥接。

分层排查步骤

Layer 1：Windows 本地验证 Chrome CDP

chrome.exe --remote-debugging-port=9222
curl http://127.0.0.1:9222/json/version

Layer 2：WSL2 验证可达性

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

Layer 3：配置正确的 browser profile

{
  browser: {
    enabled: true,
    defaultProfile: "remote",
    profiles: {
      remote: {
        cdpUrl: "http://WINDOWS_HOST_OR_IP:9222",
        attachOnly: true
      }
    }
  }
}

Layer 4：Control UI 使用 Windows localhost

http://127.0.0.1:18789/

不要使用 LAN IP（会触发 insecure-origin 问题）。

Layer 5：端到端验证

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

常见误导性错误

错误信息	实际原因
control-ui-insecure-auth	UI 源/安全上下文问题，非 CDP 传输问题
Remote CDP for profile "remote" is not reachable	WSL2 无法访问配置的 cdpUrl
No Chrome tabs found for profile="user"	选择了 local Chrome MCP 但无可用标签页

配置/权限

cdpUrl 支持 http://、https://、ws://、wss://。使用 HTTP(S) 进行 /json/version 发现，仅在浏览器服务提供直接 DevTools socket URL 时使用 WS(S)。

相关页面

• tool-browser — 浏览器工具概述
• tool-browser-linux-troubleshooting — Linux 故障排查