浏览器控制 API

对于安装、配置和故障排查，请参阅浏览器。本页是本地控制 HTTP API、openclaw browser CLI 以及脚本模式（快照、引用、等待、调试流程）的参考。

控制 API（可选）¶

仅用于本地集成，Gateway 会暴露一个小型回环 HTTP API。这个独立服务器是可选启用的——在 gateway 服务环境中设置环境变量 OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1，并在 HTTP 端点可用之前重启 gateway。如果没有设置该变量，浏览器控制运行时仍可通过 CLI 和 agent 工具工作，但没有任何内容监听回环控制端口。

状态/启动/停止：GET /, GET /doctor, POST /start, POST /stop, POST /reset-profile
配置文件：GET /profiles, POST /profiles/create, DELETE /profiles/:name
标签页：GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId, POST /tabs/action
快照/截图/流：GET /snapshot, POST /screenshot, POST /screencast
操作：POST /navigate, POST /act
钩子：POST /hooks/file-chooser, POST /hooks/dialog
下载：POST /download, POST /wait/download
权限：POST /permissions/grant
调试：GET /console, GET /errors, GET /requests, GET /dialogs, POST /pdf, 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

POST /tabs/action 是 CLI 内部用于 browser tab 子命令的批量形式（{"action":"new"|"label"|"select"|"close"|"list", ...}）。直接编写脚本时，请优先使用上述单一用途的标签页路由。

所有端点都接受 ?profile=<name>。POST /start?headless=true 请求为本地托管配置文件执行一次性无头启动，而不更改持久化的浏览器配置。仅附加、远程 CDP 和现有会话配置文件会拒绝该覆盖，因为 OpenClaw 不会启动这些浏览器进程。

对于标签页端点，targetId 是兼容性字段名。建议传递来自 GET /tabs 或 POST /tabs/open 的 suggestedTargetId。标签和诸如 t1 的 tabId 句柄也被接受。原始 CDP target id 和唯一的原始 target-id 前缀仍然有效，但它们是易变的诊断句柄。标签页句柄的作用域限定于浏览器主机或节点以及配置文件。在发起后续请求时，请将该路由与句柄一起保留。

对于配置为 driver: "extension" 的配置文件，GET /tabs 和浏览器工具还可以返回 webExtensionTabId，即同一标签页的运行时作用域数字 Chrome WebExtensions 标签页 ID。对于其他驱动程序或在扩展元数据不可用时，会省略该字段。仅在调用 WebExtensions API 时使用它；对于 OpenClaw 浏览器操作，请继续使用 suggestedTargetId 或 tabId，因为 webExtensionTabId 可能在浏览器或扩展重新连接后发生变化。

Control UI 的 browser.request Gateway 方法接受 target: "host" 以固定 Gateway 主机，或接受 target: "node" 并配合 node: "<node-id>" 以固定浏览器节点。在 query.profile 中传递配置文件。显式路由不会回退到另一台主机。省略它们会保留已配置的自动路由。这些路由字段不会授予访问权限或更改浏览器策略。

浏览器预览需要一个来自 browser 工具且具有已知路由的结果。来自其他工具的浏览器形态元数据不会触发截图或更改面板选择。这些结果仍然是普通工具输出。

在标签页列表期间，如果 URL 验证失败，标签页会保留其身份和标题，但返回 url: "" 和 urlUnavailableReason：

navigation_blocked：导航规则拒绝了该地址。
navigation_check_failed：OpenClaw 无法验证该地址，例如因为 DNS 查找失败。刷新以再次检查。

仅空 URL 并不表示策略拒绝。导航策略错误也会携带 reason: "navigation_blocked"。原始被阻止的 URL 和 DNS 详情不包含在该元数据中。标签页列表是观察，而不是授权：后续每次内容读取或操作仍会执行其自身检查。

如果配置了共享密钥 gateway 身份验证，则浏览器 HTTP 路由也需要身份验证：

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

注意事项：

这个独立回环浏览器 API 不使用 trusted-proxy 或 Tailscale Serve 身份头。
如果 gateway.auth.mode 为 none 或 trusted-proxy，这些回环浏览器路由不会继承这些携带身份的模式。请保持它们仅限回环。

