浏览器工具（OpenClaw 管理）

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

入门视角：

可以把它理解为一个独立的、仅供智能体使用的浏览器。
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"，请在配置中启用它（见下方）并重启 Gateway。

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

openclaw：受管的隔离浏览器（不需要扩展）。
chrome：通过扩展中继连接到你的系统浏览器（需要 OpenClaw 扩展附加到某个标签页上）。

如果你想默认使用受管模式，设置 browser.defaultProfile: "openclaw"。

配置

浏览器设置保存在 ~/.openclaw/openclaw.json 中。

json5

{
  browser: {
    enabled: true, // 默认：true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // 默认信任网络模式
      // allowPrivateNetwork: true, // 旧版别名
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // 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 端口（gateway.port 或 OPENCLAW_GATEWAY_PORT），派生的浏览器端口会同步移动以保持在同一"族"中。
cdpUrl 未设置时默认为中继端口。
remoteCdpTimeoutMs 适用于远程（非回环）CDP 可达性检查。
remoteCdpHandshakeTimeoutMs 适用于远程 CDP WebSocket 可达性检查。
浏览器导航/打开标签页在导航前进行 SSRF 防护，并在导航后对最终的 http(s) URL 进行尽力的二次检查。
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 默认为 true（信任网络模型）。设置为 false 可实现严格的仅公网浏览。
browser.ssrfPolicy.allowPrivateNetwork 作为旧版别名仍受支持。
attachOnly: true 意味着"从不启动本地浏览器；仅在已运行时附加"。
color + 每个配置文件的 color 给浏览器 UI 添加色调，方便你识别当前激活的配置文件。
默认配置文件为 openclaw（OpenClaw 管理的独立浏览器）。使用 defaultProfile: "chrome" 可切换到 Chrome 扩展中继。
自动检测顺序：如果系统默认浏览器基于 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"
  }
}

本地控制与远程控制

本地控制（默认）： Gateway 启动回环控制服务并可以启动本地浏览器。
远程控制（节点主机）： 在拥有浏览器的机器上运行节点主机；Gateway 将浏览器操作代理到该节点。
远程 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 可以自动将浏览器工具调用路由到该节点，无需额外的浏览器配置。这是远程 gateway 的默认路径。

注意事项：

节点主机通过代理命令暴露其本地浏览器控制服务。
配置文件来自节点自身的 browser.profiles 配置（与本地相同）。
如果不需要，可以禁用：
- 在节点上：nodeHost.browserProxy.enabled=false
- 在 gateway 上：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 账户匹配的区域端点（参见其文档）。

安全

核心理念：

浏览器控制仅限回环地址；访问通过 Gateway 的认证或节点配对流转。
如果启用了浏览器控制但未配置认证，OpenClaw 在启动时自动生成 gateway.auth.token 并持久化到配置中。
将 Gateway 和任何节点主机保持在私有网络中（Tailscale）；避免公开暴露。
将远程 CDP URL/令牌视为密钥；建议使用环境变量或密钥管理器。

远程 CDP 提示：

尽可能使用 HTTPS 端点和短期令牌。
避免在配置文件中直接嵌入长期令牌。

配置文件（多浏览器）

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

openclaw 管理的：具有自己的用户数据目录 + CDP 端口的专用 Chromium 浏览器实例
远程的：明确的 CDP URL（在其他地方运行的 Chromium 浏览器）
扩展中继：通过本地中继 + 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 扩展

流程：

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

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

沙箱会话

如果智能体会话被沙箱化，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（可选）

仅用于本地集成，Gateway 暴露一个小型的回环 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
钩子：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>。

如果配置了 gateway 认证，浏览器 HTTP 路由也需要认证：

Authorization: Bearer <gateway token>
x-openclaw-password: <gateway password> 或使用该密码的 HTTP 基本认证

Playwright 要求

某些功能（navigate/act/AI 快照/角色快照、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回明确的 501 错误。ARIA 快照和基本截图对 openclaw 管理的 Chrome 仍然有效。对于 Chrome 扩展中继驱动，ARIA 快照和截图需要 Playwright。

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

Docker Playwright 安装

如果你的 Gateway 在 Docker 中运行，避免使用 npx playwright（npm 覆盖冲突）。改用内置 CLI：

bash

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

要持久化浏览器下载，设置 PLAYWRIGHT_BROWSERS_PATH（例如 /home/node/.cache/ms-playwright）并确保 /home/node 通过 OPENCLAW_HOME_VOLUME 或绑定挂载持久化。参见 Docker。

工作原理（内部）

高级流程：

一个小型控制服务器接受 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 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

状态管理：

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"}'
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 是准备性调用；在触发选择器/对话框的点击/按键之前运行它们。
下载和跟踪输出路径受限于 OpenClaw 临时根目录：
- traces：/tmp/openclaw（回退：${os.tmpdir()}/openclaw）
- downloads：/tmp/openclaw/downloads（回退：${os.tmpdir()}/openclaw/downloads）
上传路径受限于 OpenClaw 临时上传根目录：
- uploads：/tmp/openclaw/uploads（回退：${os.tmpdir()}/openclaw/uploads）
upload 也可以通过 --input-ref 或 --element 直接设置文件输入。
snapshot：
- --format ai（安装了 Playwright 时的默认值）：返回带有数字引用的 AI 快照（aria-ref="<n>"）。
- --format aria：返回无障碍树（无引用；仅用于检查）。
- --efficient（或 --mode efficient）：紧凑的角色快照预设（interactive + compact + depth + 较低的 maxChars）。
- 配置默认值（仅限工具/CLI）：设置 browser.snapshotDefaults.mode: "efficient" 以在调用者未传递 mode 时使用高效快照（参见 Gateway 配置）。
- 角色快照选项（--interactive、--compact、--depth、--selector）强制执行基于角色的快照，返回类似 ref=e12 的引用。
- --frame "<iframe selector>" 将角色快照范围限定到 iframe（配合角色引用如 e12）。
- --interactive 输出扁平的、易于选择的交互元素列表（最适合驱动操作）。
- --labels 添加带有叠加引用标签的视口截图（输出 MEDIA:<path>）。
click/type 等需要来自 snapshot 的 ref（AI 快照返回数字 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 的 glob）：
- openclaw browser wait --url "**/dash"
等待加载状态：
- openclaw browser wait --load networkidle
等待 JS 谓词：
- openclaw browser wait --fn "window.ready===true"

浏览器工具（OpenClaw 管理） ​

功能概览 ​

快速开始 ​

配置文件：openclaw vs chrome ​

配置 ​

使用 Brave（或其他基于 Chromium 的浏览器） ​

本地控制与远程控制 ​

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

Browserless（托管远程 CDP） ​

安全 ​

配置文件（多浏览器） ​

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

沙箱会话 ​

设置 ​

隔离保证 ​

浏览器选择 ​

控制 API（可选） ​

Playwright 要求 ​

Docker Playwright 安装 ​

工作原理（内部） ​

CLI 快速参考 ​

快照与引用 ​

等待增强功能 ​

浏览器工具（OpenClaw 管理）

功能概览

快速开始

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

配置

使用 Brave（或其他基于 Chromium 的浏览器）

本地控制与远程控制

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

Browserless（托管远程 CDP）

安全

配置文件（多浏览器）

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

沙箱会话

设置

隔离保证

浏览器选择

控制 API（可选）

Playwright 要求

Docker Playwright 安装

工作原理（内部）

CLI 快速参考

快照与引用

等待增强功能