OpenClaw从入门到应用——工具（Tools）：浏览器工具-洪萨配资

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》

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

初学者视角：

可将其视为一个独立的、仅限代理使用的浏览器。
openclaw配置文件不会触碰您的个人浏览器配置文件。
代理可以在安全通道中打开标签页、读取页面、点击和输入。
内置的user配置文件会附加到您真实的已登录 Chrome 会话；
chrome-relay是显式的扩展中继配置文件。

您将获得的功能

一个名为openclaw的独立浏览器配置文件（默认为橙色强调色）。
确定性的标签页控制（列出/打开/聚焦/关闭）。
代理操作（点击/输入/拖拽/选择）、快照、截图、PDF 导出。
可选的多配置文件支持（openclaw、work、remote等）。

此浏览器不是您的日常使用浏览器。它是一个安全、隔离的表面，专用于代理自动化和验证。

快速入门

openclaw browser --browser-profile openclaw status openclaw browser --browser-profile openclaw start openclaw browser --browser-profile openclawopenhttps://example.com openclaw browser --browser-profile openclaw snapshot

如果收到“Browser disabled”（浏览器已禁用）提示，请在配置中启用它（见下文）并重启 Gateway。

配置文件：`openclaw`与`user`与`chrome-relay`

openclaw：受管理的隔离浏览器（无需扩展）。
user：内置的 Chrome MCP 附加配置文件，用于您的真实已登录 Chrome会话。
chrome-relay：扩展中继到您的系统浏览器（需要 OpenClaw 扩展附加到标签页）。

对于代理浏览器工具调用：

默认：使用隔离的openclaw浏览器。
当现有登录会话很重要且用户在计算机前可点击/批准任何附加提示时，优先使用profile="user"。
仅当用户明确希望使用 Chrome 扩展/工具栏按钮附加流程时，才使用profile="chrome-relay"。
profile是显式覆盖，当您想要特定浏览器模式时使用。

如果希望默认使用受管理模式，请设置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: "openclaw", 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" }, user: { driver: "existing-session", attachOnly: true, color: "#00AA00", }, "chrome-relay": { driver: "extension", cdpUrl: "http://127.0.0.1:18792", color: "#00AA00", }, 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: "user"可选择已登录用户浏览器，或使用defaultProfile: "chrome-relay"选择扩展中继。
自动检测顺序：如果系统默认浏览器基于 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 configsetbrowser.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 启动回环控制服务并可启动本地浏览器。
远程控制（节点主机）：在拥有浏览器的机器上运行节点主机；Gateway 将浏览器操作代理到该主机。
远程 CDP：设置browser.profiles..cdpUrl（或browser.cdpUrl）以附加到远程基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。

远程 CDP URL 可包含认证：

查询令牌（例如，https://provider.example?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 密钥进行认证。

示例：

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

注意事项：

将 `` 替换为您的真实 Browserless 令牌。
选择与您的 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 是一个云平台，用于运行无头浏览器，内置 CAPTCHA 解决、隐身模式和住宅代理。

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

注意事项：

注册并从概览仪表板复制您的API 密钥。
将 `` 替换为您的真实 Browserbase API 密钥。
Browserbase 在 WebSocket 连接时自动创建浏览器会话，因此无需手动创建会话步骤。
免费套餐允许每月一个并发会话和一个浏览器小时。付费计划限制请参见定价。
完整 API 参考、SDK 指南和集成示例请参见 Browserbase 文档。

安全

关键理念：

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

远程 CDP 提示：

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

配置文件（多浏览器）

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

openclaw-managed：具有自己用户数据目录和 CDP 端口的专用基于 Chromium 的浏览器实例
remote：显式的 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
extension relay：通过本地中继 + Chrome 扩展使用您现有的 Chrome 标签页
existing session：通过 Chrome DevTools MCP 自动连接使用您现有的 Chrome 配置文件

默认设置：

如果缺失，openclaw配置文件会自动创建。
chrome-relay配置文件内置用于 Chrome 扩展中继（默认指向http://127.0.0.1:18792）。
现有会话配置文件需要手动启用；使用--driver existing-session创建它们。
本地 CDP 端口默认从18800–18899分配。
删除配置文件会将其本地数据目录移至回收站。

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

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

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

