WSL2 + Windows + remote Chrome CDP 故障排除

在常见的拆分主机设置中，OpenClaw Gateway(网关) 运行在 WSL2 内部，Chrome 运行在 Windows 上，浏览器控制必须跨越 WSL2 和 Windows 的边界。来自 issue #39369 的分层故障模式意味着可能会同时出现几个独立的问题，这会首先让错误的层级看起来像是坏掉了。

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

你有两种有效的模式：

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

使用指向从 WSL2 到 Windows Chrome CDP 端点的远程浏览器配置文件。

在以下情况选择此项：

Gateway(网关) 保持在 WSL2 内部
Chrome 运行在 Windows 上
你需要浏览器控制跨越 WSL2/Windows 边界

选项 2：主机本地 Chrome MCP

仅当 Gateway(网关) 本身与 Chrome 运行在同一主机上时，才使用 existing-session / user。

在以下情况选择此项：

OpenClaw 和 Chrome 在同一台机器上
你想要本地已登录的浏览器状态
你不需要跨主机浏览器传输
你不需要高级的 managed/raw-CDP-only 路由，如 responsebody、PDF 导出、下载拦截或批量操作

对于 WSL2 Gateway(网关) + Windows Chrome，首选原始远程 CDP。Chrome MCP 是主机本地的，而不是 WSL2 到 Windows 的桥接。

工作架构

参考架构：

WSL2 在 127.0.0.1:18789 上运行 Gateway(网关)
Windows 在普通浏览器的 http://127.0.0.1:18789/ 处打开控制 UI
Windows Chrome 在端口 9222 上公开一个 CDP 端点
WSL2 可以访问该 Windows CDP 端点
OpenClaw 将浏览器配置文件指向可从 WSL2 访问的地址

为什么此设置令人困惑

多个故障可能会重叠：

WSL2 无法访问 Windows CDP 端点
控制 UI 是从非安全源打开的
gateway.controlUi.allowedOrigins 与页面源不匹配
缺少令牌或配对
浏览器配置文件指向了错误的地址

因此，修复一个层级后可能仍然会显示另一个错误。

控制 UI 的关键规则

当从 Windows 打开 UI 时，请使用 Windows localhost，除非你有特意设置的 HTTPS 环境。

使用：

http://127.0.0.1:18789/

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

分层验证

从上到下进行。不要跳过步骤。

第一层：验证 Chrome 正在 Windows 上提供 CDP 服务

在 Windows 上启用远程调试并启动 Chrome：

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

从 Windows，首先验证 Chrome 本身：

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

如果在 Windows 上失败，OpenClaw 还不是问题所在。

第二层：验证 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 配置之前修复此问题。

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

对于原始远程 CDP，将 OpenClaw 指向可从 WSL2 访问的地址：

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

注意：

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

第四层：单独验证控制 UI 层

从 Windows 打开 UI：

http://127.0.0.1:18789/

然后验证：

页面来源与 gateway.controlUi.allowedOrigins 期望的相匹配
令牌认证或配对配置正确
您没有将控制 UI 认证问题误当作浏览器问题进行调试

有用的页面：

Control UI

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

在 WSL2 中：

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