浏览器控制（OpenClaw 托管）

OpenClaw 可以运行一个专用的 Chrome/Brave/Edge/Chromium 配置文件，由智能体控制。它与您的个人浏览器隔离，并通过网关内的一个小型本地控制服务管理（仅限回环）。

入门视图：

将其视为独立的、仅智能体使用的浏览器。
openclaw 配置文件不会触及您的个人浏览器配置文件。
智能体可以打开标签页、读取页面、点击和输入，在安全的车道中。
默认的 chrome 配置文件通过扩展中继使用系统默认 Chromium 浏览器；切换到 openclaw 以使用隔离的托管浏览器。

您获得的功能

一个名为 openclaw 的独立浏览器配置文件（默认橙色强调色）。
确定性标签控制（列表/打开/聚焦/关闭）。
智能体操作（点击/类型/拖动/选择）、快照、截图、PDF。
可选的多配置文件支持（openclaw、work、remote，...）。

此浏览器不是您的日常驱动程序。它是智能体自动化和验证的安全、隔离的界面。

快速开始

bash

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

如果看到"Browser disabled"，在配置中启用它（见下文）并重启网关。

配置文件：`openclaw` vs `chrome`

openclaw：托管的、隔离的浏览器（不需要扩展）。
chrome：到您的系统浏览器的扩展中继（需要 OpenClaw 扩展附加到标签页）。

如果想要默认托管模式，设置 browser.defaultProfile: "openclaw"。

配置

浏览器设置位于 ~/.openclaw/openclaw.json。

json5

{
  browser: {
    enabled: true,                    // 默认: true
    // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置覆盖
    remoteCdpTimeoutMs: 1500,         // 远程 CDP HTTP 超时 (毫秒)
    remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时 (毫秒)
    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.port 或 OPENCLAW_GATEWAY_PORT），派生的浏览器端口会移动以保持在同一个"系列"中。
cdpUrl 未设置时默认为中继端口。
remoteCdpTimeoutMs 适用于远程（非回环）CDP 可达性检查。
remoteCdpHandshakeTimeoutMs 适用于远程 CDP WebSocket 可达性检查。
attachOnly: true 意味着"从不启动本地浏览器；仅当它已经在运行时才附加"。
color + 每配置 color 着色浏览器 UI，以便您可以看到哪个配置文件是活动的。
默认配置文件是 chrome（扩展中继）。对托管浏览器使用 defaultProfile: "openclaw"。
自动检测顺序：如果基于 Chromium 则为系统默认浏览器；否则 Chrome → Brave → Edge → Chromium → Chrome Canary。
本地 openclaw 配置文件自动分配 cdpPort/cdpUrl — 仅对远程 CDP 设置这些。

使用 Brave（或另一个基于 Chromium 的浏览器）

如果您的系统默认浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），OpenClaw 自动使用它。设置 browser.executablePath 覆盖自动检测：

CLI 示例：

bash

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

json5

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

// Windows
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
  }
}

// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

本地 vs 远程控制

本地控制（默认）： 网关启动回环控制服务，可以启动本地浏览器。
远程控制（节点主机）： 在有浏览器的机器上运行节点主机；网关将浏览器操作代理到它。
远程 CDP： 设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以附加到远程基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。

远程 CDP URL 可以包含认证：

查询令牌（例如，https://provider.example?token=<token>）
HTTP 基本认证（例如，https://user:pass@provider.example）

