使用方式

1. 查看浏览器状态

browser action=status

2. 启动浏览器

browser action=start

3. 打开网页

browser action=open url="https://example.com"

4. 截图

// 普通截图
browser action=screenshot

// 全页截图
browser action=screenshot fullPage=true

// 带标签的截图（显示元素编号）
browser action=snapshot labels=true

5. 获取页面快照

// AI 快照（带数字编号，适合点击操作）
browser action=snapshot

// 交互式快照（推荐，更稳定）
browser action=snapshot interactive=true

// 紧凑模式
browser action=snapshot compact=true

6. 点击元素

// 使用快照返回的数字 ref
browser action=act kind=click ref="12"

// 使用 role ref
browser action=act kind=click ref="e12"

7. 输入文本

// 输入文本并提交
browser action=act kind=type ref="23" text="hello" submit=true

// 输入后按回车
browser action=act kind=press key="Enter"

8. 等待元素

// 等待文本出现
browser action=wait text="完成"

// 等待 URL 变化
browser action=wait url="**/dashboard"

// 等待加载状态
browser action=wait load=networkidle

// 组合等待
browser action=wait selector="#main" url="**/dash" load=networkidle

9. 标签页操作

// 打开新标签页
browser action=open url="https://example.com"

// 列出标签页
browser action=tabs

// 切换到指定标签页
browser action=focus targetId="abcd1234"

// 关闭标签页
browser action=close targetId="abcd1234"

10. 文件上传

// 上传文件
browser action=upload filePath="/tmp/openclaw/uploads/file.pdf"

11. 滚动页面

// 滚动到元素可见
browser action=act kind=scrollIntoView ref="e12"

// 滚动到顶部/底部
browser action=act kind=evaluate fn="window.scrollTo(0, document.body.scrollHeight)"

12. 设置浏览器状态

// 设置离线模式
browser action=set offline=true

// 设置自定义 Headers
browser action=set headers="{\"X-Debug\":\"1\"}"

// 设置地理位置
browser action=set geo="37.7749,-122.4194"

// 设置 User Agent / 设备
browser action=set device="iPhone 14"

快照引用 (Refs) 详解

AI 快照 (默认)

返回带数字编号的快照 (1, 2, 3...)
点击时使用 ref="12" 这样的数字

Role 快照 (推荐)

使用 --interactive 或 --compact 参数
返回 [ref=e12] 格式的角色引用
更稳定，不依赖 DOM 结构变化

重要提示

Refs 在页面导航后会失效，每次操作前建议重新获取快照
使用 highlight 可以高亮显示目标元素，验证点击位置

常见工作流

登录网页示例

browser action=open url="https://example.com/login"
browser action=snapshot → 获取快照
browser action=act kind=type ref="5" text="username" → 输入用户名
browser action=act kind=type ref="6" text="password" → 输入密码
browser action=act kind=click ref="7" → 点击登录按钮
browser action=wait url="**/dashboard" → 等待跳转

填写表单示例

打开页面
browser action=snapshot interactive=true

使用 fill 批量填充多个字段：

browser action=act kind=fill fields='[{"ref":"1","type":"text","value":"张三"},{"ref":"2","type":"text","value":"25"}]'

下载文件示例

点击下载链接
browser action=waitfordownload filename="report.pdf"
文件保存到 /tmp/openclaw/downloads/

调试技巧

查看控制台错误

browser action=console level="error"

查看网络请求

browser action=requests filter="api"

录制 Trace

browser action=trace_start
// 执行操作
browser action=trace_stop

高亮元素

browser action=highlight ref="e12"

参数说明

参数	类型	说明
action	string	操作类型：status, start, stop, tabs, open, focus, close, snapshot, screenshot, act, navigate, wait, upload 等
url	string	目标 URL
profile	string	浏览器配置：openclaw (默认) / chrome (使用你的 Chrome)
target	string	浏览器目标：sandbox / host / node
ref	string	元素引用编号
text	string	输入的文本
fullPage	boolean	是否截取完整页面
interactive	boolean	是否使用交互式快照
compact	boolean	是否使用紧凑模式
kind	string	操作类型：click, type, press, hover, scroll, select, drag, fill, evaluate

注意事项

安全：浏览器可能包含登录会话，请勿分享浏览器状态
Refs：每次页面变化后需要重新获取快照
等待：网络慢的页面记得增加等待时间
调试：先用 snapshot 查看页面结构，再进行操作

功能	说明
打开网页	导航到指定 URL
截图	页面截图或全页截图
快照	获取页面 DOM 快照（AI 快照或 ARIA 快照）
点击	点击页面元素
输入	在输入框中输入文本
滚动	滚动页面
等待	等待元素/文本/URL 加载
标签页管理	打开/切换/关闭标签页
文件上传	上传文件到网页
下载	从网页下载文件

bb-browser

bb-browser 浏览器控制工具

核心功能