浏览器自动化

OpenClaw 通过 Chrome DevTools Protocol (CDP) 实现强大的浏览器自动化能力。本章介绍 CDP 三种控制模式及实战应用。

什么是 CDP？

Chrome DevTools Protocol (CDP) 是 Chrome 浏览器原生的远程控制协议，相当于给浏览器开了一个"后门"，可以直接用指令操控浏览器的所有底层功能。

CDP 的优势

对比项	CDP	Selenium	Puppeteer	Playwright
底层程度	最底层	较高层	中层	中层
灵活性	最高	中等	较高	较高
轻量级	最轻	较重	中等	较重
学习曲线	较陡	平缓	中等	中等

CDP 能做什么

打开网页、导航、刷新
点击按钮、填写表单
截图、录屏
抓取页面数据
多标签页管理
网络请求拦截
性能监控

三种控制模式

OpenClaw 基于 CDP 提供三种控制模式，适应不同场景需求。

模式一：Headless Chrome（无头浏览器）

最简单的模式，OpenClaw 自动启动一个无界面的 Chrome 实例。

特点

配置简单，开箱即用
资源占用少
适合服务器环境
每次启动都是全新状态

启动方式

# 启动无头浏览器
openclaw browser start --headless

配置

{
  "browser": {
    "enabled": true,
    "driver": "chrome-devtools",
    "headless": true,
    "args": [
      "--no-sandbox",
      "--disable-gpu",
      "--disable-dev-shm-usage"
    ]
  }
}

适用场景

服务器环境
定时爬虫任务
自动化测试
不需要登录状态的任务

模式二：接管本地浏览器

连接到用户正在使用的 Chrome 浏览器，可以复用登录状态。

特点

复用已有登录状态
可以看到操作过程
适合需要登录的网站
需要手动启动浏览器

启动步骤

Step 1：以调试模式启动 Chrome

Windows：

# 在 PowerShell 中执行
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\chrome-debug-profile"

macOS：

/Applications/Google\ Chrome.app/Contents/MacOS/Google Chrome --remote-debugging-port=9222 --user-data-dir="$HOME/chrome-debug-profile"

Linux：

google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/chrome-debug-profile"

Step 2：配置 OpenClaw 连接

{
  "browser": {
    "enabled": true,
    "driver": "chrome-devtools",
    "cdpUrl": "http://127.0.0.1:9222"
  }
}

Step 3：验证连接

openclaw browser status

适用场景

需要保持登录状态
操作需要人工确认
调试和开发
复杂的网页交互

模式三：Chrome 扩展（Extension Relay）

通过 Chrome 扩展程序连接浏览器，最灵活的方式。

特点

无需命令行启动浏览器
支持远程浏览器
跨平台兼容性好
支持云端部署

安装步骤

Step 1：安装 Chrome 扩展

访问 Chrome Web Store
搜索 "OpenClaw Extension" 或 "Claw Extension"
点击"添加到 Chrome"

Step 2：启动本地中继服务

openclaw extension-relay start

默认监听端口 18792。

Step 3：配置扩展

在扩展设置中填入中继服务地址：

ws://127.0.0.1:18792

Step 4：配置 OpenClaw

{
  "browser": {
    "enabled": true,
    "driver": "chrome-extension",
    "relayPort": 18792
  }
}

架构图

┌─────────────────┐     WebSocket      ┌─────────────────┐
│  Chrome 扩展     │◄──────────────────►│  Extension Relay │
│  (浏览器内)      │                    │  (本地服务)       │
└─────────────────┘                    └────────┬────────┘
                                                │
                                                │ 本地连接
                                                ▼
                                       ┌─────────────────┐
                                       │    OpenClaw     │
                                       │    Agent        │
                                       └─────────────────┘

适用场景

云端部署
远程浏览器控制
企业内网环境
需要穿透防火墙

常用浏览器操作

基础操作

截图

# 截取当前页面
openclaw browser screenshot --output screenshot.png

# 截取特定元素
openclaw browser screenshot --selector "#content" --output content.png

# 全页面截图
openclaw browser screenshot --full-page --output fullpage.png

生成 PDF

openclaw browser pdf --output page.pdf

页面交互

扫描页面元素

# 获取页面快照
openclaw browser snapshot

返回页面结构，包含可交互元素的列表。

点击元素

# 通过选择器点击
openclaw browser click --selector "#submit-button"

# 通过文本点击
openclaw browser click --text "登录"

输入文本

# 在输入框输入文本
openclaw browser type --selector "#username" --text "myuser"

# 输入并回车
openclaw browser type --selector "#search" --text "OpenClaw" --enter

表单操作

# 选择下拉框选项
openclaw browser select --selector "#country" --value "China"

# 勾选复选框
openclaw browser check --selector "#agree"

# 取消勾选
openclaw browser uncheck --selector "#newsletter"

多标签页管理

# 列出所有标签页
openclaw browser tabs

# 新建标签页
openclaw browser tab new --url https://example.com

# 切换标签页
openclaw browser tab select --index 1

