OpenClaw 浏览器自动化实战

目录

• • 摘要
  • 1. 引言：为什么需要浏览器自动化？
  • • 1.1 浏览器自动化的应用场景
    • 1.2 传统方案的局限性
    • 1.3 OpenClaw 的解决方案
  • 2. Playwright 基础：浏览器自动化原理
  • • 2.1 什么是 Playwright？
    • 2.2 CDP 协议与浏览器控制
    • 2.3 OpenClaw 如何封装 Playwright
  • 3. OpenClaw Browser 工具详解
  • • 3.1 工具概览
    • 3.2 Snapshot：让 AI "看见" 页面
    • 3.3 Act：执行页面操作
    • 3.4 代码示例：自动化登录流程
  • 4. 浏览器配置详解
  • • 4.1 配置文件结构
    • 4.2 Headless 模式配置
    • 4.3 代理配置
    • 4.4 UserAgent 配置
  • 5. 实战案例
  • • 5.1 案例一：网页截图与监控
    • 5.2 案例二：表单自动填写
    • 5.3 案例三：数据抓取
  • 6. Chrome 扩展集成：Browser Relay
  • • 6.1 什么是 Browser Relay？
    • 6.2 安装与配置
    • 6.3 配置文件说明
    • 6.4 安全注意事项
  • 7. 常见问题与排查
  • • 7.1 浏览器启动失败
    • 7.2 Snapshot 返回空结果
    • 7.3 操作定位失败
    • 7.4 Chrome 扩展无法连接
    • 7.5 Playwright 不可用
  • 8. 总结
  • 参考资料

摘要

本文深入探讨 OpenClaw 框架中的浏览器自动化能力，从 Playwright 基础原理出发，详细解析 OpenClaw Browser 工具的核心 API 与使用方法。通过对比传统 Selenium 方案，展示 OpenClaw 在智能体控制、多配置文件管理、Chrome 扩展集成等方面的独特优势。读者将掌握如何使用 snapshot 与 act 实现智能化的页面交互，配置 headless 模式与代理，以及通过 Browser Relay 实现对现有 Chrome 标签页的安全接管。文章包含网页截图、表单填写、数据抓取等多个实战案例，帮助开发者快速构建可靠的浏览器自动化工作流。最近发现了一个很全面的人工智能学习网站，通俗易懂，风趣幽默，分享一下给大家，需要的可以去点击https://www.captainbed.cn/qiy跳转到网站去看看。

1. 引言：为什么需要浏览器自动化？

1.1 浏览器自动化的应用场景

在当今数字化时代，浏览器已成为我们与互联网交互的核心入口。从电商购物到在线办公，从社交媒体到金融交易，几乎所有的在线活动都通过浏览器完成。然而，许多场景下人工操作浏览器效率低下，甚至无法满足需求：

🎯 自动化测试：Web 应用的功能测试、回归测试、兼容性测试需要反复执行相同的操作流程，人工测试耗时且容易出错。

📊 数据采集：从网页中提取结构化数据，如商品价格、新闻资讯、社交媒体内容等，手动复制粘贴效率极低。

🔄 业务流程自动化：如自动填报表单、批量上传文件、定时执行操作等，减少人工重复劳动。

🤖 AI 智能体交互：让 AI 模型能够"看到"网页、理解页面内容、执行操作，实现真正的智能助手。

1.2 传统方案的局限性

在 OpenClaw 出现之前，浏览器自动化主要依赖以下方案：

这些方案虽然各有优势，但都存在一个共同问题：缺乏与 AI 智能体的原生集成。开发者需要编写大量胶水代码，才能让 AI 模型"理解"页面并执行操作。

1.3 OpenClaw 的解决方案

OpenClaw 通过内置的 browser 工具，将 Playwright 的强大能力封装为智能体友好的 API。核心创新包括：

• Snapshot 机制：将页面转换为结构化的 UI 树，让 AI 能够"阅读"页面内容
• Ref 定位系统：用数字 ID 或角色引用定位元素，告别脆弱的 CSS 选择器
• 多配置文件管理：隔离的浏览器环境，保护用户隐私
• Chrome 扩展集成：通过 Browser Relay 控制现有 Chrome 标签页

#mermaid-svg-UVuP4jvZHTotPOhg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-UVuP4jvZHTotPOhg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-UVuP4jvZHTotPOhg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-UVuP4jvZHTotPOhg .error-icon{fill:#552222;}#mermaid-svg-UVuP4jvZHTotPOhg .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-UVuP4jvZHTotPOhg .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-UVuP4jvZHTotPOhg .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-UVuP4jvZHTotPOhg .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-UVuP4jvZHTotPOhg .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-UVuP4jvZHTotPOhg .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-UVuP4jvZHTotPOhg .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-UVuP4jvZHTotPOhg .marker{fill:#333333;stroke:#333333;}#mermaid-svg-UVuP4jvZHTotPOhg .marker.cross{stroke:#333333;}#mermaid-svg-UVuP4jvZHTotPOhg svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-UVuP4jvZHTotPOhg p{margin:0;}#mermaid-svg-UVuP4jvZHTotPOhg .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-UVuP4jvZHTotPOhg .cluster-label text{fill:#333;}#mermaid-svg-UVuP4jvZHTotPOhg .cluster-label span{color:#333;}#mermaid-svg-UVuP4jvZHTotPOhg .cluster-label span p{background-color:transparent;}#mermaid-svg-UVuP4jvZHTotPOhg .label text,#mermaid-svg-UVuP4jvZHTotPOhg span{fill:#333;color:#333;}#mermaid-svg-UVuP4jvZHTotPOhg .node rect,#mermaid-svg-UVuP4jvZHTotPOhg .node circle,#mermaid-svg-UVuP4jvZHTotPOhg .node ellipse,#mermaid-svg-UVuP4jvZHTotPOhg .node polygon,#mermaid-svg-UVuP4jvZHTotPOhg .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-UVuP4jvZHTotPOhg .rough-node .label text,#mermaid-svg-UVuP4jvZHTotPOhg .node .label text,#mermaid-svg-UVuP4jvZHTotPOhg .image-shape .label,#mermaid-svg-UVuP4jvZHTotPOhg .icon-shape .label{text-anchor:middle;}#mermaid-svg-UVuP4jvZHTotPOhg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-UVuP4jvZHTotPOhg .rough-node .label,#mermaid-svg-UVuP4jvZHTotPOhg .node .label,#mermaid-svg-UVuP4jvZHTotPOhg .image-shape .label,#mermaid-svg-UVuP4jvZHTotPOhg .icon-shape .label{text-align:center;}#mermaid-svg-UVuP4jvZHTotPOhg .node.clickable{cursor:pointer;}#mermaid-svg-UVuP4jvZHTotPOhg .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-UVuP4jvZHTotPOhg .arrowheadPath{fill:#333333;}#mermaid-svg-UVuP4jvZHTotPOhg .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-UVuP4jvZHTotPOhg .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-UVuP4jvZHTotPOhg .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-UVuP4jvZHTotPOhg .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-UVuP4jvZHTotPOhg .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-UVuP4jvZHTotPOhg .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-UVuP4jvZHTotPOhg .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-UVuP4jvZHTotPOhg .cluster text{fill:#333;}#mermaid-svg-UVuP4jvZHTotPOhg .cluster span{color:#333;}#mermaid-svg-UVuP4jvZHTotPOhg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-UVuP4jvZHTotPOhg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-UVuP4jvZHTotPOhg rect.text{fill:none;stroke-width:0;}#mermaid-svg-UVuP4jvZHTotPOhg .icon-shape,#mermaid-svg-UVuP4jvZHTotPOhg .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-UVuP4jvZHTotPOhg .icon-shape p,#mermaid-svg-UVuP4jvZHTotPOhg .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-UVuP4jvZHTotPOhg .icon-shape .label rect,#mermaid-svg-UVuP4jvZHTotPOhg .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-UVuP4jvZHTotPOhg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-UVuP4jvZHTotPOhg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-UVuP4jvZHTotPOhg :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户指令

AI 智能体

browser 工具

snapshot

act

screenshot

UI 树解析

元素定位

点击/输入/导航

页面变化

视觉验证

2. Playwright 基础：浏览器自动化原理

2.1 什么是 Playwright？

Playwright 是由 Microsoft 开发的现代浏览器自动化框架，支持 Chromium、Firefox 和 WebKit 三大浏览器引擎。相比 Selenium，Playwright 具有以下优势：

⚡ 更快的执行速度：基于 WebSocket 通信，而非 HTTP 请求，减少了网络开销。

🔒 更可靠的选择器：支持文本选择器、角色选择器、测试 ID 选择器等多种定位方式。

🌐 跨浏览器支持：一套代码可运行在 Chrome、Firefox、Safari 上。

📱 移动端模拟：支持设备模拟、触摸事件、地理位置等移动端特性。

2.2 CDP 协议与浏览器控制

Playwright 的核心是 Chrome DevTools Protocol (CDP)，这是 Chrome 浏览器暴露的调试接口。通过 CDP，开发者可以：

• 监听网络请求和响应
• 捕获控制台日志和错误
• 模拟用户输入
• 截取屏幕快照
• 执行 JavaScript 代码

图：OpenClaw 浏览器控制架构，展示了 Gateway 网关如何通过 CDP 协议与浏览器通信

浏览器

CDP 客户端

Playwright

自动化脚本

浏览器

CDP 客户端

Playwright

自动化脚本

#mermaid-svg-xuL2EphHuz7rvhQ8{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-xuL2EphHuz7rvhQ8 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-xuL2EphHuz7rvhQ8 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-xuL2EphHuz7rvhQ8 .error-icon{fill:#552222;}#mermaid-svg-xuL2EphHuz7rvhQ8 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-xuL2EphHuz7rvhQ8 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-xuL2EphHuz7rvhQ8 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-xuL2EphHuz7rvhQ8 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-xuL2EphHuz7rvhQ8 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-xuL2EphHuz7rvhQ8 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-xuL2EphHuz7rvhQ8 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-xuL2EphHuz7rvhQ8 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-xuL2EphHuz7rvhQ8 .marker.cross{stroke:#333333;}#mermaid-svg-xuL2EphHuz7rvhQ8 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-xuL2EphHuz7rvhQ8 p{margin:0;}#mermaid-svg-xuL2EphHuz7rvhQ8 .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-xuL2EphHuz7rvhQ8 text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-xuL2EphHuz7rvhQ8 .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-xuL2EphHuz7rvhQ8 .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-xuL2EphHuz7rvhQ8 .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-xuL2EphHuz7rvhQ8 .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-xuL2EphHuz7rvhQ8 #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-xuL2EphHuz7rvhQ8 .sequenceNumber{fill:white;}#mermaid-svg-xuL2EphHuz7rvhQ8 #sequencenumber{fill:#333;}#mermaid-svg-xuL2EphHuz7rvhQ8 #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-xuL2EphHuz7rvhQ8 .messageText{fill:#333;stroke:none;}#mermaid-svg-xuL2EphHuz7rvhQ8 .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-xuL2EphHuz7rvhQ8 .labelText,#mermaid-svg-xuL2EphHuz7rvhQ8 .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-xuL2EphHuz7rvhQ8 .loopText,#mermaid-svg-xuL2EphHuz7rvhQ8 .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-xuL2EphHuz7rvhQ8 .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-xuL2EphHuz7rvhQ8 .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-xuL2EphHuz7rvhQ8 .noteText,#mermaid-svg-xuL2EphHuz7rvhQ8 .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-xuL2EphHuz7rvhQ8 .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-xuL2EphHuz7rvhQ8 .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-xuL2EphHuz7rvhQ8 .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-xuL2EphHuz7rvhQ8 .actorPopupMenu{position:absolute;}#mermaid-svg-xuL2EphHuz7rvhQ8 .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-xuL2EphHuz7rvhQ8 .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-xuL2EphHuz7rvhQ8 .actor-man circle,#mermaid-svg-xuL2EphHuz7rvhQ8 line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-xuL2EphHuz7rvhQ8 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

调用 API

转换为 CDP 命令

WebSocket 消息

执行结果

解析响应

返回数据

2.3 OpenClaw 如何封装 Playwright

OpenClaw 在 Playwright 之上构建了更高层次的抽象：

1. HTTP API 层

Gateway 网关暴露了一组 RESTful API，所有浏览器操作都通过 HTTP 请求完成：

GET /tabs # 列出所有标签页
POST /tabs/open # 打开新标签页
GET /snapshot # 获取页面快照
POST /act # 执行操作
POST /screenshot # 截图

2. 智能体工具层

AI 智能体通过 browser 工具与浏览器交互，无需关心底层实现细节：

{
"action": "snapshot",
"profile": "openclaw"
}

3. 配置管理层

支持多配置文件、远程 CDP、浏览器代理等高级配置，通过 JSON 文件统一管理。

3. OpenClaw Browser 工具详解

3.1 工具概览

browser 工具是 OpenClaw 提供的核心浏览器自动化接口，支持以下操作类型：

3.2 Snapshot：让 AI “看见” 页面

Snapshot 是 OpenClaw 浏览器自动化的核心创新。它将复杂的 HTML 页面转换为结构化的 UI 树，让 AI 模型能够"阅读"并理解页面内容。

图：Snapshot 将 HTML 页面转换为结构化 UI 树，AI 通过 ref 定位元素

AI Snapshot（默认模式）

openclaw browser snapshot

输出示例：

[1] button "登录"
[2] textbox "用户名"
[3] textbox "密码"
[4] link "忘记密码?"
[5] heading "欢迎回来"
[6] image "Logo"

每个元素都有一个数字 ref（如 [1]），后续操作通过这个 ref 定位元素。

Role Snapshot（角色模式）

openclaw browser snapshot –interactive

输出示例：

button "登录" [ref=e1]
textbox "用户名" [ref=e2]
textbox "密码" [ref=e3]
link "忘记密码?" [ref=e4]

角色模式使用 e1、e2 等 ref，基于 Playwright 的 getByRole 定位，更加稳定可靠。

Snapshot 参数详解

3.3 Act：执行页面操作

act 操作用于执行点击、输入、拖拽等用户交互。所有操作都基于 snapshot 返回的 ref。

点击操作

# 使用数字 ref
openclaw browser click 1

# 使用角色 ref
openclaw browser click e1

# 双击
openclaw browser click e1 –double

输入操作

# 输入文本
openclaw browser type e2 "hello@example.com"

# 输入后提交
openclaw browser type e2 "hello@example.com" –submit

其他操作

# 悬停
openclaw browser hover e5

# 拖拽
openclaw browser drag e10 e11

# 下拉选择
openclaw browser select e9 "选项A" "选项B"

# 按键
openclaw browser press Enter

3.4 代码示例：自动化登录流程

以下代码展示了如何使用 OpenClaw CLI 实现完整的登录自动化流程：

#!/bin/bash
# OpenClaw 浏览器自动化登录示例

# 1. 启动浏览器
openclaw browser start

# 2. 打开登录页面
openclaw browser open https://example.com/login

# 3. 等待页面加载
openclaw browser wait –load networkidle

# 4. 获取页面快照，识别表单元素
openclaw browser snapshot –interactive

# 5. 填写用户名（假设 ref=e2）
openclaw browser type e2 "myusername"

# 6. 填写密码（假设 ref=e3）
openclaw browser type e3 "mypassword"

# 7. 点击登录按钮（假设 ref=e1）
openclaw browser click e1

# 8. 等待登录完成
openclaw browser wait –url "**/dashboard"

# 9. 截图验证
openclaw browser screenshot –full-page

# 10. 关闭浏览器
openclaw browser stop

上述脚本展示了 OpenClaw 浏览器自动化的完整流程。首先通过 start 启动浏览器实例，然后使用 open 导航到目标页面。wait –load networkidle 确保页面完全加载后再进行操作。snapshot –interactive 获取页面的可交互元素列表，返回的 ref 用于后续的 type 和 click 操作。最后通过 wait –url 等待页面跳转完成，并用 screenshot 记录结果。这种方式比传统的 CSS 选择器更加稳定，因为 ref 是基于元素的角色和名称生成的，不会因为页面样式变化而失效。

4. 浏览器配置详解

4.1 配置文件结构

OpenClaw 的浏览器配置位于 ~/.openclaw/openclaw.json，支持丰富的自定义选项：

{
browser: {
enabled: true, // 是否启用浏览器功能
defaultProfile: "chrome", // 默认配置文件
headless: false, // 无头模式
noSandbox: false, // 禁用沙箱（服务器环境）
attachOnly: false, // 仅附加，不启动
executablePath: "/usr/bin/brave-browser", // 自定义浏览器路径
color: "#FF4500", // 主题颜色
profiles: {
openclaw: { cdpPort: 18800, color: "#FF4500" },
work: { cdpPort: 18801, color: "#0066CC" },
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }
}
}
}

4.2 Headless 模式配置

Headless 模式（无头模式）是指浏览器在没有图形界面的情况下运行，适用于服务器环境和 CI/CD 流程。

启用 Headless 模式

{
browser: {
headless: true
}
}

CLI 指定

openclaw browser start –headless

使用场景对比

4.3 代理配置

OpenClaw 支持通过浏览器代理访问网络，适用于需要隐藏真实 IP 或访问地区限制内容的场景。

配置代理

目前 OpenClaw 通过 Playwright 的代理配置实现，可以在启动时指定：

# 通过环境变量
HTTP_PROXY=http://proxy.example.com:8080 openclaw browser start

# 或在代码中配置

代理类型支持

4.4 UserAgent 配置

自定义 UserAgent 可以模拟不同的设备和浏览器，用于测试响应式设计或绕过简单的浏览器检测。

设置 UserAgent

# 通过设备预设
openclaw browser set device "iPhone 14"

# 或设置自定义 UserAgent
openclaw browser set headers –json '{"User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)"}'

常用设备预设

5. 实战案例

5.1 案例一：网页截图与监控

网页截图是浏览器自动化最常见的应用之一，可用于监控页面变化、生成报告、视觉回归测试等。

基础截图

# 视口截图
openclaw browser screenshot

# 全页截图
openclaw browser screenshot –full-page

# 元素截图
openclaw browser screenshot –ref e12

自动化监控脚本

#!/usr/bin/env python3
"""
网页监控脚本：定时截图并检测变化
"""

import subprocess
import hashlib
import time
from datetime import datetime

def take_screenshot(url, output_path):
"""使用 OpenClaw 截取网页"""
commands = [
["openclaw", "browser", "start", "–headless"],
["openclaw", "browser", "open", url],
["openclaw", "browser", "wait", "–load", "networkidle"],
["openclaw", "browser", "screenshot", "–full-page", "–output", output_path],
["openclaw", "browser", "stop"]
]

for cmd in commands:
subprocess.run(cmd, capture_output=True)

return output_path

def get_file_hash(filepath):
"""计算文件哈希值"""
with open(filepath, 'rb') as f:
return hashlib.md5(f.read()).hexdigest()

def monitor_page(url, interval=300):
"""监控页面变化"""
last_hash = None

while True:
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
output = f"/tmp/monitor_{timestamp}.png"

take_screenshot(url, output)
current_hash = get_file_hash(output)

if last_hash and current_hash != last_hash:
print(f"[{timestamp}] ⚠️ 页面发生变化！")
# 发送通知…
else:
print(f"[{timestamp}] ✅ 页面无变化")

last_hash = current_hash
time.sleep(interval)

if __name__ == "__main__":
monitor_page("https://example.com", interval=300)

上述 Python 脚本实现了一个简单的网页监控系统。take_screenshot 函数封装了 OpenClaw CLI 的调用流程，从启动浏览器到截图保存。get_file_hash 计算截图的 MD5 哈希值，用于检测页面内容是否发生变化。monitor_page 是主循环，每隔指定时间（默认 5 分钟）截取一次页面，对比哈希值判断是否有变化。如果检测到变化，可以扩展为发送邮件、推送通知等操作。这个脚本适合监控价格变动、新闻更新、服务状态等场景。

5.2 案例二：表单自动填写

表单填写是业务流程自动化的核心需求，OpenClaw 提供了多种方式实现表单操作。

单字段填写

# 获取快照
openclaw browser snapshot –interactive

# 逐个填写
openclaw browser type e2 "张三"
openclaw browser type e3 "zhangsan@example.com"
openclaw browser type e4 "13800138000"

批量填写（fill 命令）

openclaw browser fill –fields '[
{"ref": "e2", "type": "text", "value": "张三"},
{"ref": "e3", "type": "text", "value": "zhangsan@example.com"},
{"ref": "e4", "type": "text", "value": "13800138000"}
]'

处理下拉选择和复选框

# 下拉单选
openclaw browser select e5 "北京"

# 下拉多选
openclaw browser select e6 "技术" "产品" "设计"

# 复选框
openclaw browser click e7 # 点击切换选中状态

完整表单自动化示例

/**
* OpenClaw 表单自动化配置
* 用于批量填写复杂的业务表单
*/

const formConfig = {
// 目标页面
url: "https://example.com/registration",

// 表单字段映射
fields: [
{ name: "姓名", selector: '[name="username"]', value: "李四" },
{ name: "邮箱", selector: '[name="email"]', value: "lisi@example.com" },
{ name: "手机", selector: '[name="phone"]', value: "13900139000" },
{ name: "城市", selector: '[name="city"]', type: "select", value: "上海" },
{ name: "性别", selector: '[name="gender"]', type: "radio", value: "male" },
{ name: "爱好", selector: '[name="hobbies"]', type: "checkbox", values: ["阅读", "运动"] },
{ name: "简介", selector: '[name="bio"]', type: "textarea", value: "这是一段个人简介…" }
],

// 提交按钮
submit: { selector: 'button[type="submit"]' },

// 等待策略
waitAfterSubmit: {
url: "**/success",
timeout: 10000
}
};

// 执行流程：
// 1. openclaw browser open <url>
// 2. openclaw browser snapshot –interactive
// 3. 遍历 fields，根据 type 执行相应操作
// 4. openclaw browser click <submit ref>
// 5. openclaw browser wait –url <waitAfterSubmit.url>

上述配置文件定义了一个完整的表单自动化方案。fields 数组描述了每个表单字段的定位方式和值，支持文本输入、下拉选择、单选、复选等多种类型。submit 指定提交按钮，waitAfterSubmit 定义提交后的等待策略。实际执行时，首先打开页面获取快照，然后根据字段类型依次填写，最后点击提交并等待跳转。这种配置化的方式便于维护和复用，适合批量处理类似的表单任务。

5.3 案例三：数据抓取

OpenClaw 可以用于抓取网页数据，特别是需要 JavaScript 渲染的动态页面。

基础数据提取

# 打开页面
openclaw browser open https://example.com/products

# 等待数据加载
openclaw browser wait –selector ".product-list"

# 获取快照
openclaw browser snapshot –selector ".product-list" –interactive

执行 JavaScript 提取数据

# 使用 evaluate 执行自定义 JS
openclaw browser evaluate –fn '
(() => {
const products = [];
document.querySelectorAll(".product-item").forEach(item => {
products.push({
name: item.querySelector(".name")?.textContent,
price: item.querySelector(".price")?.textContent,
link: item.querySelector("a")?.href
});
});
return JSON.stringify(products);
})()
'

分页抓取脚本

#!/usr/bin/env python3
"""
分页数据抓取脚本
"""

import subprocess
import json

def run_browser_command(cmd_args):
"""执行 OpenClaw CLI 命令"""
result = subprocess.run(
["openclaw", "browser"] + cmd_args,
capture_output=True,
text=True
)
return result.stdout

def scrape_paginated_data(base_url, max_pages=10):
"""抓取分页数据"""
all_data = []

# 启动浏览器
run_browser_command(["start", "–headless"])

# 打开首页
run_browser_command(["open", base_url])
run_browser_command(["wait", "–load", "networkidle"])

for page in range(1, max_pages + 1):
print(f"正在抓取第 {page} 页…")

# 提取当前页数据
js_code = '''
JSON.stringify(
Array.from(document.querySelectorAll(".item")).map(el => ({
title: el.querySelector(".title")?.textContent?.trim(),
price: el.querySelector(".price")?.textContent?.trim()
}))
)
'''

result = run_browser_command(["evaluate", "–fn", js_code])
items = json.loads(result)
all_data.extend(items)

# 尝试点击下一页
snapshot = run_browser_command(["snapshot", "–interactive"])

# 查找"下一页"按钮的 ref（需要解析 snapshot 输出）
# 这里简化处理，实际需要解析文本找到对应 ref
next_result = run_browser_command(["click", "e99"]) # 假设 e99 是下一页

if "error" in next_result.lower():
print("已到达最后一页")
break

run_browser_command(["wait", "–load", "networkidle"])

# 关闭浏览器
run_browser_command(["stop"])

return all_data

if __name__ == "__main__":
data = scrape_paginated_data("https://example.com/list", max_pages=5)
print(f"共抓取 {len(data)} 条数据")
print(json.dumps(data[:3], ensure_ascii=False, indent=2))

上述脚本实现了分页数据的自动抓取。核心流程是：启动无头浏览器 → 打开目标页面 → 循环抓取每页数据 → 点击下一页 → 直到没有更多页面。run_browser_command 函数封装了 CLI 调用，scrape_paginated_data 是主逻辑。通过 evaluate 执行自定义 JavaScript 提取页面数据，返回 JSON 格式便于处理。分页处理需要先获取快照找到"下一页"按钮的 ref，然后点击跳转。这种方式适合抓取电商商品、新闻列表、论坛帖子等分页内容。

6. Chrome 扩展集成：Browser Relay

6.1 什么是 Browser Relay？

Browser Relay 是 OpenClaw 的独特功能，它允许 AI 智能体控制你现有的 Chrome 标签页，而不是启动一个独立的浏览器实例。

图：Browser Relay 通过 Chrome 扩展实现 AI 对现有标签页的控制

#mermaid-svg-PcbSrJ9rbXfEUV1A{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-PcbSrJ9rbXfEUV1A .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-PcbSrJ9rbXfEUV1A .error-icon{fill:#552222;}#mermaid-svg-PcbSrJ9rbXfEUV1A .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-PcbSrJ9rbXfEUV1A .marker{fill:#333333;stroke:#333333;}#mermaid-svg-PcbSrJ9rbXfEUV1A .marker.cross{stroke:#333333;}#mermaid-svg-PcbSrJ9rbXfEUV1A svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-PcbSrJ9rbXfEUV1A p{margin:0;}#mermaid-svg-PcbSrJ9rbXfEUV1A .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-PcbSrJ9rbXfEUV1A .cluster-label text{fill:#333;}#mermaid-svg-PcbSrJ9rbXfEUV1A .cluster-label span{color:#333;}#mermaid-svg-PcbSrJ9rbXfEUV1A .cluster-label span p{background-color:transparent;}#mermaid-svg-PcbSrJ9rbXfEUV1A .label text,#mermaid-svg-PcbSrJ9rbXfEUV1A span{fill:#333;color:#333;}#mermaid-svg-PcbSrJ9rbXfEUV1A .node rect,#mermaid-svg-PcbSrJ9rbXfEUV1A .node circle,#mermaid-svg-PcbSrJ9rbXfEUV1A .node ellipse,#mermaid-svg-PcbSrJ9rbXfEUV1A .node polygon,#mermaid-svg-PcbSrJ9rbXfEUV1A .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-PcbSrJ9rbXfEUV1A .rough-node .label text,#mermaid-svg-PcbSrJ9rbXfEUV1A .node .label text,#mermaid-svg-PcbSrJ9rbXfEUV1A .image-shape .label,#mermaid-svg-PcbSrJ9rbXfEUV1A .icon-shape .label{text-anchor:middle;}#mermaid-svg-PcbSrJ9rbXfEUV1A .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-PcbSrJ9rbXfEUV1A .rough-node .label,#mermaid-svg-PcbSrJ9rbXfEUV1A .node .label,#mermaid-svg-PcbSrJ9rbXfEUV1A .image-shape .label,#mermaid-svg-PcbSrJ9rbXfEUV1A .icon-shape .label{text-align:center;}#mermaid-svg-PcbSrJ9rbXfEUV1A .node.clickable{cursor:pointer;}#mermaid-svg-PcbSrJ9rbXfEUV1A .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-PcbSrJ9rbXfEUV1A .arrowheadPath{fill:#333333;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-PcbSrJ9rbXfEUV1A .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-PcbSrJ9rbXfEUV1A .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-PcbSrJ9rbXfEUV1A .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-PcbSrJ9rbXfEUV1A .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-PcbSrJ9rbXfEUV1A .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-PcbSrJ9rbXfEUV1A .cluster text{fill:#333;}#mermaid-svg-PcbSrJ9rbXfEUV1A .cluster span{color:#333;}#mermaid-svg-PcbSrJ9rbXfEUV1A div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-PcbSrJ9rbXfEUV1A .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-PcbSrJ9rbXfEUV1A rect.text{fill:none;stroke-width:0;}#mermaid-svg-PcbSrJ9rbXfEUV1A .icon-shape,#mermaid-svg-PcbSrJ9rbXfEUV1A .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-PcbSrJ9rbXfEUV1A .icon-shape p,#mermaid-svg-PcbSrJ9rbXfEUV1A .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-PcbSrJ9rbXfEUV1A .icon-shape .label rect,#mermaid-svg-PcbSrJ9rbXfEUV1A .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-PcbSrJ9rbXfEUV1A .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-PcbSrJ9rbXfEUV1A .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-PcbSrJ9rbXfEUV1A :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户 Chrome

OpenClaw 系统

CDP

AI 智能体

browser 工具

Gateway 网关

本地中继服务器

Chrome 扩展

目标标签页

核心优势

✅ 无缝集成：直接操作你正在使用的浏览器，无需切换窗口

✅ 会话保持：保留已登录状态，无需重复登录

✅ 实时协作：AI 和人类可以同时操作同一页面

✅ 隐私隔离：仅控制你明确附加的标签页

6.2 安装与配置

步骤一：安装扩展

# 安装扩展到 OpenClaw 状态目录
openclaw browser extension install

# 查看扩展路径
openclaw browser extension path

步骤二：加载到 Chrome

步骤三：使用扩展

6.3 配置文件说明

Browser Relay 使用内置的 chrome 配置文件：

{
browser: {
defaultProfile: "chrome", // 默认使用扩展中继
profiles: {
chrome: {
driver: "extension",
cdpUrl: "http://127.0.0.1:18792", // 中继端口
color: "#4285F4"
}
}
}
}

创建自定义配置文件

openclaw browser create-profile \\
–name my-chrome \\
–driver extension \\
–cdp-url http://127.0.0.1:18792 \\
–color "#00AA00"

6.4 安全注意事项

⚠️ Browser Relay 功能强大，但也带来安全风险：

风险提示

最佳实践

7. 常见问题与排查

7.1 浏览器启动失败

问题现象

Error: Browser disabled

解决方案

检查配置文件中的 browser.enabled 是否为 true：

{
browser: {
enabled: true
}
}

重启 Gateway 网关：

openclaw gateway restart

7.2 Snapshot 返回空结果

问题现象

snapshot 命令返回空列表或很少元素。

可能原因

解决方案

# 等待页面加载完成
openclaw browser wait –load networkidle

# 检查 iframe
openclaw browser snapshot –frame "iframe#content"

# 显示所有元素（包括隐藏的）
openclaw browser snapshot –format aria

7.3 操作定位失败

问题现象

Error: Element not found: ref=e12

原因分析

Ref 在页面导航后会失效，需要重新获取 snapshot。

解决方案

# 1. 重新获取快照
openclaw browser snapshot –interactive

# 2. 使用新的 ref 执行操作
openclaw browser click e5

# 3. 如果仍失败，使用高亮调试
openclaw browser highlight e5

7.4 Chrome 扩展无法连接

问题现象

扩展徽章显示 !，无法附加标签页。

排查步骤

# 1. 检查 Gateway 是否运行
openclaw gateway status

# 2. 检查中继端口
curl http://127.0.0.1:18792/health

# 3. 查看扩展选项页
# 点击扩展图标 → 右键 → 选项

常见原因

7.5 Playwright 不可用

问题现象

Playwright is not available in this gateway build

解决方案

安装完整的 Playwright 包：

# 本地安装
npm install playwright
npx playwright install chromium

# Docker 环境
docker compose run –rm openclaw-cli \\
node /app/node_modules/playwright-core/cli.js install chromium

8. 总结

本文从浏览器自动化的基础原理出发，全面介绍了 OpenClaw 框架中的浏览器控制能力。核心要点总结如下：

1. 架构设计 🏗️

OpenClaw 通过 HTTP API + Playwright + CDP 的三层架构，将复杂的浏览器控制封装为智能体友好的接口。Gateway 网关作为中间层，提供认证、路由、配置管理等功能，使浏览器自动化成为 AI 智能体的"原生能力"。

2. Snapshot 机制 📸

Snapshot 是 OpenClaw 浏览器自动化的核心创新。它将 HTML 页面转换为结构化的 UI 树，让 AI 模型能够"阅读"页面内容。数字 ref 和角色 ref 两种定位方式，告别了脆弱的 CSS 选择器，大大提高了自动化脚本的稳定性。

3. 多配置文件管理 🗂️

OpenClaw 支持多个独立的浏览器配置文件，每个配置文件有独立的用户数据目录和 CDP 端口。这种设计既保护了用户隐私，又支持同时运行多个自动化任务。

4. Browser Relay 🔌

Chrome 扩展集成是 OpenClaw 的独特优势。通过 Browser Relay，AI 可以控制用户现有的 Chrome 标签页，保留已登录状态，实现人机协作的无缝衔接。同时，扩展的附加/分离机制确保了用户对 AI 权限的精确控制。

5. 实战应用 🎯

网页监控、表单填写、数据抓取三个案例展示了 OpenClaw 在实际场景中的应用价值。配置化的设计理念使自动化脚本易于维护和复用。

思考题 💭

参考资料

• OpenClaw 官方文档 – 浏览器工具
• OpenClaw 官方文档 – Chrome 扩展
• Playwright 官方文档
• Chrome DevTools Protocol
• OpenClaw GitHub 仓库