5.4 浏览器工具与网页自动化

浏览器工具用于将“访问网页、登录、点击、抓取”等交互转换为可控的工具调用，使智能体能按需获取网页信息或执行操作。本节说明浏览器工具的使用边界、常用命令，以及如何把网页自动化纳入工具策略与排障闭环。

5.4.1 能力与边界：把网页操作做成有界工具

浏览器自动化的工程难点在于“如何可控”。应将浏览器能力视为高风险工具（可跨站访问、读取页面、触发外部副作用），并将边界前置到两处：

1. 工具策略：通过允许、拒绝与分层策略控制哪些智能体可以使用浏览器相关工具，拒绝规则优先于允许规则。详见 5.2 工具策略：允许、拒绝与分层策略 与官方工具文档 https://docs.openclaw.ai/tools。

2. 交互流程：把网页操作拆成可验证步骤，每一步都要有可检查的成功条件，并在失败时输出下一步排障命令。

5.4.2 浏览器能力分层：从搜索到视觉的四个层级

并非所有网页交互都需要启动完整浏览器。实践中，网页相关能力可按成本、复杂度和适用场景分为四个渐进层级， 优先使用低层级，仅在不够用时才升级到高层级 。

四层能力详解

层级	能力	适用场景	依赖	性能与成本
L0	搜索引擎 + 网页抓取	日常信息检索（覆盖 80% 场景）	Brave Search + Readability / jina.ai	最低
L1	无头浏览器（Headless Chrome）	需要 JavaScript 渲染的 SPA 页面	Headless Chrome	低
L2	有头浏览器 + DOM 操作	需要登录、填表单、点按钮	Chrome + 虚拟桌面（Xvfb）	中，需 ≥4G 内存
L3	截图 + 视觉识别	信息只存在于图片中（商品图、图表、参数表）	有头浏览器 + 多模态模型	最高，速度最慢

决策逻辑

1. 先尝试 L0：能用搜索 + 抓取拿到信息，就不要启动浏览器。

2. L0 抓取为空白（典型症状：SPA 页面只有骨架 HTML）→ 升级到 L1。

3. L1 仍无法完成（需要登录、点击、填写表单）→ 升级到 L2。

4. L2 无法获取的信息（嵌入在图片中的文字、图表数据）→ 最后使用 L3。

[!NOTE] 在云服务器上使用 L2 和 L3，需要先安装虚拟桌面服务（如 Xvfb），它会在内存中模拟一个显示器，让有头浏览器能在无物理显示器的环境下运行。安装方式：`sudo apt-get install xvfb`。

5.4.3 常用命令：启动、检查与打开页面

以下命令可用于启动浏览器服务、检查状态以及打开页面：浏览器工具参考。

在需要浏览器能力前，建议先检查状态，再按需启动。

openclaw browser status
openclaw browser start

当浏览器服务可用后，可以用 `browser open` 快速打开目标页面，便于验证环境与网络是否正常。

openclaw browser open "https://example.com"

如果需要停止浏览器服务，可使用 `browser stop`。

openclaw browser stop

5.4.4 与网页工具协作：优先读工具，必要时才用浏览器

网页相关能力通常分两类：

1. 读为主的网页获取与解析，适合用网页工具完成，结果更易结构化与回注。

2. 必须交互的场景，例如登录后页面、复杂表单、或需要执行脚本的页面，才引入浏览器工具。

工程上建议优先使用读工具获取信息，仅在读工具无法覆盖时再使用浏览器，以减少不确定交互带来的故障面。详情参考 网页工具说明。

5.4.5 验收与排障：用状态命令与日志定位问题层级

浏览器相关问题的排障建议按层级收敛：

1. 先用 `browser status` 判断服务是否在线。

2. 再用 `browser open` 验证网络与页面可达性。

3. 最后用系统日志定位是否为工具策略、路由或会话问题。

openclaw browser status
openclaw status --deep
openclaw logs --follow --json

当出现“能打开页面但智能体无法完成任务”时，优先检查工具策略是否拒绝了浏览器相关工具；当出现“浏览器无法启动”时，优先检查依赖与运行环境，并先跑 `doctor` 获取结构化的自检结果。

openclaw doctor