WSL2 + Windows 远程 Chrome CDP 故障排查

本指南适用于以下典型跨主机配置：

OpenClaw Gateway 运行在 WSL2 内
Chrome 运行在 Windows 上
浏览器控制需要跨越 WSL2/Windows 边界

同时涵盖来自 issue #39369 的多层故障叠加模式：多个独立问题同时出现，导致表面上看像是另一层出了问题。

首先选对浏览器模式

两种有效方案：

方案一：WSL2 到 Windows 的原始远程 CDP

使用指向 WSL2→Windows Chrome CDP 端点的远程浏览器 Profile。

适合场景：

Gateway 保留在 WSL2 内
Chrome 运行在 Windows 上
浏览器控制需要跨越 WSL2/Windows 边界

方案二：主机本地 Chrome MCP

仅当 Gateway 与 Chrome 运行在同一台主机时，才使用 existing-session / user。

适合场景：

OpenClaw 和 Chrome 在同一台机器上
需要本地已登录浏览器状态
不需要跨主机浏览器传输

对于 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 将浏览器 Profile 指向 WSL2 可达的地址

为什么这个配置容易出问题

多种故障可能同时叠加：

WSL2 无法访问 Windows CDP 端点
Control UI 从非安全源打开
gateway.controlUi.allowedOrigins 与页面 origin 不匹配
缺少 token 或配对
浏览器 Profile 指向了错误地址

因此，修复一层问题后，可能还有另一层报错。

Control UI 的关键规则

从 Windows 打开 UI 时，除非你有专门的 HTTPS 配置，否则请使用 Windows localhost。

使用：

http://127.0.0.1:18789/

不要使用局域网 IP 访问 Control UI。普通 HTTP 的局域网或 tailnet 地址可能触发与 CDP 本身无关的不安全源/设备认证问题。参见 Control UI。

分层验证

从上到下逐层排查，不要跳步。

第一层：验证 Windows 上 Chrome 是否正常提供 CDP 服务

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

powershell

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

先在 Windows 本地验证 Chrome：

powershell

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

如果这一步在 Windows 上就失败了，问题还没到 OpenClaw 这层。

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

从 WSL2 中，用你打算配置到 cdpUrl 的地址测试：

bash

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 配置。

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

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

json5

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

注意：

使用 WSL2 可达的地址，而不是仅 Windows 本地能用的地址
外部管理的浏览器保持 attachOnly: true
在让 OpenClaw 尝试之前，先用 curl 验证同一 URL

第四层：单独验证 Control UI 层

从 Windows 打开 UI：

http://127.0.0.1:18789/

然后验证：

页面 origin 与 gateway.controlUi.allowedOrigins 期望值匹配
token 认证或配对配置正确
你不是在把 Control UI 认证问题当成浏览器问题排查

参考页面：

Control UI

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

从 WSL2：

bash

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

成功标志：

标签页在 Windows Chrome 中打开
openclaw browser tabs 返回目标标签页
后续操作（snapshot、screenshot、navigate）从同一 Profile 正常运行

常见误导性报错

将每条错误信息视为特定层的线索：

control-ui-insecure-auth
- UI 源/安全上下文问题，不是 CDP 传输问题
token_missing
- 认证配置问题
pairing required
- 设备审批问题
Remote CDP for profile "remote" is not reachable
- WSL2 无法访问配置的 cdpUrl
gateway timeout after 1500ms
- 通常仍是 CDP 可达性问题或远端响应慢/不可达
No Chrome tabs found for profile="user"
- 选择了本地 Chrome MCP Profile，但主机本地没有可用标签页

快速排查清单

Windows：curl http://127.0.0.1:9222/json/version 能正常返回吗？
WSL2：curl http://WINDOWS_HOST_OR_IP:9222/json/version 能正常返回吗？
OpenClaw 配置：browser.profiles.<name>.cdpUrl 用的正是 WSL2 可达的地址吗？
Control UI：你打开的是 http://127.0.0.1:18789/ 而不是局域网 IP 吗？
你是不是在用 existing-session 跨越 WSL2 和 Windows，而不是原始远程 CDP？

实践总结

这个配置通常是可行的。难点在于浏览器传输、Control UI 源安全性、token/配对这三个问题各自独立失败，但从用户角度看却很相似。

遇到问题时：

先在 Windows 本地验证 Chrome CDP 端点
再从 WSL2 验证同一端点
最后再调试 OpenClaw 配置或 Control UI 认证

WSL2 + Windows 远程 Chrome CDP 故障排查 ​

首先选对浏览器模式 ​

方案一：WSL2 到 Windows 的原始远程 CDP ​

方案二：主机本地 Chrome MCP ​

正确架构 ​

为什么这个配置容易出问题 ​

Control UI 的关键规则 ​

分层验证 ​

第一层：验证 Windows 上 Chrome 是否正常提供 CDP 服务 ​

第二层：验证 WSL2 能否访问该 Windows 端点 ​

第三层：配置正确的浏览器 Profile ​

第四层：单独验证 Control UI 层 ​

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

常见误导性报错 ​

快速排查清单 ​

实践总结 ​