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

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

先选择正确的浏览器模式

​

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

• Gateway 保持运行在 WSL2 中
• Chrome 运行在 Windows 上
• 你需要浏览器控制跨越 WSL2/Windows 边界

​

选项 2：本机 Chrome MCP

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

​

工作架构

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

​

为什么这个设置会让人困惑

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

​

Control UI 的关键规则

​

分层验证

​

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

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

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

​

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

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 端来说地址不正确
• 防火墙 / 端口转发 / 本地代理仍然缺失

​

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

{
  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 socket URL 时才使用 WS(S)
• 在期望 OpenClaw 成功之前，先用 curl 测试同一个 URL

​

第 4 层：单独验证 Control UI 层

• 页面来源与 gateway.controlUi.allowedOrigins 的预期一致
• token 认证或配对配置正确
• 你没有把 Control UI 认证问题当成浏览器问题来排查

• Control UI

​

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

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

• 标签页在 Windows Chrome 中打开
• openclaw browser tabs 返回目标
• 后续操作（snapshot、screenshot、navigate）可以通过同一配置文件正常工作

​

常见的误导性错误

• control-ui-insecure-auth
  • UI 来源 / 安全上下文问题，不是 CDP 传输问题
• token_missing
  • 认证配置问题
• pairing required
  • 设备批准问题
• Remote CDP for profile "remote" is not reachable
  • WSL2 无法访问所配置的 cdpUrl
• Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable
  • HTTP 端点已响应，但仍无法打开 DevTools WebSocket
• 远程会话后 viewport / 深色模式 / locale / offline 覆盖状态残留
  • 运行 openclaw browser stop --browser-profile remote
  • 这会关闭活动控制会话，并释放 Playwright/CDP 的模拟状态，而无需重启 gateway 或外部浏览器
• gateway timeout after 1500ms
  • 通常仍然是 CDP 可达性问题，或者远程端点较慢/不可达
• No Chrome tabs found for profile="user"
  • 选择了本机 Chrome MCP 配置文件，但没有可用的本机标签页

​

快速分诊清单

1. Windows：curl http://127.0.0.1:9222/json/version 能工作吗？
2. WSL2：curl http://WINDOWS_HOST_OR_IP:9222/json/version 能工作吗？
3. OpenClaw 配置：browser.profiles.<name>.cdpUrl 是否使用了那个精确的、WSL2 可访问的地址？
4. Control UI：你打开的是 http://127.0.0.1:18789/，而不是 LAN IP 吗？
5. 你是不是在尝试跨 WSL2 和 Windows 使用 existing-session，而不是原始远程 CDP？

​

实用结论

• 先在本机验证 Windows Chrome 端点
• 再从 WSL2 验证同一个端点
• 然后才去排查 OpenClaw 配置或 Control UI 认证

​

相关内容

• Browser
• Browser login
• Browser Linux troubleshooting