在 WSL2 使用远程 CDP 时，OpenClaw 浏览器截图可能超时（v2026.3.23）

有用户反馈：在 WSL2 里通过 远程 CDP 连接 Windows Chrome 时，升级到 OpenClaw 2026.3.23 后会出现一种很“卡脖子”的问题：

browser snapshot（无障碍树 / 文字模式）可以正常工作
CDP 的 HTTP 端点也正常（能列出 tabs）
但 browser screenshot 反复超时

来源：

Issue： openclaw/openclaw#54148

哪些环境更容易中招

如果你的架构类似下面这样，基本就是命中范围：

Chrome 跑在 Windows 上，并带参数 --remote-debugging-port=9222
OpenClaw 跑在 WSL2（例如 Ubuntu 24.04 / Windows 11）
OpenClaw 的浏览器 profile 使用 cdpUrl 连接远程调试端口，例如：

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

如何确认你遇到的是同一类问题

在 WSL2 内执行：

先确认 CDP 的 HTTP 端点通不通：

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

能返回 JSON，说明 CDP 在 HTTP 层面是可达的。

再确认 OpenClaw 的“非截图”路径是否正常：

如果 browser snapshot 正常，但 browser screenshot 超时，通常不是“CDP 根本连不上”的问题，而更像是 截图那条链路发生了超时/卡住。

3)（可选）用 OpenClaw 之外的方法验证“截图其实可行”

该 issue 中，报告者用 CDP WebSocket 直接调用 Page.captureScreenshot 可以拿到有效 PNG。这个信息很关键，因为它意味着：

Chrome 在该环境下具备截图能力
更可能是 OpenClaw 的 screenshot 实现路径触发了超时

WSL2 里一个常见坑：不要误用 “existing-session” 驱动

报告者尝试过 driver: "existing-session"，并遇到 DevToolsActivePort 相关报错。

这在 Chrome 跑在 Windows 的前提下很常见：

DevToolsActivePort 是本机启动 Chrome 时生成的 本地文件
它不会出现在 WSL2 的文件系统里

因此 WSL2 → Windows Chrome 这种形态通常应该走 remote CDP URL，而不是依赖本地端口文件的 attach 方式。

临时绕过方案（等官方修复前）

方案 A：能不用截图就先用 snapshot

如果你的任务并不强依赖 PNG，先用 browser snapshot 继续推进流程，至少不被完全卡死。

方案 B：回退到已知可用版本

如果截图是强需求，可以考虑回退到你环境里最后一个稳定可用的版本。

该 issue 的信息显示：从 v2026.3.13 升到 v2026.3.23 后开始出现超时。

方案 C：把“截图”这一步临时外置（直连 CDP）

如果你能接受“临时多一段脚本”，可以用独立的 CDP 客户端去执行截图（该报告使用了 Python 的 WebSocket 客户端调用 Page.captureScreenshot）。

不完美，但能把截图这一步单独救活，而不影响你其他仍在 OpenClaw 内的自动化。

值班团队先判断什么情况下该优先怀疑这是 OpenClaw 回归，而不是 Windows 或 WSL2 网络问题

如果 /json/version 还能正常返回，browser snapshot 也还能工作，但只有 browser screenshot 在升级后开始超时，就应该先把怀疑重点放在 OpenClaw 的 screenshot 实现路径，而不是先重做整套 Windows、WSL2 或 Chrome 联通性排查。

更像是 OpenClaw screenshot 回归 的信号包括：

升级前同一套 WSL2 → Windows Chrome 远程 CDP 架构可以正常截图
升级后只有截图超时，snapshot 和 tab listing 仍正常
直接调用 CDP Page.captureScreenshot 仍能拿到有效图片

更像是 环境或网络层问题 的信号包括：

/json/version 本身已经不通
browser snapshot 也一起失败
Chrome 远程调试端口、Windows 防火墙或监听地址最近发生过变化

这个判断顺序很重要，因为很多团队会在这里浪费时间，把“截图链路回归”误当成“WSL2 到 Windows 根本连不上”。

反馈给维护者时建议带上的信息

为了更快复现，建议附上：

OpenClaw 版本与 commit hash
WSL2 发行版 + Windows 版本
Chrome 版本 + 启动参数
browser profile 配置（cdpUrl、attachOnly、driver 等）
/json/version 是否可达
snapshot 是否可用
是否能通过 CDP WebSocket 直接 Page.captureScreenshot

WSL2 remote CDP 超时时，先分清三层连接

浏览器截图超时不要一上来就重启 agent。更稳的排查顺序是先把链路拆成三层：

WSL2 到 Windows Chrome 的 CDP 端口是否能连通，先用 /json/version 确认不是网络层断开；
OpenClaw 的 browser profile 是否指向同一个 remote debugging endpoint，避免 agent 连到空 profile 或旧进程；
页面本身是否已经加载完成，截图超时有时只是目标页卡在登录、弹窗或跨域资源上。

这三层都确认后，再判断是不是 OpenClaw browser tool 的超时参数或上游回归。这样能承接 “WSL2 remote CDP timeout”“OpenClaw browser screenshot timeout” 这类搜索，把读者从盲目重启带到可复现诊断。

来源

openclaw/openclaw#54148