浏览器故障排除
对于 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 startRemote 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