# 关闭当前标签页
openclaw browser tab close

# 关闭指定标签页
openclaw browser tab close --index 2

高级操作

执行 JavaScript

openclaw browser evaluate --script "document.title"

等待元素

# 等待元素出现
openclaw browser wait --selector "#result" --timeout 10000

# 等待元素消失
openclaw browser wait --selector ".loading" --hidden --timeout 10000

网络请求

# 拦截请求
openclaw browser intercept --pattern "*.js" --block

# 等待网络空闲
openclaw browser wait-network-idle

状态持久化

为什么需要状态持久化？

如果每次连接的都是一个纯净无痕的浏览器，AI 会反复卡在扫码和登录验证码上。状态持久化可以让浏览器记住登录状态。

配置用户数据目录

# 启动时指定用户数据目录
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/openclaw-chrome-data" \
  --headless=new

首次登录流程

第一次运行时，去掉 --headless 参数
手动在弹出的浏览器中登录需要的平台
登录完成后，切回无头模式后台运行

# 首次登录（有界面）
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/openclaw-chrome-data"

# 登录完成后，使用无头模式
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/openclaw-chrome-data" \
  --headless=new

Docker 环境配置

在 Docker 中使用浏览器自动化需要特殊配置。

问题：网络隔离

Docker 容器内的 OpenClaw 无法直接访问宿主机的浏览器。

解决方案：Cloudflare Tunnel

使用 Cloudflared Tunnel 将宿主机的调试端口暴露出来。

Step 1：启动带状态的浏览器

google-chrome \
  --remote-debugging-port=9222 \
  --remote-debugging-address=0.0.0.0 \
  --headless=new \
  --disable-gpu \
  --no-sandbox \
  --user-data-dir="$HOME/openclaw-chrome-data"

Step 2：启动 Cloudflared Tunnel

cloudflared tunnel --url http://127.0.0.1:9222

终端会输出类似 https://your-random-words.trycloudflare.com 的地址。

Step 3：获取完整的 WebSocket URL

# 获取浏览器实例 ID
curl http://127.0.0.1:9222/json/version

返回结果中包含 /devtools/browser/xxxx-xxxx... 路径。

Step 4：配置 OpenClaw

{
  "browser": {
    "enabled": true,
    "driver": "chrome-devtools-mcp",
    "mcp": {
      "cdpUrl": "wss://your-random-words.trycloudflare.com/devtools/browser/1234abcd-..."
    }
  }
}

安全警告

CDP 本身没有任何密码校验机制，通过 Tunnel 将端口暴露在公网存在安全风险。

最佳实践：

自动化任务执行完毕后，立即关闭 Tunnel
不要让 Tunnel 一直后台运行

一键启动脚本

#!/bin/bash
# openclaw-chrome-start.sh

CHROME_DATA_DIR="$HOME/openclaw-chrome-data"

cleanup() {
  echo "正在清理..."
  pkill -f "cloudflared tunnel" 2>/dev/null
  echo "已安全关闭 Tunnel"
  exit 0
}

trap cleanup SIGINT

# 启动 Chrome
if ! pgrep -f "chrome.*remote-debugging" > /dev/null; then
  google-chrome \
    --remote-debugging-port=9222 \
    --remote-debugging-address=0.0.0.0 \
    --user-data-dir="$CHROME_DATA_DIR" \
    --headless=new \
    --no-sandbox \
    --disable-gpu &
  sleep 2
fi

# 启动 Tunnel
cloudflared tunnel --url http://127.0.0.1:9222 > /tmp/tunnel-output.txt 2>&1 &

# 获取 Tunnel URL
sleep 5
TUNNEL_URL=$(grep -o 'https://[-a-zA-Z0-9]*\.trycloudflare\.com' /tmp/tunnel-output.txt | head -n 1)
WS_PATH=$(curl -s http://127.0.0.1:9222/json/version | grep -o "/devtools/browser/[a-f0-9-]*")

WSS_BASE="${TUNNEL_URL/https/wss}"
FINAL_URL="${WSS_BASE}${WS_PATH}"

echo "=========================================="
echo "WebSocket URL:"
echo "$FINAL_URL"
echo "=========================================="
echo "按 Ctrl+C 关闭 Tunnel"

wait

实战案例

案例 1：自动登录网站

帮我登录 GitHub，账号是 myuser，密码是 mypass

OpenClaw 会自动：

打开 GitHub 登录页面
填写用户名和密码
点击登录按钮
处理可能的两步验证

案例 2：定时抓取数据

配置 Cron 任务：

{
  "cron": {
    "tasks": [
      {
        "name": "price-monitor",
        "schedule": "0 */6 * * *",
        "prompt": "打开 https://example.com/product/123，抓取商品价格，如果价格低于 500 元就通知我"
      }
    ]
  }
}

案例 3：自动填写表单

帮我填写这个表单：
- 姓名：张三
- 邮箱：[email protected]
- 电话：13800138000

案例 4：批量操作

帮我在以下网站注册账号：
1. site1.com
2. site2.com
3. site3.com

使用统一的信息：
- 用户名：myuser
- 邮箱：[email protected]
- 密码：MyP@ssw0rd

案例 5：网页监控

配置 Heartbeat 任务：

# Heartbeat 任务

## 每 30 分钟检查

- 打开 https://example.com/status
- 检查服务状态是否正常
- 如果显示异常，发送告警到 Telegram

常见问题

浏览器无法启动

检查：

# 检查 Chrome 是否安装
which google-chrome

# 检查端口是否被占用
lsof -i :9222

连接超时

原因：CDP 端口未正确暴露或防火墙阻止。

解决：

# 检查 Chrome 是否在监听
curl http://127.0.0.1:9222/json/version

# 检查防火墙规则
# Linux
sudo ufw status

# Windows
netsh advfirewall firewall show rule name=all | findstr 9222

登录状态丢失

原因：未配置用户数据目录。

解决：

# 使用 --user-data-dir 参数
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/chrome-data"

页面加载超时

解决：

# 增加超时时间
openclaw config set browser.timeout 60000

# 或在操作中指定
openclaw browser navigate https://example.com --timeout 60000

元素定位失败

解决：

使用 snapshot 命令获取页面结构
尝试不同的选择器
等待元素加载完成

# 等待元素出现
openclaw browser wait --selector "#content" --timeout 10000

最佳实践

1. 使用状态持久化

始终配置用户数据目录，避免重复登录。

2. 合理设置超时

根据网络状况和页面复杂度设置合理的超时时间。

3. 错误处理

在自动化脚本中添加错误处理：

# 任务描述

打开网站
如果 10 秒内未加载完成，发送告警
如果出现验证码，通知人工处理

4. 安全意识

不要在无痕模式下保存敏感信息
定期清理用户数据目录
使用 Tunnel 时注意及时关闭

5. 资源管理

# 定期清理浏览器缓存
openclaw browser clear-cache

# 关闭不用的标签页
openclaw browser tab close --except-current

下一步

多 Agent 协作 - 让 Agent 协作完成复杂任务
最佳实践 - 生产环境配置建议
速查表 - 常用命令速查

什么是 CDP？​

CDP 的优势​

CDP 能做什么​

三种控制模式​

模式一：Headless Chrome（无头浏览器）​

特点​

启动方式​

配置​

适用场景​

模式二：接管本地浏览器​

特点​

启动步骤​

适用场景​

模式三：Chrome 扩展（Extension Relay）​

特点​

安装步骤​

架构图​

适用场景​

常用浏览器操作​

基础操作​

导航​

截图​

生成 PDF​

页面交互​

扫描页面元素​

点击元素​

输入文本​

表单操作​

多标签页管理​

高级操作​

执行 JavaScript​

等待元素​

网络请求​

状态持久化​

为什么需要状态持久化？​

配置用户数据目录​

首次登录流程​

Docker 环境配置​

问题：网络隔离​

解决方案：Cloudflare Tunnel​

Step 1：启动带状态的浏览器​

Step 2：启动 Cloudflared Tunnel​

Step 3：获取完整的 WebSocket URL​

Step 4：配置 OpenClaw​

安全警告​

一键启动脚本​

实战案例​

案例 1：自动登录网站​

案例 2：定时抓取数据​

案例 3：自动填写表单​

案例 4：批量操作​

案例 5：网页监控​

常见问题​

浏览器无法启动​

连接超时​

登录状态丢失​

页面加载超时​

元素定位失败​

最佳实践​

1. 使用状态持久化​

2. 合理设置超时​

3. 错误处理​

4. 安全意识​

5. 资源管理​

下一步​

什么是 CDP？

CDP 的优势

CDP 能做什么

三种控制模式

模式一：Headless Chrome（无头浏览器）

特点

启动方式

配置

适用场景

模式二：接管本地浏览器

特点

启动步骤

适用场景

模式三：Chrome 扩展（Extension Relay）

特点

安装步骤

架构图

适用场景

常用浏览器操作

基础操作

导航

截图

生成 PDF

页面交互

扫描页面元素

点击元素

输入文本

表单操作

多标签页管理

高级操作

执行 JavaScript

等待元素

网络请求

状态持久化

为什么需要状态持久化？

配置用户数据目录

首次登录流程

Docker 环境配置

问题：网络隔离

解决方案：Cloudflare Tunnel

Step 1：启动带状态的浏览器

Step 2：启动 Cloudflared Tunnel

Step 3：获取完整的 WebSocket URL

Step 4：配置 OpenClaw

安全警告

一键启动脚本

实战案例

案例 1：自动登录网站

案例 2：定时抓取数据

案例 3：自动填写表单

案例 4：批量操作

案例 5：网页监控

常见问题

浏览器无法启动

连接超时

登录状态丢失

页面加载超时

元素定位失败

最佳实践

1. 使用状态持久化

2. 合理设置超时

3. 错误处理

4. 安全意识

5. 资源管理

下一步