浏览器故障排除

对于特定于 Linux 的问题（尤其是 snap Chromium），请参阅浏览器故障排查。

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

检查超时但截图正常¶

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

使用相同的配置文件和目标 ID 重试一次检查。如果仍然失败，请在重启 Gateway 之前运行 openclaw browser doctor 并检查截图。浏览器渲染的 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>
• 当配置了回环外部 CDP 服务但未设置 attachOnly: true 时，出现 Port <port> is in use for profile "<name>" but not by openclaw
• 导航 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 目标被允许。

重置或删除本地托管配置文件时，会在移动其数据之前停止由先前 Gateway 运行时留下的已验证浏览器。如果无法验证或停止活动的配置文件所有者，OpenClaw 会保留配置文件数据并报告原因。请关闭使用该配置文件的浏览器，并在重试前检查其 Chromium 锁。指向其他主机名的锁仍然无法验证，即使在机器重命名后也是如此；启动浏览器也会保留该锁定配置文件的偏好设置。

安全指南：

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