屏幕录制流¶

POST /screencast 为所选标签页的实时视图签发一次性令牌。在 JSON 请求体中传递可选的 targetId、maxWidth、maxHeight 和 quality。尺寸默认为 1280，并被限制为 320 到 2000 之间的整数。JPEG 质量默认为 70，并被限制在 30 到 90 之间。

响应包含 token、wsPath、expiresAtMs、targetId 和 url。将 wsPath 相对于 Gateway URL 解析，并在那里打开 WebSocket： /browser/screencast?token=<token>。48 位十六进制令牌在 60 秒后过期，且只能使用一次。无效、过期和重用的令牌会在升级前以 HTTP 401 拒绝。查看器不发送应用消息。二进制查看器消息会关闭连接。

通过 Gateway 签发的票据和查看器绑定到请求 Gateway 连接。结束该连接会吊销未使用的票据并关闭其查看器。已吊销（失效）连接会立即被隔离，在 Gateway 套接字完成关闭之前：其票据无法升级，其查看器不再接收帧或元数据。回环 HTTP 控制 API 没有可绑定的 Gateway 连接，因此其票据仍然仅基于 TTL。

插件为每个配置文件和标签页共享一个 CDP screencast。Chrome 在重绘时发送 JPEG 帧，节奏约为每秒 20 帧。较慢的查看器会跳过帧，而不是建立队列。导航会立即结束捕获会话。只有当地址被允许后，才会启动新的 CDP 会话，因此来自前一个文档的延迟帧无法进入新流。被拒绝的导航会停止流。

文本消息是 JSON，其中 type 为 ready、meta 或 error。ready 消息包含 targetId、url 和 title。meta 在允许的导航和页面加载后更新 url 和 title。二进制消息包含：

四字节无符号大端 JSON 头长度。
相应字节数的 UTF-8 JSON：{ "url", "cssWidth", "cssHeight", "scrollX", "scrollY", "ts" }。
JPEG 字节。

cssWidth 和 cssHeight 来自 CDP 的 deviceWidth 和 deviceHeight 元数据，并以 CSS 像素描述布局视口。scrollX 和 scrollY 来自 scrollOffsetX 和 scrollOffsetY。ts 是 CDP 帧时间戳。

关闭代码	含义
4001	Token 无效或已过期（通常在升级前以 HTTP 401 拒绝）
4003	`navigation_blocked`
4004	`target_closed`，包括配置文件生命周期变更
4005	不支持流式传输
4006	`authority_revoked`（请求的 Gateway 连接已结束或失效，例如设备 Token 被吊销）
1012	Gateway 正在关闭

Chrome MCP existing-session 配置文件和缺失 Playwright 会返回 HTTP 501，并带有 code: "SCREENCAST_UNSUPPORTED" 以及 reason: "existing-session" 或 "playwright"。 Node 路由的请求在代理前失败，返回 INVALID_REQUEST，详情为 { "code": "SCREENCAST_UNSUPPORTED", "reason": "node" }。当流式传输不可用时，Control UI 会回退到现有的截图路由。导航元数据会更新标签页和地址栏。显示的图像会保留其自身的 URL 和指标，直到替换帧到达。当 Annotate 或 Inspect 处于活动状态时，Control UI 会固定捕获的图像及其 URL，然后在捕获模式结束时显示最新保留的帧。

`/act` 错误契约¶

POST /act 对验证、策略以及已识别的交互失败使用结构化错误响应：

{ "error": "<message>", "code": "ACT_*" }

当前 code 值：

