浏览器自动化

Openclaw 可以运行一个独立的 Chrome/Brave/Edge 浏览器配置文件，由 AI 助手控制。这个浏览器与您的日常浏览器完全隔离。

简单理解：

  • 这是一个专门给 AI 用的浏览器，不会影响您的个人浏览器
  • AI 可以打开网页、点击、输入、截图
  • 默认配置文件名为 clawd（橙色标识）

功能特点

  • 独立的浏览器配置文件（不影响您的日常浏览）
  • 标签页管理（打开/关闭/切换）
  • 自动化操作（点击/输入/拖拽/选择）
  • 页面快照、截图、PDF 导出
  • 支持多配置文件（clawd、work、remote 等）

快速开始

bash
# 查看浏览器状态
openclaw browser status

# 启动浏览器
openclaw browser start

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

# 获取页面快照
openclaw browser snapshot

如果提示 "Browser disabled"，请在配置中启用浏览器并重启网关。

配置文件类型

配置文件说明
clawd独立管理的浏览器（无需扩展）
chrome通过扩展连接您的系统浏览器（需安装扩展）

如果您希望默认使用独立浏览器，设置 browser.defaultProfile: "clawd"。

配置说明

配置文件位于 ~/.openclaw/openclaw.json。

基础配置示例：

json5
{
  browser: {
    enabled: true,           // 启用浏览器控制
    defaultProfile: "clawd", // 默认使用独立浏览器
    headless: false,         // 显示浏览器窗口（调试时建议开启）
    color: "#FF4500"         // 浏览器 UI 颜色标识
  }
}

完整配置示例（高级用户）：

json5
{
  browser: {
    enabled: true,
    controlUrl: "http://127.0.0.1:18791",
    cdpUrl: "http://127.0.0.1:18792",
    defaultProfile: "clawd",
    color: "#FF4500",
    headless: false,
    noSandbox: false,       // Linux 可能需要设为 true
    attachOnly: false,      // 仅附加到已运行的浏览器
    executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
    profiles: {
      clawd: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" }
    }
  }
}

配置字段说明

字段说明默认值
enabled启用浏览器控制true
defaultProfile默认配置文件chrome
headless无头模式（不显示窗口）false
noSandbox禁用沙箱（Linux 可能需要）false
executablePath浏览器可执行文件路径自动检测
colorUI 颜色标识#FF4500

指定浏览器

如果您的系统默认浏览器是 Chrome/Brave/Edge，Openclaw 会自动检测。您也可以手动指定：

通过命令行设置：

bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"

各平台配置示例：

