工具自动化15 分钟阅读中级

浏览器控制

OpenClaw 可以运行一个由 AI 代理控制的专用 Chrome/Brave/Edge/Chromium 配置文件,实现安全的网页自动化

你将学到

OpenClaw 浏览器控制的核心概念和隔离机制
如何配置 openclaw 和 chrome 两种浏览器配置文件
使用 CLI 命令进行浏览器自动化操作
本地控制 vs 远程控制的工作原理
Chrome 扩展中继模式的设置和使用
快照(Snapshot)和引用(Refs)系统
安全最佳实践和隐私保护

目录导航

什么是浏览器控制

OpenClaw 可以运行一个由 AI 代理控制的专用 Chrome/Brave/Edge/Chromium 配置文件。它与你的个人浏览器隔离,通过 Gateway 内部的小型本地控制服务进行管理(仅限本地回环)。

初学者视角

•把它想象成一个单独的、仅供 AI 使用的浏览器
•openclaw 配置文件不会影响你的个人浏览器配置
•代理可以在安全的环境中打开标签页、阅读页面、点击和输入
•默认的 chrome 配置文件通过扩展中继使用系统默认的 Chromium 浏览器;切换到 openclaw 可使用隔离的托管浏览器

你能得到什么

一个名为 openclaw 的独立浏览器配置文件(默认为橙色强调)
确定性标签页控制(列表/打开/聚焦/关闭)
代理操作(点击/输入/拖动/选择)、快照、截图、PDF
可选的多配置文件支持(openclaw、work、remote 等)
这不是你的日常浏览器——它是用于代理自动化和验证的安全、隔离的界面

快速开始

使用以下命令快速开始使用浏览器控制:

检查浏览器状态

openclaw browser --browser-profile openclaw status

启动浏览器

openclaw browser --browser-profile openclaw start

打开网页

openclaw browser --browser-profile openclaw open https://example.com

获取页面快照

openclaw browser --browser-profile openclaw snapshot

如果出现"浏览器已禁用"提示,请在配置中启用并重启 Gateway

浏览器配置文件

OpenClaw 支持两种主要的浏览器配置文件模式:

openclaw - 托管隔离浏览器

由 OpenClaw 管理的独立 Chromium 实例,拥有自己的用户数据目录和 CDP 端口,无需扩展即可工作。这是最安全和隔离的方式。

chrome - 扩展中继

通过本地中继 + Chrome 扩展驱动你现有的 Chrome 标签页,需要安装 OpenClaw 扩展并将其附加到标签页。

提示: 如果默认想使用托管模式,设置 browser.defaultProfile: "openclaw"

配置详解

浏览器设置位于 ~/.openclaw/openclaw.json 配置文件中:

~/.openclaw/openclaw.json

browser:
  enabled: true
  remoteCdpTimeoutMs: 1500
  remoteCdpHandshakeTimeoutMs: 3000
  defaultProfile: "chrome"
  color: "#FF4500"
  headless: false
  noSandbox: false
  attachOnly: false
  executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  profiles:
    openclaw:
      cdpPort: 18800
      color: "#FF4500"
    work:
      cdpPort: 18801
      color: "#0066CC"
    remote:
      cdpUrl: "http://10.0.0.42:9222"
      color: "#00AA00"

浏览器控制服务绑定到从 gateway.port 派生的端口上的回环地址(默认: 18791,即 gateway + 2)

中继使用下一个端口(18792)

如果覆盖 Gateway 端口,派生的浏览器端口也会相应移动

cdpUrl 在未设置时默认为中继端口

attachOnly: true 表示"永不启动本地浏览器;仅在已运行时附加"

color 和每个配置文件的 color 会对浏览器 UI 进行着色,以便你看到哪个配置文件处于活动状态

默认配置文件是 chrome(扩展中继),使用 defaultProfile: "openclaw" 切换到托管浏览器

浏览器选择

在本地启动时,OpenClaw 按顺序自动检测并选择第一个可用的浏览器。你也可以通过 browser.executablePath 覆盖自动检测。

自动检测顺序

如果系统默认浏览器是基于 Chromium 的(Chrome/Brave/Edge 等),OpenClaw 会自动使用它。自动检测顺序:

•系统默认浏览器(如果是基于 Chromium 的)
•Chrome
•Brave
•Edge
•Chromium
•Chrome Canary

macOS

/Applications/Brave Browser.app/Contents/MacOS/Brave Browser

Windows

C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe

Linux

/usr/bin/brave-browser

本地与远程控制

OpenClaw 支持两种控制模式:

本地控制(默认)

Gateway 启动本地回环控制服务并可以启动本地浏览器

远程控制(节点主机)