ACT_KIND_REQUIRED（HTTP 400）：kind 缺失或无法识别。
ACT_INVALID_REQUEST（HTTP 400）：操作载荷未通过规范化或验证。
ACT_SELECTOR_UNSUPPORTED（HTTP 400）：selector 与不支持的操作类型一起使用。
ACT_EVALUATE_DISABLED（HTTP 403）：evaluate（或 wait --fn）已被配置禁用。
ACT_TARGET_ID_MISMATCH（HTTP 403）：顶层或批量 targetId 与请求目标冲突。
ACT_OPERATION_FAILED（HTTP 500）：所选元素无法执行操作，例如不可编辑的输入框、被遮挡的控件或模糊的 ref。消息描述交互失败，而不将其视为浏览器连接中断。
ACT_EXISTING_SESSION_UNSUPPORTED（HTTP 501）：操作不支持 existing-session 配置文件。

其他运行时失败仍可能返回 { "error": "<message>" }，且没有 code 字段。

Playwright 要求¶

某些功能（navigate/act/AI snapshot/role snapshot、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回明确的 501 错误。

没有 Playwright 时仍然可用的功能：

ARIA 快照
当每个标签页的 CDP WebSocket 可用时，角色式可访问性快照（--interactive、--compact、 --depth、--efficient）。这是用于检查和 ref 发现的回退方案。Playwright 仍然是主要操作引擎。
当每个标签页的 CDP WebSocket 可用时，受管理的 openclaw 浏览器的页面截图
existing-session / Chrome MCP 配置文件的页面截图
来自快照输出的 existing-session 基于 ref 的截图（--ref）

仍然需要 Playwright 的功能：

navigate
act
依赖 Playwright 原生 AI 快照格式的 AI 快照
CSS 选择器元素截图（--element）
完整浏览器 PDF 导出

元素截图还会拒绝 --full-page。该路由返回 fullPage is not supported for element screenshots。

如果你看到 Playwright is not available in this gateway build，则打包的 Gateway 缺少核心浏览器运行时依赖项。请重新安装或更新 OpenClaw，然后重启 Gateway。对于 Docker，还需要按以下说明安装 Chromium 浏览器二进制文件。

Docker Playwright 安装¶

如果你的 Gateway 运行在 Docker 中，请避免使用 npx playwright（npm 覆盖冲突）。对于自定义镜像，请将 Chromium 烘焙到镜像中：

OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

浏览器还需要系统库，因此在一次性 Compose 容器中安装 Chromium 并不持久。请改为使用 OPENCLAW_INSTALL_BROWSER=1 重建镜像。要持久化浏览器下载和其他缓存，请使用 OPENCLAW_HOME_VOLUME 或绑定挂载持久化 /home/node。参见 Docker。

工作原理（内部）¶

一个小型回环控制服务器接受 HTTP 请求，并通过 CDP 连接到基于 Chromium 的浏览器。高级操作（click/type/snapshot/PDF）通过 CDP 之上的 Playwright 执行。当 Playwright 缺失时，只有非 Playwright 操作可用。代理看到一个稳定接口，而本地/远程浏览器和配置文件在底层自由切换。

CLI 快速参考¶

所有命令都接受 --browser-profile <name> 以指定特定配置文件，并接受 --json 以获取机器可读输出。

基础：状态、标签页、打开/聚焦/关闭

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep    # add a live snapshot probe
openclaw browser start
openclaw browser start --headless # one-shot local managed headless launch
openclaw browser stop            # also clears emulation on attach-only/remote CDP
openclaw browser reset-profile   # moves the profile's browser data to Trash
openclaw browser tabs
openclaw browser tab             # shortcut for current tab
openclaw browser tab new
openclaw browser tab new --label research
openclaw browser tab label abcd1234 research
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 profiles
openclaw browser create-profile --name research --color "#0066CC"
openclaw browser create-profile --name attach --driver existing-session --cdp-url http://127.0.0.1:9222
openclaw browser delete-profile --name research

检查：截图、快照、控制台、错误、请求

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12        # or --ref e12
openclaw browser screenshot --labels
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 --urls
openclaw browser snapshot --selector "#main" --interactive
openclaw browser snapshot --frame "iframe#main" --interactive
openclaw browser snapshot --out snapshot.txt
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           # or e12 for role refs
openclaw browser click-coords 120 340        # viewport coordinates
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 upload /tmp/openclaw/uploads/file.pdf --ref e12
openclaw browser upload media://inbound/file.pdf
openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser dialog --accept
openclaw browser dialog --dismiss --dialog-id d1
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 evaluate --fn 'const title = document.title; return title;'
openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
openclaw browser highlight e12
openclaw browser trace start
openclaw browser trace stop

