浏览器控制 API
有关设置、配置和故障排除,请参阅 Browser。
本页是本地控制 HTTP API、openclaw browser
CLI 以及脚本模式(快照、引用、等待、调试流程)的参考。
控制 API(可选)¶
仅用于本地集成,Gateway 会暴露一个小型回环 HTTP API。
此独立服务器为可选启用——请在 Gateway 服务环境中设置环境变量
OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1,并在 HTTP 端点可用之前重启
Gateway。如果没有此变量,浏览器控制运行时仍可通过 CLI 和代理工具工作,
但没有任何内容监听回环控制端口。
- 状态/启动/停止:
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。对于其他 driver 或扩展元数据不可用时,会省略此字段。
仅在调用 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 为所选标签页的实时视图签发一次性 token。
在 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 位十六进制 token 在 60 秒后过期,
且只能使用一次。无效、过期和重复使用的 token 会在升级前以 HTTP 401 拒绝。
查看器不发送应用消息。二进制查看器消息会关闭连接。
通过 Gateway 签发的票据和查看器绑定到发起请求的 Gateway 连接。 结束该连接会吊销未使用的票据并关闭其查看器。已吊销(失效)的连接会立即被 隔离,早于 Gateway 套接字完成关闭:它们的票据无法升级,它们的查看器不会 收到更多帧或元数据。回环 HTTP 控制 API 没有可绑定的 Gateway 连接, 因此其票据仍然仅基于 TTL。
该插件为每个配置文件和标签页共享一个 CDP 屏幕录制。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 对验证、策略以及已识别的交互失败使用结构化错误响应:
当前 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 快照/角色快照、元素截图、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 的功能:
navigateact- 依赖 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 烘焙到镜像中:
浏览器还需要系统库,因此在一性 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 check
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 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 reff1e12、role refe12,或可操作的 ARIA refax12)。原样复制返回的 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__之类的键。
当 OpenClaw 能够证明替换标签页时,稳定的标签页 ID 和标签会在 Chromium 原始目标替换中保留下来,例如同一 URL 的唯一旧/新标签页对,或表单提交后单个旧标签页变为单个新标签页。存在歧义的重复 URL 替换会获得新的句柄。原始目标 ID 仍然易变。在脚本中优先使用来自 tabs 的 suggestedTargetId。
快照标志一览:
--format ai(使用 Playwright 时的默认值):AI 快照,包含原生 Playwright 引用,包括带框架限定的引用,例如f1e12。--format aria:带有axN引用的可访问性树。当 Playwright 可用时,OpenClaw 会将具有后端 DOM ID 的引用绑定到实时页面。后续操作即可使用它们。否则,请将输出视为仅用于检查。--efficient(或--mode efficient):紧凑角色快照预设。设置browser.snapshotDefaults.mode: "efficient"可将其设为默认值(参见 网关配置)。--interactive、--compact、--depth、--selector会强制使用带有ref=e12引用的角色快照。--frame "<iframe>"将角色快照限定到某个 iframe。- 选择器限定和框架限定的角色引用会绑定到已捕获的 DOM 控件,包括 shadow DOM 和外部
aria-owns成员。重新排序控件不会重新定位这些引用。控件被移除或绑定失败时,需要重新生成快照,而不是按名称匹配另一个控件。 - 在限定作用域的角色快照中,被忽略的节点和未命名的通用包装器在深度过滤之前是透明的。深度从所选根节点开始统计剩余的角色节点;包装器行和引用编号可能与旧快照不同。状态属性、URL 附录和输出限制仍然适用。
- 选择器限定的快照是一次时间点观察。如果请求时没有元素匹配,它会立即返回空快照。它不会等待快照超时。当预期页面稍后会添加该元素时,请使用
openclaw browser wait "<selector>"。 --selector不会改变页面范围或框架限定的传输失败的行为。这些失败仍会使用配置的快照超时和诊断信息。- 使用 Playwright 时,
--labels会添加一张叠加引用标签的截图 (打印MEDIA:<path>),并附带一个annotations数组,包含每个引用的边界 框。在screenshot中,基于 Playwright 的标签支持--full-page、--ref和--element。在snapshot中,附带的截图仍仅限视口。现有会话/chrome-mcp 配置文件会在页面截图上渲染叠加标签,但不会返回annotations,也不会使用 Playwright 的全页/引用/元素投影辅助函数。如果没有 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[])。带标签的元素截图会保留生成它的快照中的引用和框架。 -
当链接文本存在歧义且代理需要具体导航目标时,添加
--urls。使用--frame时,URL 附录来自该框架。 -
ARIA 快照(类似
ax12的 ARIA 引用):openclaw browser snapshot --format aria - 输出:以结构化节点表示的可访问性树。
- 操作:当快照路径能够通过 Playwright 和 Chrome 后端 DOM ID 绑定引用时,
openclaw browser click ax12可用。 - 如果 Playwright 不可用,ARIA 快照仍可用于检查,但引用可能不可操作。当需要操作引用时,请使用
--format ai或--interactive重新生成快照。 - 当驱动程序暴露稳定的文档标识时,针对同一配置文件、标签页、文档和选项族的连续 AI 快照和角色快照会为前一个快照中不存在的带引用行追加
[new]。导航会开始一个新的未标记基线,包括当快照包含该框架时同一 URL 的 iframe 重新加载。现有会话快照会省略差异。第一个快照建立不带标记的基线。后续响应还会暴露newElements,并在值非零时添加计数页脚。带有axN引用的结构化--format aria快照不使用差异标记。 - 贡献者:原始 CDP 回退路径有一个 Docker 证明通道,描述于 Docker 测试套件。
引用行为:
- 引用在导航之间并不稳定。如果某项操作失败,请重新运行
snapshot并使用新的引用。 - 批次会在已提交的主框架导航(包括同一 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 子命令。在 profile="user" 和其他现有会话(chrome-mcp)配置文件中不支持 batch。请在那里逐个发送动作。
- 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 生命周期:ref 来自批处理之前运行的
snapshot(snapshot不是嵌套动作)。改变页面状态的嵌套动作——例如触发导航的click,或修改 DOM 的evaluate——可能会使批处理其余部分中较早的 ref 失效。将改变状态的动作放在前面,或在重新snapshot后拆分为后续批处理。导航和重新snapshot发生在批处理之外(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 的 glob):
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 --clearopenclaw 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。提示注入可能会操纵它。如果不需要,请使用browser.evaluateEnabled=false禁用它。openclaw browser evaluate --fn接受函数源代码、表达式或语句主体。语句主体会被包装为异步函数,因此请使用return返回你想要的值。当页面端函数可能需要比默认 evaluate 超时更长的时间时,请使用--timeout-ms <ms>。- 有关登录和反机器人说明(X/Twitter 等),请参阅 浏览器登录 + X/Twitter 发帖。
- 保持 Gateway/node 主机私有(仅 loopback 或仅 tailnet)。
- 远程 CDP 端点功能强大。请为其建立隧道并加以保护。
严格模式示例(默认阻止私有/内部目标):
{
browser: {
ssrfPolicy: {
dangerouslyAllowPrivateNetwork: false,
allowedHostnames: ["*.example.com", "example.com", "localhost"],
},
},
}
相关¶
- 浏览器 - 概览、配置、配置文件、安全
- 浏览器登录 - 登录网站
- 浏览器 Linux 故障排除
- 浏览器 WSL2 故障排除
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw