跳转至

浏览器故障排除

对于 Linux 特定问题(尤其是 snap Chromium),请参阅 浏览器故障排除。

对于 WSL2 Gateway + Windows Chrome 分主机设置,请参阅 WSL2 + Windows + 远程 Chrome CDP 故障排除。

检查超时但截图正常

快照和页面文本读取使用浏览器自动化连接,即使标签页列表和截图仍然可用,该连接也可能变得陈旧。当该连接无法再解析所请求的标签页时,OpenClaw 会重新连接一次。无响应的同级标签页共享一次目标检查等待,而不是为每个标签页添加单独的等待。

使用相同的配置文件和目标 ID 重试一次检查。如果仍然失败,请运行 openclaw browser doctor,并在重启 Gateway 之前检查一张截图。浏览器渲染的 HTTP 错误(例如 403 Forbidden)表明网站拒绝了访问;它不能证明某个配置文件或资源是否存在。

输出目录错误

如果输出因 Invalid path: must stay within output directory 而失败,请将输出目录设置为其真实、规范的路径。浏览器输出会拒绝目录路径中任何位置的用户创建符号链接,包括最终目录已经存在的情况。macOS 的 /tmp 和 /var 系统别名仍然受支持。

CDP 启动失败与导航 SSRF 阻止

这些是不同的故障类别,并且指向不同的代码路径。

  • CDP 启动或就绪失败 表示 OpenClaw 无法确认浏览器控制平面健康。
  • 导航 SSRF 阻止 表示浏览器控制平面健康,但页面导航目标被策略拒绝。

常见示例:

  • CDP 启动或就绪失败:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • Port <port> is in use for profile "<name>" but not by openclaw,当配置了回环外部 CDP 服务但未设置 attachOnly: true 时
  • 导航 SSRF 阻止:
  • open、navigate、快照或打开标签页流程因浏览器/网络策略错误而失败,而 start 和 tabs 仍然可用

使用以下最小序列来区分这两者:

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

如何解读结果:

  • 如果 start 因 not reachable after start 失败,请先排查 CDP 就绪状态。
  • 如果 start 成功但 tabs 失败,控制平面仍然不健康。应将其视为 CDP 可达性问题,而不是页面导航问题。
  • 如果 start 和 tabs 成功但 open 或 navigate 失败,浏览器控制平面已启动,故障位于导航策略或目标页面。
  • 如果 start、tabs 和 open 全部成功,基本受管浏览器控制路径是健康的。

重要行为细节:

  • 即使未配置 browser.ssrfPolicy,浏览器配置也默认使用一个失败关闭的 SSRF 策略对象。
  • 对于本地回环 openclaw 受管配置文件,CDP 健康检查会故意跳过针对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。
  • 启动本地受管浏览器后,就绪检查允许每个 HTTP 请求最多 1.5 秒,每个 WebSocket 阶段最多 2 秒,以容忍 Gateway 调度延迟。就绪重试窗口为八秒;接近窗口末尾的检查使用更短的超时。
  • 后续操作在决定某个拥有的受管浏览器需要重启之前,会使用相同的就绪宽限。停止配置文件会中止其待处理的发现和就绪检查;取消一个等待共享启动的调用者不会停止该共享启动。
  • 导航保护是独立的。start 或 tabs 成功并不意味着后续的 open 或 navigate 目标被允许。

重置或删除本地受管配置文件时,OpenClaw 会在移动其数据之前停止由较早 Gateway 运行时遗留的已验证浏览器。如果无法验证或停止正在运行的配置文件所有者,OpenClaw 会保留配置文件数据并报告原因。重试前,请关闭使用该配置文件的浏览器,并检查其 Chromium 锁。命名其他主机名的锁仍保持未验证状态,包括机器重命名之后;启动浏览器也会保留该锁定配置文件的偏好设置。

安全指南:

  • 默认情况下,不要放宽浏览器 SSRF 策略。
  • 优先使用窄范围的精确主机名 allowedHostnames 例外,而不是宽泛的私有网络访问。
  • 仅在有意信任的环境中,并且需要且已审查私有网络浏览器访问时,才使用 dangerouslyAllowPrivateNetwork: true。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw