浏览器自动化

OpenClaw 提供强大的浏览器自动化能力，Agent 可以打开网页、点击按钮、填写表单、截图等。本章介绍浏览器配置和常用操作。

概述

OpenClaw 可以管理一个专用的 Chrome/Brave/Edge/Chromium 浏览器配置，这个浏览器与你的个人浏览器完全隔离，专门用于 Agent 自动化操作。

核心特点

隔离环境：不触碰你的个人浏览器配置
自动管理：OpenClaw 自动启动和管理浏览器
功能完整：支持标签页控制、截图、PDF、表单操作等
多配置文件：支持多个独立的浏览器配置

浏览器选择

OpenClaw 自动检测系统中的 Chromium 浏览器，按以下顺序选择：

Chrome
Brave
Edge
Chromium
Chrome Canary

也可以通过配置指定浏览器路径。

浏览器配置文件（Profile）

OpenClaw 支持多种浏览器配置文件模式：

openclaw 配置文件（默认）

这是 OpenClaw 管理的独立浏览器，与你的个人浏览器完全隔离。每次启动都是干净的状态，适合：

自动化测试
数据抓取
不需要登录状态的任务

user 配置文件（Existing Session）

连接到你正在使用的 Chrome 浏览器，通过 Chrome DevTools MCP 自动连接到你的真实登录会话。适合：

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

这是内置的 user 配置文件，使用 Chrome DevTools MCP 的 --autoConnect 流程。当用户在电脑前可以批准连接提示时，这是最方便的选择。

启用 user 配置文件：

{
  "browser": {
    "defaultProfile": "user"
  }
}

或在命令中指定：

openclaw browser snapshot --browser-profile user

使用 user 配置文件的前提：

目标 Chromium 浏览器版本 144+
已在浏览器中启用远程调试
浏览器显示并用户接受了连接同意提示

启用 Chrome 远程调试：

Chrome: chrome://inspect/#remote-debugging
Brave: brave://inspect/#remote-debugging
Edge: edge://inspect/#remote-debugging

自定义 Existing Session 配置

可以为 Brave、Edge 或其他 Chromium 浏览器创建自定义的 existing-session 配置：

{
  "browser": {
    "profiles": {
      "brave-personal": {
        "driver": "existing-session",
        "userDataDir": "~/.config/BraveSoftware/Brave-Browser"
      }
    }
  }
}

远程 CDP

连接到远程运行的 Chromium 浏览器，适合：

云端部署
Docker 环境
远程浏览器服务（如 Browserless、Browserbase）

CLI 命令

基础操作

# 查看浏览器状态
openclaw browser status

# 启动浏览器
openclaw browser start

# 停止浏览器
openclaw browser stop

# 查看标签页
openclaw browser tabs

# 打开新标签页
openclaw browser open https://example.com

截图和快照

# 截取当前页面
openclaw browser screenshot

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

# 截取特定元素（使用快照返回的引用）
openclaw browser screenshot --ref 12
openclaw browser screenshot --ref e12

# 获取页面快照（AI 格式，带数字引用）
openclaw browser snapshot

# ARIA 格式快照（无引用，仅查看）
openclaw browser snapshot --format aria

# 获取交互式元素列表（角色快照，e 前缀引用）
openclaw browser snapshot --interactive

# 高效快照模式（紧凑输出）
openclaw browser snapshot --efficient

# 带标签覆盖的快照
openclaw browser snapshot --labels

# 限定选择器范围
openclaw browser snapshot --selector "#main" --interactive

# iframe 内的快照
openclaw browser snapshot --frame "iframe#main" --interactive

# 限制输出行数
openclaw browser snapshot --format aria --limit 200

页面交互

# 导航到 URL
openclaw browser navigate https://example.com

# 点击元素（使用 snapshot 返回的引用）
openclaw browser click 12
openclaw browser click e12

# 输入文本
openclaw browser type 23 "hello"

# 输入并提交
openclaw browser type 23 "hello" --submit

# 按键
openclaw browser press Enter

# 悬停
openclaw browser hover 44

# 滚动到元素
openclaw browser scrollintoview e12

# 拖拽
openclaw browser drag 10 11

# 下拉选择
openclaw browser select 9 OptionA OptionB

等待操作

# 等待文本出现
openclaw browser wait --text "Done"

# 等待 URL 匹配
openclaw browser wait --url "**/dashboard"

# 等待网络空闲
openclaw browser wait --load networkidle

# 等待 JS 条件
openclaw browser wait --fn "window.ready===true"

# 等待选择器出现
openclaw browser wait "#main"

标签页管理

# 列出标签页
openclaw browser tabs

# 切换标签页
openclaw browser focus <targetId>

# 关闭标签页
openclaw browser close <targetId>

调试工具

# 执行 JavaScript
openclaw browser evaluate --fn '(el) => el.textContent' --ref 7

# 高亮元素
openclaw browser highlight e12

# 查看控制台日志
openclaw browser console --level error

# 查看页面错误
openclaw browser errors --clear

# 查看网络请求
openclaw browser requests --filter api --clear

# 开始追踪
openclaw browser trace start

# 停止追踪
openclaw browser trace stop

状态管理

# 查看 Cookie
openclaw browser cookies

# 设置 Cookie
openclaw browser cookies set session abc123 --url "https://example.com"

# 清除 Cookie
openclaw browser cookies clear

# 本地存储
openclaw browser storage local get
openclaw browser storage local set theme dark
openclaw browser storage session clear

# 设置离线模式
openclaw browser set offline on

# 设置时区
openclaw browser set timezone America/New_York

# 设置设备模拟
openclaw browser set device "iPhone 14"

PDF 导出

# 导出当前页面为 PDF
openclaw browser pdf

配置参考

基本配置

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw"
  }
}

多配置文件

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "profiles": {
      "openclaw": {
        "color": "#FF5A2D"
      },
      "work": {
        "color": "#2196F3",
        "userDataDir": "~/.openclaw/browser-work"
      },
      "remote": {
        "cdpUrl": "wss://browser.example.com"
      }
    }
  }
}

使用 user 配置文件

user 配置文件通过 Chrome DevTools MCP 连接到你正在使用的 Chrome：

{
  "browser": {
    "profiles": {
      "user": {
        "driver": "existing-session"
      }
    }
  }
}

使用 user 配置文件时，需要在 Chrome 中启用远程调试：

打开 chrome://inspect/#remote-debugging
启用远程调试
保持浏览器运行

重要限制：

OpenClaw 不会为此 driver 启动浏览器，只连接到现有会话
需要用户在电脑前批准连接提示
截图支持页面捕获和元素捕获，但不支持 CSS --element 选择器
wait --load networkidle 暂不支持
PDF 导出和下载拦截等功能仍需要托管浏览器路径
现有会话是主机本地的，如果 Chrome 在不同的机器或网络命名空间，需要使用远程 CDP 或 node host

远程 CDP 配置

连接到远程浏览器服务：

{
  "browser": {
    "profiles": {
      "browserless": {
        "cdpUrl": "wss://chrome.browserless.io?token=<API_KEY>"
      },
      "browserbase": {
        "cdpUrl": "wss://connect.browserbase.com?token=<API_KEY>"
      }
    }
  }
}

支持的远程 CDP 格式：

HTTP(S) 端点：OpenClaw 调用 /json/version 发现 WebSocket 调试 URL
WebSocket 端点（ws:///wss://）：直接连接，跳过发现步骤

Browserless 配置

Browserless 是托管 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 CDP 连接：

{
  "browser": {
    "profiles": {
      "browserless": {
        "cdpUrl": "wss://chrome.browserless.io?token=<BROWSERLESS_API_KEY>"
      }
    }
  }
}

Browserbase 配置

Browserbase 提供云端无头浏览器，内置 CAPTCHA 解决、隐身模式和住宅代理：

{
  "browser": {
    "profiles": {
      "browserbase": {
        "cdpUrl": "wss://connect.browserbase.com?token=<BROWSERBASE_API_KEY>"
      }
    }
  }
}

注意：Browserbase 免费层允许一个并发会话和每月一小时的浏览器使用时间。

快照引用（Refs）

页面快照返回元素引用，用于后续操作。OpenClaw 支持两种快照风格：

AI 快照（数字引用）

默认格式，返回带数字引用的文本快照：

openclaw browser snapshot
# 返回类似 aria-ref="12" 的引用
openclaw browser click 12

内部通过 Playwright 的 aria-ref 解析。

角色快照（e 前缀引用）

通过 --interactive 或其他角色选项启用，返回角色基础列表/树：

openclaw browser snapshot --interactive
# 返回类似 [ref=e12] 的引用
openclaw browser click e12

内部通过 getByRole(...) 解析（重复元素额外使用 nth()）。

重要说明

引用不稳定：页面导航后引用会失效，需要重新获取快照
如果角色快照使用了 --frame，角色引用会限定在该 iframe 内直到下一次角色快照
CSS 选择器不支持用于操作，只能使用快照返回的引用

调试工作流

当操作失败时（如"元素不可见"、"被覆盖"等）：

# 1. 获取交互式快照
openclaw browser snapshot --interactive

# 2. 使用返回的引用操作
openclaw browser click e12

# 3. 如果仍然失败，高亮元素查看
openclaw browser highlight e12

# 4. 检查页面错误和请求
openclaw browser errors --clear
openclaw browser requests --filter api --clear

# 5. 深度调试：录制追踪
openclaw browser trace start
# ... 执行操作 ...
openclaw browser trace stop
# 输出: TRACE:<path>

等待增强

除了时间和文本，还可以等待更多条件：

# 等待 URL 匹配（支持 glob 模式）
openclaw browser wait --url "**/dashboard"

# 等待页面加载状态
openclaw browser wait --load networkidle

# 等待 JavaScript 条件
openclaw browser wait --fn "window.ready===true"

# 等待选择器出现
openclaw browser wait "#main"

状态和环境设置

这些命令用于"让网站表现得像某个环境"：

# Cookie 操作
openclaw browser cookies
openclaw browser cookies set session abc123 --url "https://example.com"
openclaw browser cookies clear

# 本地存储
openclaw browser storage local get
openclaw browser storage local set theme dark
openclaw browser storage session clear

# 离线模式
openclaw browser set offline on

# 自定义请求头
openclaw browser set headers --headers-json '{"X-Debug":"1"}'

# HTTP 基本认证
openclaw browser set credentials user pass
openclaw browser set credentials --clear

# 地理位置
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set geo --clear

# 媒体偏好
openclaw browser set media dark

# 时区和语言
openclaw browser set timezone America/New_York
openclaw browser set locale en-US

# 设备模拟（Playwright 设备预设）
openclaw browser set device "iPhone 14"

# 视口大小
openclaw browser set viewport 1280 720

安全注意事项

浏览器控制服务仅监听本地回环地址
远程 CDP URL 应视为敏感信息
使用 browser evaluate 和 wait --fn 会执行页面中的 JavaScript
可通过 browser.evaluateEnabled: false 禁用 JavaScript 执行

Playwright 依赖

部分高级功能（导航、截图、PDF、元素截图）需要 Playwright。如果未安装，相关端点会返回 501 错误。

Docker 环境安装 Playwright：

# 使用 OpenClaw 内置命令
openclaw browser install-playwright

常见问题

浏览器无法启动

# 检查浏览器状态
openclaw browser status

# 运行诊断
openclaw doctor

连接超时

# 检查端口
curl http://127.0.0.1:18791

# 检查配置
openclaw config get browser

元素操作失败

重新获取快照
使用 --interactive 模式
检查元素是否在视口内
增加等待时间

缺少 Playwright

# 安装 Playwright
openclaw browser install-playwright

# 或手动安装
npm install playwright
npx playwright install chromium

下一步

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

概述​

核心特点​

浏览器选择​

浏览器配置文件（Profile）​

openclaw 配置文件（默认）​

user 配置文件（Existing Session）​

自定义 Existing Session 配置​

远程 CDP​

CLI 命令​

基础操作​

截图和快照​

页面交互​

等待操作​

标签页管理​

调试工具​

状态管理​

PDF 导出​

配置参考​

基本配置​

多配置文件​

使用 user 配置文件​

远程 CDP 配置​

Browserless 配置​

Browserbase 配置​

快照引用（Refs）​

AI 快照（数字引用）​

角色快照（e 前缀引用）​

重要说明​

调试工作流​

等待增强​

状态和环境设置​

安全注意事项​

Playwright 依赖​

常见问题​

浏览器无法启动​

连接超时​

元素操作失败​

缺少 Playwright​

下一步​

概述