概述
浏览器工具（Browser Tool）是 OpenClaw 内置的核心工具之一，赋予 AI 代理直接操控网页的能力。借助这个工具，代理可以导航网页、提取内容、填写表单、点击按钮、截取屏幕截图，甚至执行复杂的多步骤网页交互流程。
工具架构
OpenClaw 的浏览器工具通过沙箱的浏览器桥接机制与真实浏览器实例通信。由于 Pi SDK 是直接嵌入的，浏览器工具作为七阶段工具流水线中"OpenClaw 内置工具"阶段注入的一员，无需额外安装即可使用。
浏览器工具的通信链路为：AI 代理 → 工具调用 → 沙箱浏览器桥接 → 浏览器实例（WebSocket 协议）。这种架构确保了浏览器操作在受控环境中执行。
启用与配置
基本配置
tools:
browser:
enabled: true
headless: true
bridgeUrl: "ws://localhost:9222"
defaultTimeout: 15000
viewport:
width: 1280
height: 720
高级选项
tools:
browser:
userAgent: "OpenClaw-Browser/1.0"
acceptLanguage: "zh-CN,zh;q=0.9,en;q=0.8"
ignoreHTTPSErrors: false
extraHTTPHeaders:
X-Custom-Header: "openclaw"
proxy:
server: "http://proxy.example.com:8080"
核心操作
页面导航
浏览器工具支持标准的页面导航操作。AI 代理可以指示工具打开指定 URL，等待页面加载完成后进行后续操作。导航操作支持设置超时时间和等待条件（如等待特定元素出现）。
元素交互
工具提供了丰富的元素交互能力：
- 点击：通过选择器定位元素并点击
- 填写：向输入框填入文本内容
- 选择：操作下拉菜单选项
- 悬停：将鼠标悬停在元素上方
- 滚动：页面或容器内滚动
元素定位支持 CSS 选择器和文本内容匹配两种方式。AI 代理通常会先使用内容提取功能了解页面结构，再选择合适的定位策略。
内容提取
浏览器工具可以从页面中提取多种类型的内容：
- 文本内容：提取页面的纯文本内容，自动处理隐藏元素和不可见文本
- 结构化数据：提取表格、列表等结构化信息
- 链接信息：获取页面中的所有链接及其文本
- 元数据：读取页面标题、描述、Open Graph 标签等
截图能力
截图是浏览器工具的重要功能之一。支持全页面截图和指定区域截图，输出格式可选 PNG 或 JPEG。截图结果可以直接在对话中展示给用户，或保存到文件系统供后续使用。
tools:
browser:
screenshot:
format: png
quality: 80
fullPage: false
maxWidth: 1920
maxHeight: 1080
多标签页管理
浏览器工具支持同时管理多个标签页。AI 代理可以在不同标签页之间切换，实现跨页面的信息对比和数据整合。为防止资源滥用，沙箱会限制最大标签页数量（默认为 3）。
Cookie 与状态管理
Cookie 操作
工具提供了 Cookie 的读取和设置能力。这对于需要登录状态的操作场景至关重要。管理员可以预配置认证 Cookie，让 AI 代理在需要时自动使用。
会话持久化
浏览器的状态（包括 Cookie 和本地存储）可以在会话之间持久化。这意味着 AI 代理在一次对话中完成的登录操作，在后续对话中仍然有效，无需重复认证。
与其他工具协作
浏览器工具很少单独使用，通常与其他工具配合完成复杂任务：
- 与 web 工具配合：browser 负责交互操作，web 工具负责 API 调用
- 与 canvas 工具配合：从网页提取的数据通过 canvas 工具可视化
- 与 messaging 工具配合：将浏览器截图或提取的信息通过消息工具发送
安全注意事项
- 域名白名单：始终配置
allowedDomains，避免 AI 代理访问不应访问的网站 - 凭据保护：不要在对话中明文传递密码，使用预配置的认证方式
- 下载限制：沙箱默认阻止文件下载，如需开启请谨慎配置允许的文件类型
- JavaScript 执行：浏览器工具支持在页面中注入脚本，这是一个强大但需谨慎使用的能力
故障排查
- 页面加载超时：检查网络连接和
defaultTimeout设置 - 元素找不到：确认选择器是否正确，页面是否完全加载
- 桥接连接失败：验证浏览器实例状态和
bridgeUrl配置 - 截图空白：检查视口大小配置和页面渲染状态
总结
浏览器工具让 OpenClaw 的 AI 代理具备了真正的网页交互能力。通过合理配置和安全约束，它能够安全高效地完成从简单的信息查询到复杂的多步骤网页操作等各类任务。