json5
// macOS - Chrome
{ browser: { executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" } }

// macOS - Brave
{ browser: { executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" } }

// Windows
{ browser: { executablePath: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" } }

// Linux
{ browser: { executablePath: "/usr/bin/google-chrome" } }

自动检测顺序： Chrome → Brave → Edge → Chromium → Chrome Canary

多配置文件支持

Openclaw 支持多个命名的浏览器配置文件：

类型说明
独立管理专用浏览器实例，有独立的用户数据目录
远程 CDP连接到其他机器上的浏览器
扩展中继通过 Chrome 扩展控制现有标签页

默认配置文件：

  • clawd - 独立管理的浏览器（自动创建）
  • chrome - Chrome 扩展中继（内置）

使用指定配置文件：

bash
openclaw browser --browser-profile work start
openclaw browser --browser-profile work open https://example.com

Chrome 扩展中继（控制现有标签页）

Openclaw 还可以通过 Chrome 扩展控制您现有的 Chrome 标签页（而不是启动独立浏览器）。

详细指南：Chrome 扩展

快速设置：

  1. 安装扩展：
bash
openclaw browser extension install

  1. 加载到 Chrome：

    • 打开 chrome://extensions
    • 启用“开发者模式”
    • 点击“加载已解压的扩展程序”
    • 选择 openclaw browser extension path 输出的目录

  2. 使用：

    • 固定扩展图标，点击即可附加到当前标签页（图标显示 ON）
    • 再次点击分离

隔离保证

  • 独立用户数据目录：不会触碰您的个人浏览器配置文件
  • 独立端口：避免与开发工作流冲突（不使用 9222 端口）
  • 确定性标签页控制：通过 targetId 精确定位标签页

浏览器选择

本地启动时，Openclaw 按以下顺序选择：

  1. Chrome
  2. Brave
  3. Edge
  4. Chromium
  5. Chrome Canary

各平台搜索位置：

  • macOS：/Applications 和 ~/Applications
  • Linux：google-chrome、brave、microsoft-edge、chromium 等
  • Windows：常见安装位置

CLI 命令参考

所有命令都支持 --browser-profile <名称> 指定配置文件，--json 输出 JSON 格式。

基础操作

bash
# 浏览器状态
openclaw browser status
openclaw browser start
openclaw browser stop

# 标签页管理
openclaw browser tabs              # 列出所有标签页
openclaw browser tab new           # 新建标签页
openclaw browser tab select 2      # 选择第 2 个标签页
openclaw browser tab close 2       # 关闭第 2 个标签页
openclaw browser open https://example.com  # 打开网址

To persist browser downloads, set PLAYWRIGHT_BROWSERS_PATH (for example, /home/node/.cache/ms-playwright) and make sure /home/node is persisted via OPENCLAW_HOME_VOLUME or a bind mount. See Docker.

How it works (internal)

High-level flow:

  • A small control server accepts HTTP requests.
  • It connects to Chromium-based browsers (Chrome/Brave/Edge/Chromium) via CDP.
  • For advanced actions (click/type/snapshot/PDF), it uses Playwright on top of CDP.
  • When Playwright is missing, only non-Playwright operations are available.

This design keeps the agent on a stable, deterministic interface while letting you swap local/remote browsers and profiles.

CLI quick reference

All commands accept --browser-profile \<name\> to target a specific profile. All commands also accept --json for machine-readable output (stable payloads).

Basics:

  • openclaw browser status
  • openclaw browser start
  • openclaw browser stop
  • openclaw browser tabs
  • openclaw browser tab
  • openclaw browser tab new
  • openclaw browser tab select 2
  • openclaw browser tab close 2
  • openclaw browser open https://example.com
  • openclaw browser focus abcd1234
  • openclaw browser close abcd1234

Inspection:

  • openclaw browser screenshot
  • openclaw browser screenshot --full-page
  • openclaw browser screenshot --ref 12
  • openclaw browser screenshot --ref e12
  • openclaw browser snapshot
  • openclaw browser snapshot --format aria --limit 200
  • openclaw browser snapshot --interactive --compact --depth 6
  • openclaw browser snapshot --efficient
  • openclaw browser snapshot --labels
  • openclaw browser snapshot --selector "#main" --interactive
  • openclaw browser snapshot --frame "iframe#main" --interactive
  • openclaw browser console --level error
  • openclaw browser errors --clear
  • openclaw browser requests --filter api --clear
  • openclaw browser pdf
  • openclaw browser responsebody "**/api" --max-chars 5000

Actions:

  • openclaw browser navigate https://example.com
  • openclaw browser resize 1280 720
  • openclaw browser click 12 --double
  • openclaw browser click e12 --double
  • 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 download e12 report.pdf
  • openclaw browser waitfordownload report.pdf
  • openclaw browser upload /tmp/openclaw/uploads/file.pdf
  • openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
  • openclaw browser dialog --accept
  • openclaw browser wait --text "Done"
  • openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
  • openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
  • openclaw browser highlight e12
  • openclaw browser trace start
  • openclaw browser trace stop

State:

  • 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 --json '{"X-Debug":"1"}'
  • 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
  • openclaw browser set device "iPhone 14"

Notes:

  • upload and dialog are arming calls; run them before the click/press that triggers the chooser/dialog.
  • Download and trace output paths are constrained to OpenClaw temp roots:
    • traces: /tmp/openclaw (fallback: ${os.tmpdir()}/openclaw)
    • downloads: /tmp/openclaw/downloads (fallback: ${os.tmpdir()}/openclaw/downloads)
  • Upload paths are constrained to an OpenClaw temp uploads root:
    • uploads: /tmp/openclaw/uploads (fallback: ${os.tmpdir()}/openclaw/uploads)
  • upload can also set file inputs directly via --input-ref or --element.
  • snapshot:
    • --format ai (default when Playwright is installed): returns an AI snapshot with numeric refs (aria-ref="\<n\>").
    • --format aria: returns the accessibility tree (no refs; inspection only).
    • --efficient (or --mode efficient): compact role snapshot preset (interactive + compact + depth + lower maxChars).
    • Config default (tool/CLI only): set browser.snapshotDefaults.mode: "efficient" to use efficient snapshots when the caller does not pass a mode (see Gateway configuration).
    • Role snapshot options (--interactive, --compact, --depth, --selector) force a role-based snapshot with refs like ref=e12.
    • --frame "<iframe selector>" scopes role snapshots to an iframe (pairs with role refs like e12).
    • --interactive outputs a flat, easy-to-pick list of interactive elements (best for driving actions).
    • --labels adds a viewport-only screenshot with overlayed ref labels (prints MEDIA:\<path\>).
  • click/type/etc require a ref from snapshot (either numeric 12 or role ref e12). CSS selectors are intentionally not supported for actions.

Snapshots and refs

OpenClaw supports two “snapshot” styles:

  • AI snapshot (numeric refs): openclaw browser snapshot (default; --format ai)

    • Output: a text snapshot that includes numeric refs.
    • Actions: openclaw browser click 12, openclaw browser type 23 "hello".
    • Internally, the ref is resolved via Playwright’s aria-ref.

  • Role snapshot (role refs like e12): openclaw browser snapshot --interactive (or --compact, --depth, --selector, --frame)

    • Output: a role-based list/tree with [ref=e12] (and optional [nth=1]).
    • Actions: openclaw browser click e12, openclaw browser highlight e12.
    • Internally, the ref is resolved via getByRole(...) (plus nth() for duplicates).
    • Add --labels to include a viewport screenshot with overlayed e12 labels.

Ref behavior:

  • Refs are not stable across navigations; if something fails, re-run snapshot and use a fresh ref.
  • If the role snapshot was taken with --frame, role refs are scoped to that iframe until the next role snapshot.

Wait power-ups

You can wait on more than just time/text:

  • Wait for URL (globs supported by Playwright):
    • openclaw browser wait --url "**/dash"
  • Wait for load state:
    • openclaw browser wait --load networkidle
  • Wait for a JS predicate:
    • openclaw browser wait --fn "window.ready===true"
  • Wait for a selector to become visible:
    • openclaw browser wait "#main"

These can be combined:

页面检查

bash
# 截图
openclaw browser screenshot              # 当前视窗
openclaw browser screenshot --full-page  # 整页截图
openclaw browser screenshot --ref 12     # 元素截图

# 页面快照
openclaw browser snapshot                # AI 快照
openclaw browser snapshot --interactive  # 交互元素列表
openclaw browser snapshot --efficient    # 精简模式

# 调试信息
openclaw browser console --level error   # 控制台错误
openclaw browser errors --clear          # 页面错误
openclaw browser requests --filter api   # 网络请求
openclaw browser pdf                     # 导出 PDF

页面操作

bash
# 导航
openclaw browser navigate https://example.com
openclaw browser resize 1280 720

# 交互（需先获取 snapshot 中的 ref）
openclaw browser click 12              # 点击元素
openclaw browser click 12 --double     # 双击
openclaw browser type 23 "你好"        # 输入文本
openclaw browser type 23 "你好" --submit  # 输入并提交
openclaw browser press Enter           # 按键
openclaw browser hover 44              # 悬停
openclaw browser select 9 "选项A"      # 选择下拉框

# 等待
openclaw browser wait --text "完成"    # 等待文本出现
openclaw browser wait "#main"          # 等待元素可见
openclaw browser wait --load networkidle  # 等待网络空闲

# 文件
openclaw browser upload /tmp/file.pdf  # 上传文件
openclaw browser download e12 /tmp/report.pdf  # 下载

状态管理

bash
# Cookies
openclaw browser cookies               # 查看 cookies
openclaw browser cookies clear         # 清除 cookies

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

# 环境设置
openclaw browser set offline on        # 离线模式
openclaw browser set media dark        # 深色模式
openclaw browser set timezone Asia/Shanghai  # 时区
openclaw browser set locale zh-CN      # 语言
openclaw browser set device "iPhone 14"  # 设备模拟

快照和引用 (ref)

Openclaw 支持两种快照模式：

模式命令引用格式适用场景
AI 快照snapshot12（数字）默认，AI 助手使用
角色快照snapshot --interactivee12交互元素列表

使用流程：

  1. 获取快照：openclaw browser snapshot
  2. 找到目标元素的 ref
  3. 执行操作：openclaw browser click 12

注意： ref 在页面导航后会失效，需要重新获取快照。

调试技巧

当操作失败时（如“元素不可见”、“被遮挡”）：

  1. 获取交互元素列表：openclaw browser snapshot --interactive
  2. 高亮显示目标元素：openclaw browser highlight e12
  3. 查看页面错误：openclaw browser errors --clear
  4. 查看网络请求：openclaw browser requests --filter api
  5. 录制跟踪：
    bash
    openclaw browser trace start
# 重现问题
openclaw browser trace stop  # 输出跟踪文件路径

安全与隐私

  • 浏览器配置文件可能包含登录会话，请妥善保管
  • 登录和反机器人检测说明请参考 浏览器登录
  • 控制 URL 应保持本地访问，除非您有意暴露

故障排除

Linux 特有问题（尤其是 snap 版 Chromium），请参考 浏览器故障排除（Linux）。

相关文档

上一节：工具概述
下一节：斜杠命令