Browser（OpenClaw 托管）

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

新手视角：

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

你能得到什么

一个名为 openclaw 的独立浏览器配置文件（默认橙色主题）。
确定性的标签页控制（列表/打开/聚焦/关闭）。
Agent 操作（点击/输入/拖拽/选择）、快照、截图、PDF。
可选的多配置文件支持（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。

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

openclaw：托管的、隔离的浏览器（不需要扩展）。
chrome：通过扩展中继连接到你的 系统浏览器（需要在标签页上附加 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" },
    },
  },
}

注意事项：

浏览器控制服务绑定到 loopback，端口从 gateway.port 派生（默认：18791，即 gateway + 2）。中继使用下一个端口（18792）。
如果你覆盖了 Gateway 端口（gateway.port 或 OPENCLAW_GATEWAY_PORT），派生的浏览器端口会相应调整，保持在同一”家族”中。
cdpUrl 未设置时默认为中继端口。
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 可以包含认证信息：

查询 token（例如：https://provider.example?token=<token>）
HTTP Basic 认证（例如：https://user:[email protected]）

OpenClaw 在调用 /json/* 端点和连接到 CDP WebSocket 时会保留认证信息。建议使用环境变量或密钥管理器来存储 token，而不是直接提交到配置文件中。

Node browser proxy（零配置默认）

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

注意事项：

node host 通过 proxy 命令 暴露其本地浏览器控制服务器。
配置文件来自 node 自己的 browser.profiles 配置（与本地相同）。
如果不想要这个功能，可以禁用：
- 在 node 上：nodeHost.browserProxy.enabled=false
- 在 gateway 上：gateway.nodes.browser.mode="off"

Browserless（托管的远程 CDP）

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

示例：

{
  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 host 保持在私有网络上（Tailscale）；避免公开暴露。
将远程 CDP URL/token 视为密钥；优先使用环境变量或密钥管理器。

远程 CDP 提示：

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

Profiles（多浏览器）

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

openclaw 托管：一个专用的基于 Chromium 的浏览器实例，有自己的用户数据目录 + CDP 端口
remote：一个明确的 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
extension 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 中继 + Chrome 扩展来驱动 你现有的 Chrome 标签页（不需要单独的 “openclaw” Chrome 实例）。

完整指南：Chrome extension

流程：

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

如果 Gateway 在其他地方运行，在浏览器机器上运行 node host，这样 Gateway 可以代理浏览器操作。

Sandboxed sessions

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

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

设置

加载扩展（dev/unpacked）：

openclaw browser extension install

Chrome → chrome://extensions → 启用 “Developer mode”
“Load unpacked” → 选择 openclaw browser extension path 打印的目录
固定扩展，然后在你想控制的标签页上点击它（徽章显示 ON）。

使用它：

CLI：openclaw browser --browser-profile chrome tabs
Agent 工具：browser 带 profile="chrome"

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

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：检查常见安装位置。

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）。
对于高级操作（点击/输入/快照/PDF），它在 CDP 之上使用 Playwright。
当 Playwright 缺失时，只有非 Playwright 操作可用。

这种设计让 Agent 保持在一个稳定、确定性的接口上，同时让你可以切换本地/远程浏览器和配置文件。

CLI 快速参考

所有命令接受 --browser-profile <name> 来指定特定配置文件。所有命令也接受 --json 用于机器可读输出（稳定的 payload）。

基础操作：

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 安装时的默认值）：返回带数字 ref 的 AI 快照（aria-ref="<n>"）。
- --format aria：返回可访问性树（无 ref；仅用于检查）。
- --efficient（或 --mode efficient）：紧凑的 role 快照预设（interactive + compact + depth + 更低的 maxChars）。
- 配置默认值（仅工具/CLI）：设置 browser.snapshotDefaults.mode: "efficient" 可在调用者未传递 mode 时使用高效快照（参见 Gateway configuration）。
- Role 快照选项（--interactive、--compact、--depth、--selector）强制使用基于 role 的快照，ref 格式为 ref=e12。
- --frame "<iframe selector>" 将 role 快照限定到 iframe（与 role ref 如 e12 配对）。
- --interactive 输出一个扁平的、易于选择的交互元素列表（最适合驱动操作）。
- --labels 添加一个仅视口的截图，带有叠加的 ref 标签（打印 MEDIA:<path>）。
click/type 等需要来自 snapshot 的 ref（数字 12 或 role ref e12）。故意不支持 CSS 选择器用于操作。

Snapshots 和 refs

OpenClaw 支持两种”快照”风格：

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

Ref 行为：

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

Wait 增强功能

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

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

这些可以组合使用：

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

调试工作流

当操作失败时（例如 “not visible”、“strict mode violation”、“covered”）：

openclaw browser snapshot --interactive
使用 click <ref> / type <ref>（在 interactive 模式下优先使用 role ref）
如果仍然失败：openclaw browser highlight <ref> 查看 Playwright 定位的是什么
如果页面行为异常：
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
深度调试：记录 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 认证：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 浏览器配置文件可能包含已登录的 session；将其视为敏感信息。
browser act kind=evaluate / openclaw browser evaluate 和 wait --fn 在页面上下文中执行任意 JavaScript。Prompt 注入可以操纵这个。如果不需要，用 browser.evaluateEnabled=false 禁用它。
关于登录和反机器人注意事项（X/Twitter 等），参见 Browser login + X/Twitter posting。
保持 Gateway/node host 私有（loopback 或仅 tailnet）。
远程 CDP 端点很强大；用隧道保护它们。

故障排除

关于 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 ID 来 click/type/drag/select。
browser screenshot 捕获像素（整页或元素）。
browser 接受：
- profile 选择命名的浏览器配置文件（openclaw、chrome 或远程 CDP）。
- target（sandbox | host | node）选择浏览器所在位置。
- 在沙箱化 session 中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
- 如果省略 target：沙箱化 session 默认为 sandbox，非沙箱 session 默认为 host。
- 如果连接了支持浏览器的 node，工具可能会自动路由到它，除非你固定 target="host" 或 target="node"。

这让 Agent 保持确定性，避免脆弱的选择器。

Browser（OpenClaw 托管）

你能得到什么

快速开始

配置文件：openclaw vs chrome

配置

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

本地 vs 远程控制

Node browser proxy（零配置默认）

Browserless（托管的远程 CDP）

安全

Profiles（多浏览器）

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

Sandboxed sessions

设置

隔离保证

浏览器选择

Control API（可选）

Playwright 要求

工作原理（内部）

CLI 快速参考

Snapshots 和 refs

Wait 增强功能

调试工作流

JSON 输出

状态和环境设置

安全与隐私

故障排除

Agent 工具 + 控制工作原理

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