OpenClaw 在调用 /json/* 端点和连接 CDP WebSocket 时保留认证。优先使用环境变量或密钥管理器的令牌，而不是将它们提交到配置文件。

节点浏览器代理（零配置默认）

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

注意：

节点主机通过代理命令公开其本地浏览器控制服务器。
配置文件来自节点自己的 browser.profiles 配置（与本地相同）。
如果您不想要它，请禁用：
- 在节点上：nodeHost.browserProxy.enabled=false
- 在网关上：gateway.nodes.browser.mode="off"

Browserless（托管远程 CDP）

Browserless 是一个托管的 Chromium 服务，通过 HTTPS 暴露 CDP 端点。您可以将 OpenClaw 浏览器配置文件指向 Browserless 区域端点并使用您的 API 密钥进行认证。

示例：

json5

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00"
      }
    }
  }
}

注意：

将 <BROWSERLESS_API_KEY> 替换为您的真实 Browserless 令牌。
选择与您的 Browserless 账户匹配的区域端点（见其文档）。

安全

关键思想：

浏览器控制仅限回环；访问通过网关的认证或节点配对流动。
保持网关和任何节点主机在专用网络（Tailscale）；避免公共暴露。
将远程 CDP URL/令牌视为密钥；优先使用环境变量或密钥管理器。

远程 CDP 提示：

优先使用 HTTPS 端点和短命令牌（如果可能）。
避免直接将长命令牌嵌入配置文件。

配置文件（多浏览器）

OpenClaw 支持多个命名的配置文件（路由配置）。配置文件可以是：

openclaw 托管：专用的基于 Chromium 的浏览器实例，有自己的用户数据目录 + CDP 端口
远程：明确的 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
扩展中继：通过本地 CDP 中继 + Chrome 扩展您现有的 Chrome 标签页

默认值：

如果缺失，自动创建 openclaw 配置文件。
chrome 配置文件是内置的用于 Chrome 扩展中继（默认指向 http://127.0.0.1:18792）。
本地 CDP 端口默认从 18800–18899 分配。
删除配置文件将其本地数据目录移动到废纸篓。

所有控制端点接受 ?profile=<name>；CLI 使用 --browser-profile。

Chrome 扩展中继（使用您现有的 Chrome）

OpenClaw 还可以通过本地 CDP 中继 + Chrome 扩展驱动您现有的 Chrome 标签页（没有单独的"openclaw" Chrome 实例）。

完整指南：Chrome 扩展

流程：

网关在本地运行（同一台机器）或节点主机在浏览器机器上运行。
本地中继服务器在回环 cdpUrl（默认：http://127.0.0.1:18792）监听。
您点击标签页上的 OpenClaw Browser Relay 扩展图标以附加（它不会自动附加）。
智能体通过正常的 browser 工具控制该标签页，通过选择正确的配置文件。

如果网关在其他地方运行，在浏览器机器上运行节点主机，以便网关可以代理浏览器操作。

沙箱会话

如果智能体会话是沙箱化的，browser 工具可能默认为 target="sandbox"（沙箱浏览器）。 Chrome 扩展中继接管需要主机浏览器控制，因此：

运行会话非沙箱化，或
设置 agents.defaults.sandbox.browser.allowHostControl: true 并在调用工具时使用 target="host"。

设置

加载扩展（开发/未打包）：

bash

openclaw browser extension install

Chrome → chrome://extensions → 启用"开发者模式"
"加载已解压" → 选择 openclaw browser extension path 打印的目录
固定扩展，然后在其控制的标签页上点击它（徽章显示 ON）。

使用它：

CLI：openclaw browser --browser-profile chrome tabs
智能体工具：browser 配合 profile="chrome"

可选：如果您想要不同的名称或中继端口，创建您自己的配置文件：

bash

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

注意：

此模式依赖 Playwright-on-CDP 进行大多数操作（截图/快照/操作）。
通过再次点击扩展图标分离。

隔离保证

专用用户数据目录：从不触及您的个人浏览器配置文件。
专用端口：避免 9222 以防止与开发工作流冲突。
确定性标签控制：按 targetId 而不是"最后一个标签"定位标签页。

浏览器选择

在本地启动时，OpenClaw 选择第一个可用的：

Chrome
Brave
Edge
Chromium
Chrome Canary

您可以通过 browser.executablePath 覆盖。

平台：

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

控制 API（可选）

仅用于本地集成，网关暴露一个小型回环 HTTP API：

状态/启动/停止：GET /、POST /start、POST /stop
标签页：GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId
快照/截图：GET /snapshot、POST /screenshot
操作：POST /navigate、POST /act
Hooks：POST /hooks/file-chooser、POST /hooks/dialog
下载：POST /download、POST /wait/download
调试：GET /console、POST /pdf
调试：GET /errors、GET /requests、POST /trace/start、POST /trace/stop、POST /highlight
网络：POST /response/body
状态：GET /cookies、POST /cookies/set、POST /cookies/clear
状态：GET /storage/:kind、POST /storage/:kind/set、POST /storage/:kind/clear
设置：POST /set/offline、POST /set/headers、POST /set/credentials、POST /set/geolocation、POST /set/media、POST /set/timezone、POST /set/locale、POST /set/device

所有端点接受 ?profile=<name>。

Playwright 要求

某些功能（导航/操作/AI 快照/角色快照、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点返回清晰的 501 错误。ARIA 快照和基本截图仍然适用于 openclaw 托管的 Chrome。对于 Chrome 扩展中继驱动程序，ARIA 快照和截图需要 Playwright。

如果您看到 Playwright is not available in this gateway build，安装完整的 Playwright 包（不是 playwright-core）并重启网关，或使用浏览器支持重新安装 OpenClaw。

工作原理（内部）

高层流程：

一个小的控制服务器接受 HTTP 请求。
它通过 CDP 连接到基于 Chromium 的浏览器（Chrome/Brave/Edge/Chromium）。
对于高级操作（点击/类型/快照/PDF），它在 CDP 之上使用 Playwright。
当 Playwright 缺失时，只有非 Playwright 操作可用。

此设计使智能体保持稳定、确定的接口，同时让您交换本地/远程浏览器和配置文件。

CLI 快速参考

所有命令接受 --browser-profile <name> 以定位特定配置文件。所有命令也接受 --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 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

操作：

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 /tmp/report.pdf
openclaw browser waitfordownload /tmp/report.pdf
openclaw browser upload /tmp/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

状态：

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"

注意：

upload 和 dialog 是准备调用；在触发选择器/对话框的点击/按压之前运行它们。
upload 也可以通过 --input-ref 或 --element 直接设置文件输入。
snapshot:
- --format ai（默认，当 Playwright 安装时）：返回带有数字引用的 AI 快照（aria-ref="<n>"）。
- --format aria：返回可访问性树（无引用；仅检查）。
- --efficient（或 --mode efficient）：紧凑的角色快照预设（交互 + 紧凑 + 深度 + 较低 maxChars）。
- 配置默认（仅工具/CLI）：设置 browser.snapshotDefaults.mode: "efficient" 以在调用者未传递模式时使用高效快照（见网关配置）。
- 角色快照选项（--interactive、--compact、--depth、--selector）强制使用带引用的基于角色的快照（如 ref=e12）。
- --frame "<iframe selector>" 将角色快照作用域限定为 iframe（与角色引用如 e12 配对）。
- --interactive 输出一个扁平的、易于选择的交互元素列表（最适合驱动操作）。
- --labels 添加带有叠加 ref 标签的视口截图（打印 MEDIA:<path>）。
click/type/etc 需要来自 snapshot 的 ref（数字 12 或角色引用 e12）。 CSS 选择器故意不支持用于操作。

快照和引用

OpenClaw 支持两种"快照"样式：

AI 快照（数字引用）：openclaw browser snapshot（默认；--format ai）
- 输出：包含数字引用的文本快照。
- 操作：openclaw browser click 12、openclaw browser type 23 "hello"。
- 内部，引用通过 Playwright 的 aria-ref 解析。
角色快照（角色引用如 e12）：openclaw browser snapshot --interactive（或 --compact、--depth、--selector、--frame）
- 输出：带 [ref=e12]（和可选 [nth=1]）的基于角色的列表/树。
- 操作：openclaw browser click e12、openclaw browser highlight e12。
- 内部，引用通过 getByRole(...) 解析（加上 nth() 用于重复项）。
- 添加 --labels 以包含带有叠加 e12 标签的视口截图。

引用行为：

引用在导航之间不稳定；如果失败，重新运行 snapshot 并使用新的引用。
如果角色快照是使用 --frame 拍摄的，角色引用作用域限定为该 iframe 直到下一个角色快照。

等待增强

您可以等待的不只是时间/文本：

等待 URL（Playwright 支持通配符）：
- openclaw browser wait --url "**/dash"
等待加载状态：
- openclaw browser wait --load networkidle
等待 JS 谓词：
- openclaw browser wait --fn "window.ready===true"
等待选择器变为可见：
- openclaw browser wait "#main"