状态：Cookie、存储、离线、请求头、地理位置、设备

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            # --clear to remove
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set media dark
openclaw browser set timezone America/New_York
openclaw browser set locale en-US
openclaw browser set device "iPhone 14"

说明：

面向代理的 browser 工具暴露 action=download（必需的 ref 和 path）以及 action=waitfordownload（可选 path）。两者都会返回已保存的下载 URL、建议的文件名和受保护的本地路径。对于受管理的 Playwright 配置文件，支持显式下载拦截。现有会话配置文件会返回不支持的操作错误。
优先使用原子文件选择器上传：在上传时传入触发器 --ref，以便 OpenClaw 在一次请求中完成准备和点击。仅路径的 upload 在有意稍后触发时仍然受支持。使用 --input-ref 或 --element 可直接设置文件输入。dialog 是一个准备调用。在触发对话框的点击/按键之前运行它。如果某个操作打开模态框，操作响应会包含 blockedByDialog 和 browserState.dialogs.pending。传入该 dialogId 以直接响应。在 OpenClaw 之外处理的对话框会显示在 browserState.dialogs.recent 下。
取消待处理的定位器点击、输入或上传操作会保持其他标签页连接。上传等待器属于所选标签页。该标签页上的新上传会替换其先前的等待器。
click/type/等需要来自 snapshot 的 ref（例如，Playwright 引用 f1e12、角色引用 e12 或可操作的 ARIA 引用 ax12）。原样复制返回的 ref，包括任何 frame 前缀。出于设计考虑，操作不支持 CSS 选择器。当可见视口位置是唯一可靠目标时，请使用 click-coords。
下载和跟踪路径受限于 OpenClaw 临时根目录：/tmp/openclaw{,/downloads}（回退：${os.tmpdir()}/openclaw/...）。
upload 接受来自 OpenClaw 临时上传根目录和 OpenClaw 管理的入站媒体的文件。受管理的入站媒体可以引用为 media://inbound/<id>、沙箱相对路径 media/inbound/<id>，或受管理的入站媒体目录内已解析的路径。嵌套媒体引用、路径遍历、符号链接、硬链接和任意本地路径仍会被拒绝。
upload 还可以通过 --input-ref 或 --element 直接设置文件输入；这些操作遵循上传超时。
对话框提示文本会精确保留空白和空字符串。读取所有本地或会话存储会保留空键以及诸如 __proto__ 之类的键。

Stable tab ids and labels survive Chromium raw-target replacement when OpenClaw can prove the replacement tab, such as a unique old/new pair for the same URL or a single old tab becoming a single new tab after form submission. Ambiguous duplicate-URL replacements receive fresh handles. Raw target ids are still volatile. Prefer suggestedTargetId from tabs in scripts.

快照参数一览：

