Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

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

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

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

你有两种有效模式：

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

使用一个远程浏览器 profile，让它从 WSL2 指向 Windows Chrome CDP 端点。 适用场景：
  • Gateway 网关保持运行在 WSL2 中
  • Chrome 运行在 Windows 上
  • 你需要让浏览器控制跨越 WSL2 / Windows 边界

​
选项 2：主机本地 Chrome MCP

仅当 Gateway 网关本身运行在与 Chrome 相同的主机上时，才使用 existing-session / user。 适用场景：
  • OpenClaw 和 Chrome 在同一台机器上运行
  • 你想使用本地已登录的浏览器状态
  • 你不需要跨主机的浏览器传输
  • 你不需要高级托管 / 仅原始 CDP 路径，例如 responsebody、PDF 导出、下载拦截或批量操作
对于 WSL2 Gateway 网关 + Windows Chrome，优先选择原始远程 CDP。Chrome MCP 是主机本地机制，不是 WSL2 到 Windows 的桥接。

​
可工作的架构

参考结构：
  • WSL2 在 127.0.0.1:18789 上运行 Gateway 网关
  • Windows 在普通浏览器中打开 Control UI：http://127.0.0.1:18789/
  • Windows Chrome 在端口 9222 上暴露 CDP 端点
  • WSL2 可以访问该 Windows CDP 端点
  • OpenClaw 将浏览器 profile 指向 WSL2 可访问的地址

​
为什么这个设置容易让人困惑

多个故障可能会重叠：
  • WSL2 无法访问 Windows CDP 端点
  • Control UI 是从非安全来源打开的
  • gateway.controlUi.allowedOrigins 与页面来源不匹配
  • 缺少 token 或配对
  • 浏览器 profile 指向了错误地址
因此，即使修复了一层，仍然可能看到另一种错误。

​
Control UI 的关键规则

当 UI 从 Windows 打开时，除非你明确配置了 HTTPS，否则请使用 Windows localhost。 使用： http://127.0.0.1:18789/ 不要默认对 Control UI 使用局域网 IP。局域网或 tailnet 地址上的纯 HTTP 可能会触发与 CDP 本身无关的不安全来源 / 设备认证行为。参见 Control UI。

​
按层验证

从上到下逐层处理。不要跳步。

​
第 1 层：验证 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。

​
第 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 层：配置正确的浏览器 profile

对于原始远程 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 socket URL 时，才使用 WS(S)
  • 在期待 OpenClaw 成功之前，先用 curl 测试同一个 URL

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

从 Windows 打开 UI： http://127.0.0.1:18789/ 然后验证：
  • 页面来源与 gateway.controlUi.allowedOrigins 的预期一致
  • token 认证或配对已正确配置
  • 你没有把一个 Control UI 认证问题误当成浏览器问题来调试
有帮助的页面：

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

在 WSL2 中： 
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
  • Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable
    • HTTP 端点已经响应，但 DevTools WebSocket 仍无法打开
  • 远程会话结束后出现过期的 viewport / dark-mode / 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 profile，但没有可用的主机本地标签页

​
快速排查清单

  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/，而不是局域网 IP 吗？
  5. 你是否在 WSL2 和 Windows 之间尝试使用 existing-session，而不是原始远程 CDP？

​
实际结论

这个设置通常是可行的。难点在于：浏览器传输、Control UI 来源安全，以及 token / 配对都可能各自独立失败，而从用户侧看起来又很相似。 如果不确定：
  • 先在本地验证 Windows Chrome 端点
  • 再从 WSL2 验证同一个端点
  • 只有在这之后，才去调试 OpenClaw 配置或 Control UI 认证

​
相关内容