这些可以组合：

bash

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

调试工作流

当操作失败时（例如，"不可见"、"严格模式违规"、"被覆盖"）：

openclaw browser snapshot --interactive
使用 click <ref> / type <ref>（在交互模式中优先使用角色引用）
如果仍然失败：openclaw browser highlight <ref> 查看 Playwright 定位什么
如果页面行为奇怪：
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
深度调试：录制跟踪：
- openclaw browser trace start
- 重现问题
- openclaw browser trace stop（打印 TRACE:<path>）

JSON 输出

--json 用于脚本化和结构化工具。

示例：

bash

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

JSON 中的角色快照包含 refs 以及一个小的 stats 块（行/字符/引用/交互），以便工具可以推理负载大小和密度。

状态和环境旋钮

这些对于"让网站表现得像 X"工作流很有用：

Cookie：cookies、cookies set、cookies clear
存储：storage local|session get|set|clear
离线：set offline on|off
标头：set headers --json '{"X-Debug":"1"}'（或 --clear）
HTTP 基本认证：set credentials user pass（或 --clear）
地理位置：set geo <lat> <lon> --origin "https://example.com"（或 --clear）
媒体：set media dark|light|no-preference|none
时区/区域设置：set timezone ...、set locale ...
设备/视口：
- set device "iPhone 14"（Playwright 设备预设）
- set viewport 1280 720

