Browser（openclaw 管理的浏览器）

OpenClaw 可以运行一个 专用的 Chrome/Brave/Edge/Chromium profile（配置文件），由 agent（代理）控制。它与你的个人浏览器隔离，并通过 Gateway（网关）内的一个小型本地控制服务进行管理（仅 loopback 回环访问）。

初学者视角：

  • 可以把它想象成一个 独立的、仅供 agent 使用的浏览器。
  • openclaw profile 配置文件 不会 影响你的个人浏览器配置文件。
  • agent 可以在一个安全的通道中 打开标签页、读取页面、点击和输入。
  • 默认的 chrome profile 通过 extension relay（扩展中继）使用 系统默认的 Chromium 浏览器；切换到 openclaw 以使用隔离的托管浏览器。

你能得到什么

  • 一个名为 openclaw 的独立浏览器配置文件（默认为橙色主题）。
  • 确定性的标签页控制（list/open/focus/close 列出/打开/聚焦/关闭）。
  • Agent 操作（click/type/drag/select 点击/输入/拖动/选择）、snapshots（快照）、screenshots（截图）、PDFs。
  • 可选的多配置文件支持（openclaw、work、remote 等）。

这个浏览器 不是 你日常使用的浏览器。它是一个安全的、隔离的界面，用于 agent 自动化和验证。

快速开始

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。

Profiles（配置文件）：openclaw vs chrome

  • openclaw：托管的、隔离的浏览器（不需要扩展）。
  • chrome：通过 extension relay 连接到你的 系统浏览器（需要 OpenClaw 扩展附加到标签页）。

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

配置

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

{
  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 派生的 loopback 端口（默认：18791，即 gateway + 2）。relay（中继）使用下一个端口（18792）。
  • 如果你覆盖了 Gateway 端口（gateway.port 或 OPENCLAW_GATEWAY_PORT），派生的浏览器端口会相应调整以保持在同一"家族"中。
  • 未设置时，cdpUrl 默认为 relay 端口。
  • remoteCdpTimeoutMs 适用于远程（非 loopback）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 示例：

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

// 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 远程控制

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

远程 CDP URL 可以包含认证信息：

  • Query tokens 查询令牌（例如，https://provider.example?token=<token>）
  • HTTP Basic auth（例如，https://user:[email protected]）

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

Node browser proxy（零配置默认）

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

注意事项：

  • node host 通过 proxy command（代理命令） 暴露其本地浏览器控制服务器。
  • Profiles 来自 node 自己的 browser.profiles 配置（与本地相同）。
  • 如果不想使用，可禁用：
    • 在 node 上：nodeHost.browserProxy.enabled=false
    • 在 gateway 上：gateway.nodes.browser.mode="off"

Browserless（托管的远程 CDP）

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

示例：

{
  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 token。
  • 选择与你的 Browserless 账户匹配的区域端点（参见他们的文档）。

安全性

关键要点：

  • 浏览器控制仅限 loopback；访问通过 Gateway 的认证或 node pairing（节点配对）流转。
  • 将 Gateway 和任何 node hosts 保持在私有网络（Tailscale）上；避免公开暴露。
  • 将远程 CDP URLs/tokens 视为密钥；优先使用环境变量或密钥管理器。

远程 CDP 提示：

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

Profiles（多浏览器）

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

  • openclaw 管理的：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口
  • 远程的：一个显式的 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
  • 扩展中继：通过本地 relay + Chrome 扩展使用你现有的 Chrome 标签页

默认值：

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

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

Chrome extension relay（使用你现有的 Chrome）

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

完整指南：Chrome extension

流程：

  • Gateway 在本地运行（同一台机器）或 node host 在浏览器机器上运行。
  • 一个本地 relay server 监听 loopback cdpUrl（默认：http://127.0.0.1:18792）。
  • 你点击标签页上的 OpenClaw Browser Relay 扩展图标以附加（它不会自动附加）。
  • agent 通过正常的 browser 工具控制该标签页，通过选择正确的 profile。

如果 Gateway 在别处运行，在浏览器机器上运行 node host，以便 Gateway 可以代理浏览器操作。

Sandboxed sessions（沙箱会话）

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

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

设置

  1. 加载扩展（dev/unpacked 开发/未打包）：
openclaw browser extension install
  • Chrome → chrome://extensions → 启用 "Developer mode（开发者模式）"
  • "Load unpacked（加载已解压的扩展程序）" → 选择由 openclaw browser extension path 打印的目录
  • 固定扩展，然后在你想控制的标签页上点击它（badge 显示 ON）。
  1. 使用它：
  • CLI：openclaw browser --browser-profile chrome tabs
  • Agent 工具：browser 带 profile="chrome"

可选：如果你想要不同的名称或 relay 端口，创建你自己的 profile：

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

注意事项：

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

隔离保证

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

浏览器选择

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

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

你可以使用 browser.executablePath 覆盖。

平台：

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

Control API（可选）

仅用于本地集成，Gateway 暴露一个小型 loopback HTTP API：

  • Status/start/stop：GET /、POST /start、POST /stop
  • Tabs：GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId
  • Snapshot/screenshot：GET /snapshot、POST /screenshot
  • Actions：POST /navigate、POST /act
  • Hooks：POST /hooks/file-chooser、POST /hooks/dialog
  • Downloads：POST /download、POST /wait/download
  • Debugging：GET /console、POST /pdf
  • Debugging：GET /errors、GET /requests、POST /trace/start、POST /trace/stop、POST /highlight
  • Network：POST /response/body
  • State：GET /cookies、POST /cookies/set、POST /cookies/clear
  • State：GET /storage/:kind、POST /storage/:kind/set、POST /storage/:kind/clear
  • Settings：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 要求

一些功能（navigate/act/AI snapshot/role snapshot、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回清晰的 501 错误。ARIA 快照和基本截图仍适用于 openclaw 管理的 Chrome。对于 Chrome 扩展中继驱动程序，ARIA 快照和截图需要 Playwright。

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

工作原理（内部）

高级流程：

  • 一个小型 control server 接受 HTTP 请求。
  • 它通过 CDP 连接到基于 Chromium 的浏览器（Chrome/Brave/Edge/Chromium）。
  • 对于高级操作（click/type/snapshot/PDF），它在 CDP 之上使用 Playwright。
  • 当缺少 Playwright 时，仅可用非 Playwright 操作。

这种设计使 agent 保持在稳定的、确定性的接口上，同时允许你交换本地/远程浏览器和配置文件。

CLI 快速参考

所有命令接受 --browser-profile <name> 以定位特定的配置文件。所有命令也接受 --json 以获取机器可读输出（稳定的 payloads）。

基础命令：

  • 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 是 预备（arming） 调用；在触发选择器/对话框的 click/press 之前运行它们。
  • upload 还可以通过 --input-ref 或 --element 直接设置文件输入。
  • snapshot：
    • --format ai（安装 Playwright 时的默认值）：返回带有数字 refs 的 AI 快照（aria-ref="<n>"）。
    • --format aria：返回可访问性树（无 refs；仅供检查）。
    • --efficient（或 --mode efficient）：紧凑的 role 快照预设（interactive + compact + depth + 更低的 maxChars）。
    • 配置默认值（仅工具/CLI）：设置 browser.snapshotDefaults.mode: "efficient" 以在调用者未传递 mode 时使用高效快照（参见 Gateway configuration）。
    • Role 快照选项（--interactive、--compact、--depth、--selector）强制使用带有类似 ref=e12 的 refs 的基于 role 的快照。
    • --frame "<iframe selector>" 将 role 快照范围限定到 iframe（与 role refs 如 e12 配对）。
    • --interactive 输出一个扁平的、易于选择的交互元素列表（最适合驱动操作）。
    • --labels 添加一个仅视口的截图，并覆盖 ref 标签（打印 MEDIA:<path>）。
  • click/type 等需要来自 snapshot 的 ref（数字 12 或 role ref e12）。有意不支持 CSS selectors 用于操作。

Snapshots 和 refs

OpenClaw 支持两种 "snapshot" 样式：

  • AI snapshot（数字 refs）：openclaw browser snapshot（默认；--format ai）

    • 输出：包含数字 refs 的文本快照。
    • 操作：openclaw browser click 12、openclaw browser type 23 "hello"。
    • 内部通过 Playwright 的 aria-ref 解析 ref。

  • Role snapshot（role refs 如 e12）：openclaw browser snapshot --interactive（或 --compact、--depth、--selector、--frame）

    • 输出：带有 [ref=e12]（和可选 [nth=1]）的基于 role 的列表/树。
    • 操作：openclaw browser click e12、openclaw browser highlight e12。
    • 内部通过 getByRole(...)（对于重复项加 nth()）解析 ref。
    • 添加 --labels 以包含带有覆盖的 e12 标签的视口截图。

Ref 行为：

  • Refs 在导航之间不稳定；如果某些操作失败，重新运行 snapshot 并使用新的 ref。
  • 如果 role 快照是用 --frame 拍摄的，role refs 的作用域限定在该 iframe 中，直到下一个 role 快照。

Wait power-ups（等待增强功能）

你可以等待的不仅仅是时间/文本：

  • 等待 URL（Playwright 支持的 globs）：
    • openclaw browser wait --url "**/dash"
  • 等待加载状态：
    • openclaw browser wait --load networkidle
  • 等待 JS 谓词：
    • openclaw browser wait --fn "window.ready===true"
  • 等待 selector 变为可见：
    • openclaw browser wait "#main"

这些可以组合使用：

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

调试工作流

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

  1. openclaw browser snapshot --interactive
  2. 使用 click <ref> / type <ref>（在交互模式下优先使用 role refs）
  3. 如果仍然失败：openclaw browser highlight <ref> 以查看 Playwright 在定位什么
  4. 如果页面行为异常：
    • openclaw browser errors --clear
    • openclaw browser requests --filter api --clear
  5. 对于深度调试：记录 trace：
    • openclaw browser trace start
    • 重现问题
    • openclaw browser trace stop（打印 TRACE:<path>）

JSON 输出

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

示例：

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

JSON 中的 role 快照包括 refs 加上一个小的 stats 块（lines/chars/refs/interactive），以便工具可以推理 payload 大小和密度。

状态和环境旋钮

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

  • Cookies：cookies、cookies set、cookies clear
  • Storage：storage local|session get|set|clear
  • Offline：set offline on|off
  • Headers：set headers --json '{"X-Debug":"1"}'（或 --clear）
  • HTTP basic auth：set credentials user pass（或 --clear）
  • Geolocation：set geo <lat> <lon> --origin "https://example.com"（或 --clear）
  • Media：set media dark|light|no-preference|none
  • Timezone / locale：set timezone ...、set locale ...
  • Device / viewport：
    • 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 等），参见 Browser login + X/Twitter posting。
  • 保持 Gateway/node host 私有（loopback 或仅 tailnet）。
  • 远程 CDP endpoints 功能强大；对其进行隧道和保护。

故障排除

对于 Linux 特定问题（尤其是 snap Chromium），参见 Browser troubleshooting。

Agent 工具 + 控制工作原理

agent 获得 一个工具 用于浏览器自动化：

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

映射方式：

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

这使 agent 保持确定性并避免脆弱的 selectors。

← 返回文档首页