完整指南：Chrome 扩展

流程：

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

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

沙盒会话

如果代理会话被沙盒化，browser工具可能默认使用target="sandbox"（沙盒浏览器）。
Chrome 扩展中继接管需要主机浏览器控制，因此要么：

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

设置

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

openclaw browser extensioninstall

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

使用它：

CLI：openclaw browser --browser-profile chrome-relay tabs
代理工具：browser配合profile="chrome-relay"

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

openclaw browser create-profile\--namemy-chrome\--driverextension\--cdp-url http://127.0.0.1:18792\--color"#00AA00"

注意事项：

此模式依赖 Playwright-on-CDP 进行大多数操作（截图/快照/操作）。
再次点击扩展图标即可分离。
代理使用：对于已登录网站，优先使用profile="user"。仅当您明确需要扩展流程时才使用profile="chrome-relay"。用户必须在场点击扩展并附加标签页。

通过 MCP 的 Chrome 现有会话

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

官方背景和设置参考：

Chrome for Developers：使用 Chrome DevTools MCP 与您的浏览器会话
Chrome DevTools MCP README

内置配置文件：

user

可选：如果您想要不同的名称或颜色，可以创建自己的自定义现有会话配置文件。

然后在 Chrome 中：

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

实时附加冒烟测试：

openclaw browser --browser-profile user start openclaw browser --browser-profile user status openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot--formatai

成功的表现：

status显示driver: existing-session
status显示transport: chrome-mcp
status显示running: true
tabs列出您已打开的 Chrome 标签页
snapshot从选定的活动标签页返回引用

如果附加不工作，请检查：

Chrome 版本为144+
在chrome://inspect/#remote-debugging启用了远程调试
Chrome 显示了附加同意提示并已被接受

代理使用：

当需要用户的已登录浏览器状态时，使用profile="user"。
如果使用自定义现有会话配置文件，请传递该显式配置文件名称。
除非用户明确需要扩展/附加标签页流程，否则优先使用profile="user"而非profile="chrome-relay"。
仅当用户在计算机前可批准附加提示时才选择此模式。
Gateway 或节点主机可以生成npx chrome-devtools-mcp@latest --autoConnect

注意事项：

此路径比隔离的openclaw配置文件风险更高，因为它可以在您的已登录浏览器会话中操作。
OpenClaw 不会为此驱动程序启动 Chrome；它仅附加到现有会话。
OpenClaw 在此处使用官方的 Chrome DevTools MCP--autoConnect流程，而非旧版默认配置文件远程调试端口工作流。
现有会话截图支持页面捕获和来自快照的--ref元素捕获，但不支持 CSS--element选择器。
现有会话wait --url支持精确、子字符串和 glob 模式，如同其他浏览器驱动程序。wait --load networkidle尚不支持。
某些功能仍需要扩展中继或受管理浏览器路径，例如 PDF 导出和下载拦截。
默认保持中继仅限回环。如果中继必须从不同的网络命名空间可达（例如 Gateway 在 WSL2 中，Chrome 在 Windows 上），请将browser.relayBindHost设置为显式绑定地址（如0.0.0.0），同时保持周围网络安全和认证。

WSL2 / 跨命名空间示例：

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

隔离保证

专用用户数据目录：绝不会触碰您的个人浏览器配置文件。
专用端口：避免使用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=。

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

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

Playwright 要求

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

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

Docker Playwright 安装

如果您的 Gateway 在 Docker 中运行，请避免使用npx playwright（npm 覆盖冲突）。
改用捆绑的 CLI：

dockercompose run--rmopenclaw-cli\node/app/node_modules/playwright-core/cli.jsinstallchromium

要持久化浏览器下载，请设置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以针对特定配置文件。
所有命令也接受--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 时的默认值）：返回带有数字引用的 AI 快照（aria-ref=""）。
- --format aria：返回无障碍树（无引用；仅用于检查）。
- --efficient（或--mode efficient）：紧凑的角色快照预设（交互式 + 紧凑 + 深度 + 较低的 maxChars）。
- 配置默认值（仅限工具/CLI）：设置browser.snapshotDefaults.mode: "efficient"以在调用方未传递模式时使用高效快照（参见 Gateway 配置）。
- 角色快照选项（--interactive、--compact、--depth、--selector）强制使用类似ref=e12的引用进行基于角色的快照。
- --frame ""将角色快照限定在 iframe 内（与类似e12的角色引用配对）。
- --interactive输出一个扁平、易于选择的交互元素列表（最适合驱动操作）。
- --labels添加一个带有叠加引用标签的视口截图（打印MEDIA:<path>）。
click/type/等需要来自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 支持 glob）：
- openclaw browser wait --url "**/dash"
等待加载状态：
- openclaw browser wait --load networkidle
等待 JS 谓词：
- openclaw browser wait --fn "window.ready===true"
等待选择器变为可见：
- openclaw browser wait "#main"

这些可以组合：

openclaw browserwait"#main"\--url"**/dash"\--loadnetworkidle\--fn"window.ready===true"\--timeout-ms15000

调试工作流

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

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用于脚本和结构化工具。

示例：

openclaw browser status--jsonopenclaw browser snapshot--interactive--jsonopenclaw browser requests--filterapi--jsonopenclaw browser cookies--json

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

状态和环境调节

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

Cookies：cookies、cookies set、cookies clear
存储：storage local|session get|set|clear
离线：set offline on|off
Headers：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 发布。
保持 Gateway/节点主机私有（仅限回环或 tailnet）。
远程 CDP 端点功能强大；请对其进行隧道保护。

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

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

故障排除

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

对于 WSL2 Gateway + Windows Chrome 分离主机设置，请参见
WSL2 + Windows + 远程 Chrome CDP 故障排除。

代理工具 + 控制工作原理

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

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

映射方式：

browser snapshot返回稳定的 UI 树（AI 或 ARIA）。
browser act使用快照refID 进行点击/输入/拖拽/选择。
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从入门到应用——工具（Tools）：浏览器工具

您将获得的功能

快速入门

配置文件：`openclaw`与`user`与`chrome-relay`

配置

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

本地 vs 远程控制

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

Browserless（托管远程 CDP）

直接 WebSocket CDP 提供商

Browserbase

安全

配置文件（多浏览器）

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

沙盒会话

设置

通过 MCP 的 Chrome 现有会话

隔离保证

浏览器选择

控制 API（可选）

Playwright 要求

Docker Playwright 安装

工作原理（内部）

CLI 快速参考

快照和引用

等待增强功能

调试工作流

JSON 输出

状态和环境调节

安全与隐私

故障排除

代理工具 + 控制工作原理

LookScanned.io：浏览器中的终极PDF扫描效果生成器

如何在Windows资源管理器中一键显示iPhone照片缩略图

终极Windows和Office激活解决方案：告别许可证烦恼的完整指南

如何一键激活Windows和Office？KMS_VL_ALL_AIO智能激活脚本完全指南

3分钟搞定百度网盘提取码：开源工具的完整使用指南

中小企业如何利用Taotoken构建低成本AI应用原型

您将获得的功能

快速入门

配置文件：openclaw与user与chrome-relay

配置

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

本地 vs 远程控制

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

Browserless（托管远程 CDP）

直接 WebSocket CDP 提供商

Browserbase

安全

配置文件（多浏览器）

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

沙盒会话

设置

通过 MCP 的 Chrome 现有会话

隔离保证

浏览器选择

控制 API（可选）

Playwright 要求

Docker Playwright 安装

工作原理（内部）

CLI 快速参考

快照和引用

等待增强功能

调试工作流

JSON 输出

状态和环境调节

安全与隐私

故障排除

代理工具 + 控制工作原理

LookScanned.io：浏览器中的终极PDF扫描效果生成器

如何在Windows资源管理器中一键显示iPhone照片缩略图

终极Windows和Office激活解决方案：告别许可证烦恼的完整指南

如何一键激活Windows和Office？KMS_VL_ALL_AIO智能激活脚本完全指南

3分钟搞定百度网盘提取码：开源工具的完整使用指南

中小企业如何利用Taotoken构建低成本AI应用原型

配置文件：`openclaw`与`user`与`chrome-relay`