OpenClaw Browser：浏览器控制入门

目录

• • 摘要
  • [1. 引言 - 为什么需要浏览器控制？](#1. 引言 - 为什么需要浏览器控制？)
  • • [1.1 浏览器自动化的价值](#1.1 浏览器自动化的价值)
    • [1.2 OpenClaw Browser 架构](#1.2 OpenClaw Browser 架构)
    • [1.3 Browser 工具能力概览](#1.3 Browser 工具能力概览)
  • [2. Browser 工具基础](#2. Browser 工具基础)
  • • [2.1 工具签名](#2.1 工具签名)
    • [2.2 支持的操作类型](#2.2 支持的操作类型)
    • [2.3 浏览器配置](#2.3 浏览器配置)
  • [3. 快速开始](#3. 快速开始)
  • • [3.1 检查浏览器状态](#3.1 检查浏览器状态)
    • [3.2 启动浏览器](#3.2 启动浏览器)
    • [3.3 打开网页](#3.3 打开网页)
    • [3.4 获取页面快照](#3.4 获取页面快照)
    • [3.5 截取页面图像](#3.5 截取页面图像)
  • [4. 页面快照详解](#4. 页面快照详解)
  • • [4.1 什么是页面快照？](#4.1 什么是页面快照？)
    • [4.2 快照内容](#4.2 快照内容)
    • [4.3 引用类型](#4.3 引用类型)
    • [4.4 快照示例](#4.4 快照示例)
  • [5. 页面交互操作](#5. 页面交互操作)
  • • [5.1 点击操作](#5.1 点击操作)
    • [5.2 输入操作](#5.2 输入操作)
    • [5.3 按键操作](#5.3 按键操作)
    • [5.4 滚动操作](#5.4 滚动操作)
    • [5.5 等待操作](#5.5 等待操作)
  • [6. 实战案例](#6. 实战案例)
  • • [6.1 案例一：自动登录网站](#6.1 案例一：自动登录网站)
    • [6.2 案例二：抓取商品信息](#6.2 案例二：抓取商品信息)
    • [6.3 案例三：表单自动填写](#6.3 案例三：表单自动填写)
  • [7. Chrome 扩展模式](#7. Chrome 扩展模式)
  • • [7.1 什么是 Chrome 扩展模式？](#7.1 什么是 Chrome 扩展模式？)
    • [7.2 配置步骤](#7.2 配置步骤)
    • [7.3 使用示例](#7.3 使用示例)
    • [7.4 注意事项](#7.4 注意事项)
  • [8. 高级功能](#8. 高级功能)
  • • [8.1 执行 JavaScript](#8.1 执行 JavaScript)
    • [8.2 处理弹窗](#8.2 处理弹窗)
    • [8.3 上传文件](#8.3 上传文件)
    • [8.4 处理多标签页](#8.4 处理多标签页)
  • [9. 最佳实践](#9. 最佳实践)
  • • [9.1 等待策略](#9.1 等待策略)
    • [9.2 错误处理](#9.2 错误处理)
    • [9.3 性能优化](#9.3 性能优化)
  • [10. 常见问题与解决](#10. 常见问题与解决)
  • • Q1：页面加载慢怎么办？
    • Q2：元素找不到怎么办？
    • [Q3：Chrome 扩展无法连接？](#Q3：Chrome 扩展无法连接？)
  • [11. 总结](#11. 总结)
  • • [11.1 核心要点](#11.1 核心要点)
    • [11.2 操作清单](#11.2 操作清单)
    • [11.3 下一步](#11.3 下一步)
  • 参考资料

摘要

本文介绍 OpenClaw 框架中的浏览器控制功能。从 Browser 工具基础、核心操作、快照机制到自动化流程，全面解析如何通过 AI Agent 控制浏览器完成网页操作任务。通过实际案例演示网页导航、表单填写、数据抓取等典型场景，帮助开发者构建具有浏览器自动化能力的智能应用。🌐

---

1. 引言 - 为什么需要浏览器控制？

1.1 浏览器自动化的价值

场景	说明	示例
数据采集	自动抓取网页数据	爬取商品价格
表单操作	自动填写和提交表单	自动报名、注册
网页测试	自动化 UI 测试	功能回归测试
内容监控	监控网页变化	价格变动提醒
交互操作	模拟用户操作	自动点赞、评论

1.2 OpenClaw Browser 架构

OpenClaw Browser 架构
AI Agent
Browser Tool
浏览器类型
Chrome 扩展
内置浏览器
用户现有标签页
独立浏览器实例
页面操作
导航
快照
截图
交互

1.3 Browser 工具能力概览

能力	说明	应用场景
导航	打开网页、前进后退	网页浏览
快照	获取页面结构和元素	页面分析
截图	捕获页面图像	记录、报告
交互	点击、输入、滚动	表单操作
执行	运行 JavaScript	高级操作

---

2. Browser 工具基础

2.1 工具签名

browser(
    action: str,           # 操作类型
    targetUrl: str,        # 目标 URL
    targetId: str,         # 标签页 ID
    profile: str,          # 浏览器配置
    # ... 其他参数
)

2.2 支持的操作类型

Action	说明	参数
status	查看浏览器状态	-
start	启动浏览器	profile
stop	停止浏览器	-
open	打开网页	targetUrl
navigate	导航到 URL	targetUrl
snapshot	获取页面快照	refs
screenshot	截取页面图像	fullPage
act	执行交互操作	kind, ref
close	关闭标签页	targetId

2.3 浏览器配置

Profile	说明	使用场景
chrome	Chrome 扩展模式	使用用户现有标签页
openclaw	内置浏览器	独立浏览器实例

---

3. 快速开始

3.1 检查浏览器状态

browser(action="status")

返回示例：

{
  "status": "running",
  "browsers": ["chrome"],
  "tabs": [
    {
      "id": "ABC123",
      "url": "https://example.com",
      "title": "Example Domain"
    }
  ]
}

3.2 启动浏览器

# 启动内置浏览器
browser(action="start", profile="openclaw")

# 或使用 Chrome 扩展模式
browser(action="start", profile="chrome")

3.3 打开网页

browser(
    action="open",
    targetUrl="https://www.example.com"
)

3.4 获取页面快照

browser(
    action="snapshot",
    targetId="ABC123"  # 标签页 ID
)

3.5 截取页面图像

browser(
    action="screenshot",
    targetId="ABC123",
    fullPage=True  # 全页面截图
)

---

4. 页面快照详解

4.1 什么是页面快照？

页面快照是 OpenClaw Browser 的核心功能，它将网页转换为结构化的可操作对象。

4.2 快照内容

{
  "elements": [
    {
      "ref": "e1",
      "type": "button",
      "text": "登录",
      "attributes": {
        "class": "btn-primary",
        "disabled": false
      }
    },
    {
      "ref": "e2",
      "type": "textbox",
      "placeholder": "请输入用户名",
      "value": ""
    }
  ]
}

4.3 引用类型

Refs 类型	说明	使用场景
role	基于角色和名称	通用场景
aria	Playwright aria-ref	精确定位

4.4 快照示例

# 获取基于角色的快照
browser(
    action="snapshot",
    targetId="ABC123",
    refs="role"
)

# 获取基于 aria 的快照
browser(
    action="snapshot",
    targetId="ABC123",
    refs="aria"
)

---

5. 页面交互操作

5.1 点击操作

browser(
    action="act",
    targetId="ABC123",
    kind="click",
    ref="e1"  # 元素引用
)

5.2 输入操作

browser(
    action="act",
    targetId="ABC123",
    kind="type",
    ref="e2",  # 输入框引用
    text="Hello World"
)

5.3 按键操作

browser(
    action="act",
    targetId="ABC123",
    kind="press",
    key="Enter"
)

5.4 滚动操作

browser(
    action="act",
    targetId="ABC123",
    kind="scroll",
    y=500  # 滚动距离
)

5.5 等待操作

browser(
    action="act",
    targetId="ABC123",
    kind="wait",
    timeMs=2000  # 等待 2 秒
)

---

6. 实战案例

6.1 案例一：自动登录网站

场景：自动登录一个网站

# 1. 打开登录页面
browser(
    action="open",
    targetUrl="https://example.com/login"
)

# 2. 获取页面快照
snapshot = browser(
    action="snapshot",
    refs="role"
)

# 3. 输入用户名
browser(
    action="act",
    kind="type",
    ref="textbox[用户名]",
    text="myusername"
)

# 4. 输入密码
browser(
    action="act",
    kind="type",
    ref="textbox[密码]",
    text="mypassword"
)

# 5. 点击登录按钮
browser(
    action="act",
    kind="click",
    ref="button[登录]"
)

6.2 案例二：抓取商品信息

场景：从电商网站抓取商品信息

# 1. 打开商品页面
browser(
    action="open",
    targetUrl="https://shop.example.com/product/123"
)

# 2. 等待页面加载
browser(
    action="act",
    kind="wait",
    timeMs=2000
)

# 3. 获取页面快照
snapshot = browser(
    action="snapshot",
    refs="role"
)

# 4. 提取商品信息
# AI 会自动从快照中提取：
# - 商品名称
# - 价格
# - 描述
# - 评价数量

6.3 案例三：表单自动填写

场景：自动填写注册表单

# 1. 打开注册页面
browser(
    action="open",
    targetUrl="https://example.com/register"
)

# 2. 填写表单
form_data = {
    "姓名": "张三",
    "邮箱": "zhangsan@example.com",
    "电话": "13800138000",
    "地址": "北京市朝阳区"
}

for field, value in form_data.items():
    browser(
        action="act",
        kind="type",
        ref=f"textbox[{field}]",
        text=value
    )

# 3. 勾选同意条款
browser(
    action="act",
    kind="click",
    ref="checkbox[同意条款]"
)

# 4. 提交表单
browser(
    action="act",
    kind="click",
    ref="button[提交]"
)

---

7. Chrome 扩展模式

7.1 什么是 Chrome 扩展模式？

Chrome 扩展模式允许 AI Agent 控制用户现有的 Chrome 浏览器标签页。

7.2 配置步骤

1. 安装 OpenClaw Browser Relay 扩展
2. 点击扩展图标激活
3. 在需要控制的标签页上点击扩展按钮
4. Badge 显示 "ON" 表示已连接

7.3 使用示例

# 使用 Chrome 扩展模式
browser(
    action="open",
    targetUrl="https://example.com",
    profile="chrome"
)

# 后续操作会作用于用户当前的 Chrome 标签页

7.4 注意事项

注意项	说明
需要激活	必须点击扩展按钮激活
单标签页	一次只能控制一个标签页
权限限制	某些特殊页面无法控制

---

8. 高级功能

8.1 执行 JavaScript

browser(
    action="act",
    kind="evaluate",
    fn="() => document.title"
)

8.2 处理弹窗

# 接受弹窗
browser(
    action="dialog",
    accept=True
)

# 取消弹窗
browser(
    action="dialog",
    accept=False
)

8.3 上传文件

browser(
    action="upload",
    ref="input[type=file]",
    filePath="/path/to/file.pdf"
)

8.4 处理多标签页

# 获取所有标签页
tabs = browser(action="tabs")

# 切换到指定标签页
browser(
    action="focus",
    targetId="XYZ789"
)

# 关闭标签页
browser(
    action="close",
    targetId="XYZ789"
)

---

9. 最佳实践

9.1 等待策略

策略	说明	使用场景
固定等待	等待固定时间	简单场景
元素等待	等待元素出现	动态加载页面
状态等待	等待特定状态	复杂交互

9.2 错误处理

def safe_browser_action(action, retries=3):
    """安全的浏览器操作"""
    for i in range(retries):
        try:
            result = browser(action=action)
            return result
        except Exception as e:
            if i == retries - 1:
                raise
            # 等待后重试
            time.sleep(1)

9.3 性能优化

优化项	说明
减少快照	只在需要时获取快照
批量操作	合并多个操作
缓存结果	缓存页面数据

---

10. 常见问题与解决

Q1：页面加载慢怎么办？

解决方案：

1. 增加等待时间
2. 使用元素等待而非固定等待
3. 检查网络状态

Q2：元素找不到怎么办？

解决方案：

1. 刷新快照
2. 使用不同的 refs 类型
3. 检查元素是否在 iframe 中

Q3：Chrome 扩展无法连接？

解决方案：

1. 确认扩展已安装并激活
2. 检查 Badge 是否显示 ON
3. 刷新页面后重试

---

11. 总结

11.1 核心要点

要点	说明
快照优先	先获取快照再操作
引用定位	使用 ref 定位元素
等待加载	确保页面加载完成
错误处理	添加重试机制

11.2 操作清单

• 检查浏览器状态
• 打开目标网页
• 获取页面快照
• 执行交互操作
• 验证操作结果

11.3 下一步

• 第47篇：OpenClaw Browser 快照：页面分析与操作
• 第48篇：OpenClaw Browser 自动化：表单填写实战

---

参考资料

• OpenClaw 官方文档
• Playwright 文档
• Chrome 扩展开发