--format ai（Playwright 下的默认值）：AI 快照，使用 Playwright 原生引用，包括带 frame 限定的引用，例如 f1e12。
--format aria：带有 axN 引用的可访问性树。当 Playwright 可用时，OpenClaw 会将带有后端 DOM ID 的引用绑定到实时页面。后续操作即可使用它们。否则请将输出视为仅用于检查。
--efficient（或 --mode efficient）：紧凑角色快照预设。设置 browser.snapshotDefaults.mode: "efficient" 可将其设为默认值（参见网关配置）。
--interactive、--compact、--depth、--selector 会强制使用带有 ref=e12 引用的角色快照。--frame "<iframe>" 将角色快照限定到某个 iframe。
选择器限定和 frame 限定的角色引用会绑定到捕获的 DOM 控件，包括 shadow DOM 和外部 aria-owns 成员。重新排序控件不会重新指向这些引用。控件被移除或绑定失败时，需要重新生成快照，而不是按名称匹配另一个控件。
在限定范围的角色快照中，被忽略的节点和未命名的通用包装器在深度过滤之前是透明的。深度从所选根节点开始计算剩余的角色节点；包装器行和引用编号可能与旧快照不同。状态属性、URL 附录和输出限制仍然适用。
选择器限定的快照是一次时间点观察。如果请求时没有元素匹配，它会立即返回空快照。它不会等待快照超时。当页面预计稍后会添加该元素时，请使用 openclaw browser wait "<selector>"。
--selector 不会改变页面级或 frame 限定传输失败的行为。这些情况仍会使用配置的快照超时和诊断信息。
使用 Playwright 时，--labels 会添加带有叠加引用标签的截图（打印 MEDIA:<path>），并附带一个 annotations 数组，包含每个引用的边界框。对于 screenshot，基于 Playwright 的标签可与 --full-page、 --ref 和 --element 一起使用。对于 snapshot，随附的截图仍仅限视口。现有会话/chrome-mcp 配置文件会在页面截图上渲染叠加标签，但不会返回 annotations，也不会使用 Playwright 的 full-page/ref/element 投影辅助功能。如果没有 Playwright 或 chrome-mcp，则无法使用带标签的截图。
--urls 会将发现的链接目标追加到 AI 快照中。

快照与引用¶

OpenClaw 支持三种“快照”样式：

AI 快照（原生引用）：openclaw browser snapshot（默认，--format ai）
输出：带有 f1e12 等引用以及对应 refs 元数据的文本快照。
操作：openclaw browser click f1e12、openclaw browser type f1e23 "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()）。
包含引号、反斜杠或 YAML 标点符号的名称仍然可操作。请使用引用，而不是根据显示名称重建定位器。
缺少显示名称可能意味着可访问名称为空，或超过 Playwright 的 900 个 UTF-16 单元限制。请继续使用返回的引用。
添加 --labels 以包含带有叠加 e12 标签的截图。在基于 Playwright 的配置文件中，这还会返回每个引用的边界框元数据（annotations[]）。带标签的元素截图会保留产生它的快照中的引用和 frame。
当链接文本存在歧义且智能体需要具体导航目标时，添加 --urls。使用 --frame 时，URL 附录来自该 frame。
ARIA 快照（类似 ax12 的 ARIA 引用）：openclaw browser snapshot --format aria
输出：以结构化节点表示的可访问性树。
操作：当快照路径能够通过 Playwright 和 Chrome 后端 DOM ID 绑定引用时，openclaw browser click ax12 可用。
如果 Playwright 不可用，ARIA 快照仍可用于检查，但引用可能不可操作。需要操作引用时，请使用 --format ai 或 --interactive 重新生成快照。
当驱动程序暴露稳定的文档标识时，针对同一配置文件、标签页、文档和选项族的连续 AI 快照和角色快照会为前一个快照中不存在的带引用行追加 [new]。导航会开始一个新的未标记基线，包括当快照包含该 frame 时同一 URL 的 iframe 重新加载。现有会话快照会省略差异。第一个快照建立无标记的基线。后续响应还会暴露 newElements，并在值非零时添加计数页脚。带有 axN 引用的结构化 --format aria 快照不使用差异标记。
贡献者：raw-CDP 回退路径有一个 Docker 证明通道，描述见 Docker 测试套件。

引用行为：

引用在导航之间不稳定。如果某项操作失败，请重新运行 snapshot 并使用新的引用。
批次会在已提交的主 frame 导航（包括同一 URL 重新加载）之后或页面关闭之后停止。其 aborted 摘要会报告操作编号和跳过计数。在发出依赖操作之前，请获取新的快照；或者在预期会发生导航时使用单独的 act 调用。
当能够证明替换后的标签页时，/act 会在操作触发的替换后返回当前原始 targetId。后续命令请继续使用稳定的标签页 ID/标签。
使用 --frame 获取的角色快照会将角色引用限定到该 iframe，直到下一次角色快照。
未知或过期的 axN 引用会快速失败，而不是回退到 Playwright 的 aria-ref 选择器。发生这种情况时，请在同一标签页上运行新的快照。

浏览器批量 CLI¶