安全与隐私

openclaw 浏览器配置文件可能包含登录会话；将其视为敏感。
browser act kind=evaluate / openclaw browser evaluate 和 wait --fn 在页面上下文中执行任意 JavaScript。提示注入可以引导它。如果不需要它，通过 browser.evaluateEnabled=false 禁用它。
对于登录和反机器人注意事项（X/Twitter 等），见浏览器登录 + X/Twitter 发布。
保持网关/节点主机私有（仅回环或 tailnet）。
远程 CDP 端点很强大；隧道和保护它们。

故障排除

对于 Linux 特定问题（特别是 snap Chromium），见浏览器故障排除。

智能体工具 + 控制如何工作

智能体获得一个用于浏览器自动化的工具：

browser — 状态/启动/停止/标签页/打开/聚焦/关闭/快照/截图/导航/操作

它如何映射：

browser snapshot 返回稳定的 UI 树（AI 或 ARIA）。
browser act 使用快照 ref ID 来点击/类型/拖动/选择。
browser screenshot 捕获像素（全页或元素）。
browser 接受：
- profile 选择命名的浏览器配置文件（openclaw、chrome 或远程 CDP）。
- target（sandbox | host | node）选择浏览器所在的位置。
- 在沙箱会话中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
- 如果省略 target：沙箱会话默认为 sandbox，非沙箱会话默认为 host。
- 如果连接了支持浏览器的节点，工具可能会自动路由到它，除非您固定 target="host" 或 target="node"。

这使智能体保持确定性并避免脆弱的选择器。

浏览器控制（OpenClaw 托管） ​

您获得的功能 ​

快速开始 ​

配置文件：openclaw vs chrome ​

配置 ​

使用 Brave（或另一个基于 Chromium 的浏览器） ​

本地 vs 远程控制 ​

节点浏览器代理（零配置默认） ​

Browserless（托管远程 CDP） ​

安全 ​

配置文件（多浏览器） ​

Chrome 扩展中继（使用您现有的 Chrome） ​

沙箱会话 ​

设置 ​

隔离保证 ​

浏览器选择 ​

控制 API（可选） ​

Playwright 要求 ​

工作原理（内部） ​

CLI 快速参考 ​

快照和引用 ​

等待增强 ​

调试工作流 ​

JSON 输出 ​

状态和环境旋钮 ​

安全与隐私 ​

故障排除 ​

智能体工具 + 控制如何工作 ​

浏览器控制（OpenClaw 托管）

您获得的功能

快速开始

配置文件：`openclaw` vs `chrome`

配置

使用 Brave（或另一个基于 Chromium 的浏览器）

本地 vs 远程控制

节点浏览器代理（零配置默认）

Browserless（托管远程 CDP）

安全

配置文件（多浏览器）

Chrome 扩展中继（使用您现有的 Chrome）

沙箱会话

设置

隔离保证

浏览器选择

控制 API（可选）

Playwright 要求

工作原理（内部）

CLI 快速参考

快照和引用

等待增强

调试工作流

JSON 输出

状态和环境旋钮

安全与隐私

故障排除

智能体工具 + 控制如何工作