在拥有浏览器的机器上运行节点主机,Gateway 将浏览器操作代理到它

节点浏览器代理(零配置默认)

如果你在拥有浏览器的机器上运行节点主机,OpenClaw 可以自动将浏览器工具调用路由到该节点,无需任何额外的浏览器配置。这是远程 Gateway 的默认路径。

•节点主机通过代理命令公开其本地浏览器控制服务器
•配置文件来自节点自己的 browser.profiles 配置(与本地相同)
•禁用方法:在节点上设置 nodeHost.browserProxy.enabled=false,在 Gateway 上设置 gateway.nodes.browser.mode="off"

Chrome 扩展中继

OpenClaw 还可以通过本地 CDP 中继 + Chrome 扩展驱动你现有的 Chrome 标签页(无需单独的"openclaw" Chrome 实例)。

工作流程

1.Gateway 在本地运行(同一机器)或在浏览器机器上运行节点主机
2.本地中继服务器在回环 cdpUrl 上监听(默认: http://127.0.0.1:18792)
3.点击 OpenClaw Browser Relay 扩展图标附加到标签页(它不会自动附加)
4.代理通过正常的浏览器工具控制该标签页,通过选择正确的配置文件
5.如果 Gateway 在其他地方运行,请在浏览器机器上运行节点主机,以便 Gateway 可以代理浏览器操作

openclaw browser extension install

安装扩展(开发/未打包)

Chrome → chrome://extensions → 启用"开发者模式"

启用 Chrome 开发者模式

"加载未打包" → 选择 openclaw browser extension path 打印的目录

加载扩展

固定扩展,然后在你想要控制的标签页上点击它(徽章显示 ON)

附加扩展到标签页

CLI 命令参考

所有命令都接受 --browser-profile 配置文件名称来定位特定配置文件,以及 --json 用于机器可读输出(稳定负载)。

基础命令

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

openclaw browser screenshot

openclaw browser screenshot --full-page

openclaw browser snapshot

openclaw browser navigate https://example.com

openclaw browser click 12 --double

快照命令

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

Note: AI 快照返回带有数字引用的文本快照;角色快照返回带有 [ref=e12] 的基于角色的列表/树

状态管理

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 set offline on

openclaw browser set geo 37.7749 -122.4194

openclaw browser set timezone America/New_York

快照和引用

OpenClaw 支持两种"快照"样式,用于页面元素识别和交互:

AI 快照(数字引用)

使用 openclaw browser snapshot(默认;--format ai)获取带有数字引用的快照

openclaw browser click 12

角色快照(角色引用如 e12)

使用 openclaw browser snapshot --interactive(或 --compact、--depth、--selector、--frame)获取带有 [ref=e12] 的基于角色的列表

openclaw browser click e12

引用行为说明

•引用在导航之间不稳定;如果操作失败,请重新运行快照并使用新的引用
•如果角色快照是使用 --frame 拍摄的,角色引用将限定在该 iframe,直到下一个角色快照
•click/type 等需要来自快照的引用(数字 12 或角色引用 e12),CSS 选择器故意不支持操作

安全与隐私

核心安全原则

•浏览器控制仅限本地回环;访问通过 Gateway 的身份验证或节点配对流动
•将 Gateway 和任何节点主机保持在私有网络(如 Tailscale)上;避免公开暴露
•将远程 CDP URL/令牌视为秘密;优先使用环境变量或秘密管理器
•优先使用 HTTPS 端点和短寿命令牌
•避免将长寿命令牌直接嵌入配置文件

隐私警告

!openclaw 浏览器配置文件可能包含已登录的会话;将其视为敏感数据
!browser act kind=evaluate / openclaw browser evaluate 和 wait --fn 在页面上下文中执行任意 JavaScript
!提示注入可以控制 JavaScript 执行;如果不需要,使用 browser.evaluateEnabled=false 禁用它
!保持 Gateway/节点主机私有(仅限本地回环或 tailnet)
!远程 CDP 端点功能强大;请通过隧道保护它们

代理工具

AI 代理获得一个用于浏览器自动化的工具,支持状态/启动/停止/标签页/打开/聚焦/关闭/快照/截图/导航/操作。

browser 工具

所有控制端点接受 ?profile=配置文件名称参数来选择特定的浏览器配置文件

browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

profile

选择命名浏览器配置文件(openclaw、chrome 或远程 CDP)

target

选择浏览器所在位置(sandbox | host | node)。在沙盒会话中,target: host 需要 agents.defaults.sandbox.browser.allowHostControl=true

继续学习

浏览器控制只是 OpenClaw 强大功能的一部分。探索更多教程和文档:

查看全部教程访问官方文档