openclaw browser batch 在一次 /act 调用中运行一组嵌套的 /act 操作（与通过 agent 工具访问的同一 kind="batch" 运行时相同），因此 CLI 用户和脚本可以将 wait、click、type 和 evaluate 等操作组合成一个可重放的计划，而无需为每个操作进行往返。actions[] 中的每个条目都是 BrowserActRequest —— /act 路由接受的封闭联合类型（click、clickCoords、type、press、hover、scrollIntoView、drag、select、fill、resize、wait、evaluate、close、batch）——而不是任意 openclaw browser 子命令。batch 不支持 profile="user" 以及其他现有会话（chrome-mcp）配置文件。在这些配置文件中，请单独发送操作。

CLI：openclaw browser batch --actions '<json>'、openclaw browser batch --actions-file plan.json，或 openclaw browser batch --actions-file - 以从 stdin 读取 JSON 数组。--continue 设置 stopOnError=false。默认在第一个错误处停止。--target-id 将整个批处理限定到一个标签页。--actions-file 和 stdin 输入的上限为 1,000,000 字节。请将更大的计划拆分为多个 batch 命令。
Ref 生命周期：refs 来自批处理之前运行的 snapshot（snapshot 不是嵌套操作）。改变页面状态的嵌套操作——例如触发导航的 click，或修改 DOM 的 evaluate——可能会使批处理剩余部分中较早的 refs 失效。请将改变状态的操作放在前面，或在重新快照后拆分为后续批处理。导航和重新快照发生在批处理之外（openclaw browser navigate / snapshot），因为 open、navigate 和 snapshot 不是 /act 类型。
目标 ID 冲突：嵌套操作可以省略 targetId，或重复请求级别的 targetId。如果显式的嵌套 targetId 解析到不同的标签页，则会在任何操作运行前以 ACT_TARGET_ID_MISMATCH 拒绝。按设计，批处理操作共享请求的标签页。
错误摘要：响应为 { "results": [{ "ok": true }, { "ok": false, "error": "<message>" }, ...] }，按顺序每个操作一个条目。当 stopOnError 为默认值时，数组在第一个失败处结束。使用 --continue 时，它覆盖每个操作。任何失败条目都会使 CLI 以非零状态退出。传入 --json 可为脚本保留完整的有序响应。
嵌套批处理占用一个父结果。如果子操作失败，该结果会报告第一个子错误。每个批处理应用自己的 stopOnError：在嵌套批处理内部继续不会使其成功，也不会使其父级继续。

等待增强¶

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

等待 URL（支持 Playwright 的 globs）：
openclaw browser wait --url "**/dash"
等待加载状态：
openclaw browser wait --load networkidle
支持受管理的 openclaw 和 raw/remote CDP 配置文件。使用 existing-session 驱动程序的配置文件（包括默认 user 配置文件）会拒绝 networkidle。在那里请使用 --url、--text、选择器或 --fn 等待。
等待 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>（在交互模式下优先使用 role refs）
如果仍然失败：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 --json status
openclaw browser --json snapshot --interactive
openclaw browser --json requests --filter api
openclaw browser --json cookies

JSON 中的 role 快照包含 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 '{"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。Prompt injection 可以引导此行为。如果不需要，请使用 browser.evaluateEnabled=false 禁用它。
openclaw browser evaluate --fn 接受函数源代码、表达式或语句主体。语句主体会被包装为 async 函数，因此请使用 return 返回你想要的值。当页面端函数可能需要比默认 evaluate 超时更长时间时，请使用 --timeout-ms <ms>。
有关登录和反机器人说明（X/Twitter 等），请参阅 Browser login + X/Twitter posting。
保持 Gateway/node 主机私有（仅限 loopback 或 tailnet）。
远程 CDP 端点功能强大。请通过隧道访问并保护它们。

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

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      allowedHostnames: ["*.example.com", "example.com", "localhost"],
    },
  },
}

浏览器 - 概览、配置、配置文件、安全
浏览器登录 - 登录网站
浏览器 Linux 故障排查
浏览器 WSL2 故障排查

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw