浏览器（openclaw 托管）

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

入门视角：

把它理解为一个独立的、仅供代理使用的浏览器。
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

如果提示 “Browser disabled”，在配置中启用它（见下文）然后重启网关。

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

openclaw：托管的隔离浏览器（不需要扩展）。
chrome：到你系统浏览器的扩展中继（需要 OpenClaw 扩展附加到标签页上）。
existing-session：通过 Chrome MCP 附加到运行中的 Chrome 配置文件的官方流程。

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

配置

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

{
  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" },
      chromeLive: {
        cdpPort: 18802,
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

注意事项：

浏览器控制服务绑定到回环地址，端口由 gateway.port 推导（默认：18791，即网关端口 + 2）。中继使用下一个端口（18792）。
如果你覆盖了网关端口（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 时才需要手动设置。
driver: "existing-session" 使用 Chrome DevTools MCP 而非原始 CDP。该驱动不要设 cdpUrl。

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

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

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

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

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 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 账号匹配的区域端点（详见官方文档）。

直接 WebSocket CDP 提供商

部分托管浏览器服务暴露直接 WebSocket 端点，而非标准的基于 HTTP 的 CDP 发现（/json/version）。OpenClaw 两种都支持：

HTTP(S) 端点（如 Browserless）— OpenClaw 调用 /json/version 发现 WebSocket 调试器 URL，然后连接。
WebSocket 端点（ws:// / wss://）— OpenClaw 直接连接，跳过 /json/version。适用于 Browserbase 等提供 WebSocket URL 的服务。

Browserbase

Browserbase 是一个云平台，用于运行无头浏览器，内置验证码解决、隐身模式和住宅代理。

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

注意事项：

注册并从 Overview 面板复制你的 API Key。
把 <BROWSERBASE_API_KEY> 替换成你真实的 Browserbase API key。
Browserbase 在 WebSocket 连接时自动创建浏览器会话，无需手动创建步骤。
免费套餐允许一个并发会话和每月一小时浏览器时间。详见定价。
完整 API 参考、SDK 指南和集成示例见 Browserbase 文档。

安全性

核心要点：

浏览器控制仅限回环地址；访问通过网关认证或节点配对来控制。
如果浏览器控制已启用但没配置认证，OpenClaw 会在启动时自动生成 gateway.auth.token 并持久化到配置。
保持网关和节点主机在私有网络中（Tailscale）；避免公网暴露。
远程 CDP URL/token 视为敏感信息；优先使用环境变量或密钥管理器。

远程 CDP 建议：

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

配置文件（多浏览器）

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

openclaw 托管：一个专用的 Chromium 系浏览器实例，有自己的用户数据目录 + CDP 端口
远程：一个显式的 CDP URL（在别处运行的 Chromium 系浏览器）
扩展中继：通过本地中继 + Chrome 扩展控制你已有的 Chrome 标签页
现有会话：通过 Chrome DevTools MCP 自动连接到你已有的 Chrome 配置文件

默认值：

如果 openclaw 配置文件不存在会自动创建。
chrome 配置文件是内置的，用于 Chrome 扩展中继（默认指向 http://127.0.0.1:18792）。
现有会话配置文件是可选的；用 --driver existing-session 创建。
本地 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"。

设置

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

openclaw browser extension install

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

使用：

CLI：openclaw browser --browser-profile chrome tabs
代理工具：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。
再次点击扩展图标可以解除附加。

通过 MCP 附加 Chrome 现有会话

OpenClaw 也可以通过官方 Chrome DevTools MCP 服务器附加到运行中的 Chrome 配置文件。这会复用该 Chrome 配置文件中已打开的标签页和登录状态。

官方背景和设置参考：

创建配置文件：

openclaw browser create-profile \
  --name chrome-live \
  --driver existing-session \
  --color "#00AA00"

然后在 Chrome 中：

打开 chrome://inspect/#remote-debugging
启用远程调试
保持 Chrome 运行，OpenClaw 附加时批准连接提示

实时附加冒烟测试：

openclaw browser --browser-profile chrome-live start
openclaw browser --browser-profile chrome-live status
openclaw browser --browser-profile chrome-live tabs
openclaw browser --browser-profile chrome-live snapshot --format ai

成功的表现：

status 显示 driver: existing-session
status 显示 running: true
tabs 列出你已打开的 Chrome 标签页
snapshot 返回所选活跃标签页的 ref

附加不工作时检查：

Chrome 版本是 144+
已在 chrome://inspect/#remote-debugging 启用远程调试
Chrome 显示并且你已接受附加同意提示
网关或节点主机能启动 npx chrome-devtools-mcp@latest --autoConnect

注意事项：

这个路径比隔离的 openclaw 配置文件风险更高，因为它可以在你已登录的浏览器会话中操作。
OpenClaw 不会为这个驱动启动 Chrome；它只附加到已有会话。
OpenClaw 这里使用的是官方 Chrome DevTools MCP 的 --autoConnect 流程，不是旧版的默认配置文件远程调试端口工作流。
现有会话截图支持页面截图和从快照获得的 --ref 元素截图，但不支持 CSS --element 选择器。
现有会话的 wait --url 支持精确匹配、子串和 glob 模式，和其他浏览器驱动一样。wait --load networkidle 暂不支持。
部分功能仍需要扩展中继或托管浏览器路径，比如 PDF 导出和下载拦截。
默认让中继保持回环绑定。如果中继需要从不同网络命名空间可达（比如网关在 WSL2 中，Chrome 在 Windows 上），将 browser.relayBindHost 设为显式绑定地址如 0.0.0.0，同时保持周围网络私密且有认证。

WSL2 / 跨命名空间示例：

{
  browser: {
    enabled: true,
    relayBindHost: "0.0.0.0",
    defaultProfile: "chrome",
  },
}

隔离保证

专用用户数据目录：从不接触你的个人浏览器配置文件。
专用端口：避开 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
钩子：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>。

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

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

Playwright 要求

部分功能（navigate/act/AI 快照/role 快照、元素截图、PDF）需要 Playwright。如果没装 Playwright，这些端点会返回明确的 501 错误。对于 openclaw 托管的 Chrome，ARIA 快照和基本截图不需要 Playwright。对于 Chrome 扩展中继驱动，ARIA 快照和截图需要 Playwright。

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

Docker Playwright 安装

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

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 临时根目录下：
- 追踪：/tmp/openclaw（回退：${os.tmpdir()}/openclaw）
- 下载：/tmp/openclaw/downloads（回退：${os.tmpdir()}/openclaw/downloads）
上传路径限制在 OpenClaw 临时上传根目录下：
- 上传：/tmp/openclaw/uploads（回退：${os.tmpdir()}/openclaw/uploads）
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 时使用 efficient 快照（参见网关配置）。
- Role 快照选项（--interactive、--compact、--depth、--selector）强制使用带 ref=e12 格式 ref 的基于角色的快照。
- --frame "<iframe selector>" 将 role 快照限定在 iframe 内（配合 e12 格式的 role ref 使用）。
- --interactive 输出扁平的、易于选取的交互元素列表（最适合驱动操作）。
- --labels 添加一张带 ref 标签叠加层的视口截图（打印 MEDIA:<path>）。
click/type 等需要 snapshot 返回的 ref（数字 12 或 role ref e12）。操作有意不支持 CSS 选择器。

快照和 ref

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

AI 快照（数字 ref）：openclaw browser snapshot（默认；--format ai）
- 输出：包含数字 ref 的文本快照。
- 操作：openclaw browser click 12、openclaw browser type 23 "hello"。
- 内部通过 Playwright 的 aria-ref 解析 ref。
Role 快照（role ref 如 e12）：openclaw browser snapshot --interactive（或 --compact、--depth、--selector、--frame）
- 输出：带 [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
深度调试：录制追踪：
- 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

Role 快照的 JSON 输出包含 refs 加上一个小的 stats 块（lines/chars/refs/interactive），方便工具推理负载大小和密度。

状态和环境开关

这些适用于”让网站表现得像 X”的工作流：

Cookie：cookies、cookies set、cookies clear
存储：storage local|session get|set|clear
离线：set offline on|off
头部：set headers --headers-json '{"X-Debug":"1"}'（旧版 set headers --json '{"X-Debug":"1"}' 继续支持）
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 端点权限很大；做好隧道和保护。

严格模式示例（默认阻止私有/内部目标）：

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // 可选的精确允许
    },
  },
}

故障排除

Linux 特定问题（尤其是 snap Chromium），参见浏览器故障排除。

WSL2 网关 + Windows Chrome 分离主机配置，参见 WSL2 + Windows + 远程 Chrome CDP 故障排除。

代理工具 + 控制方式

代理得到一个工具用于浏览器自动化：

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）

直接 WebSocket CDP 提供商

Browserbase

安全性

配置文件（多浏览器）

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

沙箱化会话

设置

通过 MCP 附加 Chrome 现有会话

隔离保证

浏览器选择

控制 API（可选）

Playwright 要求

Docker Playwright 安装

工作原理（内部）

CLI 快速参考

快照和 ref

Wait 增强功能

调试工作流

JSON 输出

状态和环境开关

安全性和隐私

故障排除

代理工具 + 控制方式

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