WSL2 + Windows + 远程 Chrome CDP 故障排除

在常见的拆分主机（split-host）设置中，OpenClaw Gateway 运行在 WSL2 内部，Chrome 运行在 Windows 上，浏览器控制必须跨越 WSL2/Windows 边界。多个独立的问题可能同时出现（参见 issue #39369）：CDP 传输、Control UI 来源安全以及令牌/配对（token/pairing）都可能各自独立失败，同时产生外观相似的错误。请按顺序逐层排查，而不是猜测哪一层出了问题。

首先选择正确的浏览器模式¶

选项 1：从 WSL2 到 Windows 的原始远程 CDP¶

使用一个从 WSL2 指向 Windows Chrome CDP 端点的远程浏览器配置文件。当 Gateway 位于 WSL2 内部、Chrome 运行在 Windows 上、且浏览器控制需要跨越 WSL2/Windows 边界时，选择此选项。

选项 2：主机本地 Chrome MCP¶

仅在以下情况下使用 existing-session 驱动程序（user 配置文件）：Gateway 与 Chrome 运行在同一台主机上、你需要本地已登录的浏览器状态、你不需要跨主机的浏览器传输，并且你不需要 responsebody、PDF 导出、下载拦截或批量操作（Chrome MCP 配置文件不支持这些功能）。

对于 WSL2 Gateway + Windows Chrome 的组合，请使用原始远程 CDP。Chrome MCP 是主机本地的，不是 WSL2 到 Windows 的桥梁。

工作架构¶

WSL2 在 127.0.0.1:18789 上运行 Gateway
Windows 在普通浏览器中通过 http://127.0.0.1:18789/ 打开 Control UI
Windows Chrome 在端口 9222 上暴露 CDP 端点
WSL2 可以访问该 Windows CDP 端点
OpenClaw 将某个浏览器配置文件指向从 WSL2 可访问的地址

Control UI 的关键规则¶

当从 Windows 打开 UI 时，除非你有刻意配置的 HTTPS 方案，否则请使用 Windows localhost：

http://127.0.0.1:18789/

不要默认使用局域网 IP。在局域网或 tailnet 地址上使用纯 HTTP 可能触发与 CDP 本身无关的不安全来源/设备认证行为。参见 Control UI。

分层验证¶

从上到下逐层排查；不要跳过。修复某一层后，仍然可能在更下面的层看到不同的错误。

第 1 层：验证 Chrome 是否在 Windows 上提供 CDP 服务¶

chrome.exe --remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\OpenClaw\ChromeCDP"

Chrome 136 及更高版本会忽略默认 Chrome 数据目录的 remote-debugging 命令行开关。请使用如上所示的独立非默认数据目录。参见 Chrome 的 remote-debugging 安全变更。这不会使正常登录的 Chrome 配置文件变为可远程控制。

在 Windows 上，先验证 Chrome 本身：

curl.exe http://127.0.0.1:9222/json/version
curl.exe http://127.0.0.1:9222/json/list

如果这一步失败，请使用下面的命令诊断 Windows 监听器。此时问题还不在 OpenClaw。

在更改 portproxy 之前诊断 IPv4 和 IPv6¶

Chromium 会首先尝试将远程调试绑定到 127.0.0.1，只有当 IPv4 绑定失败时才回退到 [::1]。一条持久化的 v4tov4 规则在 127.0.0.1:9222 上监听，可能会在 Chrome 启动前就占用该端点。Chrome 随后回退到 [::1]:9222，而旧规则将 IPv4 流量转发回自己的监听器，并返回空回复。

在 Windows 上检查实际的监听器和代理规则，而不要根据 Chrome 版本进行推断：

netstat -ano | findstr :9222
netsh interface portproxy show all
curl.exe http://127.0.0.1:9222/json/version
curl.exe http://[::1]:9222/json/version

对 netstat 中出现的每个 PID，使用 tasklist /fi "PID eq <PID>" 进行查看。

如果 chrome.exe 在 127.0.0.1 上响应，请移除任何同时监听 127.0.0.1:9222 的 portproxy 规则。只将 WSL2 可访问的 Windows 适配器地址转发到 127.0.0.1。
如果 chrome.exe 仅在 [::1] 上响应，请使用 v4tov6 将 WSL2 可访问的监听器指向 ::1，而不是转发到未使用的 IPv4 地址：

netsh interface portproxy add v4tov6 listenaddress=WINDOWS_HOST_OR_IP listenport=9222 connectaddress=::1 connectport=9222

将监听器绑定到 WSL2 所需的适配器地址。不要在 0.0.0.0、局域网地址或 tailnet 地址上暴露 CDP 端口：CDP 会授予对浏览器会话的控制权。

第 2 层：验证 WSL2 能否访问该 Windows 端点¶

在 WSL2 中，测试你打算在 cdpUrl 中使用的确切地址：

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

良好结果：

/json/version 返回包含 Browser / Protocol-Version 元数据的 JSON
/json/list 返回 JSON（如果没有打开任何页面，空数组也是可以的）

如果这一步失败，说明 Windows 尚未向 WSL2 暴露该端口、从 WSL2 侧来看地址不正确，或者缺少防火墙/端口转发/代理设置。在修改 OpenClaw 配置之前，先解决这些问题。

第 3 层：配置正确的浏览器配置文件¶

将 OpenClaw 指向从 WSL2 可访问的地址：

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

说明：

使用 WSL2 可访问的地址，而不是只在 Windows 上有效的地址
对于外部管理的浏览器，保持 attachOnly: true
cdpUrl 可以是 http://、https://、ws:// 或 wss://
当你希望 OpenClaw 发现 /json/version 时，使用 HTTP(S)
仅当浏览器提供方给出直接的 DevTools socket URL 时，才使用 WS(S)
在期望 OpenClaw 成功之前，先用 curl 测试相同的 URL

第 4 层：单独验证 Control UI 层¶

在 Windows 中打开 http://127.0.0.1:18789/，然后验证：

页面来源（origin）与 gateway.controlUi.allowedOrigins 期望的值匹配
令牌认证或配对已正确配置
没有把 Control UI 认证问题误当作浏览器问题来排查

参考页面：Control UI。

第 5 层：验证端到端的浏览器控制¶

在 WSL2 中：

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