Skip to main content
有关安装、配置和故障排除，请参见 浏览器。 本页是本地控制 HTTP API、openclaw browser CLI 以及脚本模式（快照、ref、等待、调试流程）的参考文档。

​
控制 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 /navigate、POST /act
  • 钩子：POST /hooks/file-chooser、POST /hooks/dialog
  • 下载：POST /download、POST /wait/download
  • 权限：POST /permissions/grant
  • 调试：GET /console、POST /pdf
  • 调试：GET /errors、GET /requests、GET /dialogs、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；标签和 tabId 句柄（如 t1）也被接受。原始 CDP target id 和唯一的原始 target-id 前缀仍然可用，但它们是易变的诊断句柄。 如果配置了共享密钥网关身份验证，浏览器 HTTP 路由也需要身份验证：
  • Authorization: Bearer <gateway token>
  • x-openclaw-password: <gateway password>，或使用该密码的 HTTP Basic 认证
注意：
  • 这个独立的回环浏览器 API 不会消费可信代理或 Tailscale Serve 身份头。
  • 如果 gateway.auth.mode 为 none 或 trusted-proxy，这些回环浏览器 路由不会继承这些带身份的模式；请将其仅用于回环。

​
/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_EXISTING_SESSION_UNSUPPORTED（HTTP 501）：现有会话配置文件不支持该操作。
其他运行时失败仍可能返回不含 code 字段的 { "error": "<message>" }。

​
Playwright 要求

某些功能（导航／操作／AI 快照／角色快照、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回明确的 501 错误。 不使用 Playwright 仍可用的功能：
  • ARIA 快照
  • 基于角色的可访问性快照（--interactive、--compact、 --depth、--efficient），前提是每个标签页可用 CDP WebSocket。这是 用于检查和 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 烘焙进镜像：
浏览器也需要系统库，因此在一次性 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 以输出机器可读结果。
注意：
  • 面向代理的 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（数字 12、角色 ref e12 或 可操作的 ARIA ref ax12）。操作有意不支持 CSS 选择器。仅当可见视口位置是唯一可靠的目标时， 才使用 click-coords。
  • 下载和跟踪路径受限于 OpenClaw 临时根目录：/tmp/openclaw{,/downloads} （备用路径：${os.tmpdir()}/openclaw/...）。
  • upload 接受来自 OpenClaw 临时上传根目录的文件以及由 OpenClaw 管理的入站媒体。 受管理的入站媒体可以通过 media://inbound/<id>、相对于沙箱的 media/inbound/<id>，或受管理入站媒体目录中的已解析路径进行引用。嵌套媒体引用、 路径遍历、符号链接、硬链接和任意本地路径仍会被拒绝。
  • upload 还可以通过 --input-ref 或 --element 直接设置文件输入框。
当 OpenClaw 能证明替换后的标签页时，稳定的 tab id 和 label 会在 Chromium 原始目标替换后保持不变，例如同一 URL 的唯一旧/新配对，或者表单提交后单个旧标签页变为单个新标签页。含糊的重复 URL 替换会获得新的句柄。原始目标 id 仍然是易变的；在脚本中请优先使用 tabs 返回的 suggestedTargetId。 快照标志一览：
  • --format ai（默认，使用 Playwright）：带数字 refs 的 AI 快照（aria-ref="<n>"）。
  • --format aria：带 axN refs 的可访问性树。在 Playwright 可用时，OpenClaw 会将 refs 与后端 DOM id 绑定到实时页面，因此后续操作可以使用它们；否则应将输出仅视为检查用途。
  • --efficient（或 --mode efficient）：紧凑的 role 快照预设。设置 browser.snapshotDefaults.mode: "efficient" 可将其设为默认值（参见 Gateway 配置）。
  • --interactive、--compact、--depth、--selector 会强制使用带 ref=e12 refs 的 role 快照。--frame "<iframe>" 会将 role 快照限定到某个 iframe。
  • 在使用 Playwright 时，--labels 会添加带有叠加 ref 标签的截图 （输出 MEDIA:<path>），并附带一个 annotations 数组，其中包含每个 ref 的边界 框。在 screenshot 中，基于 Playwright 的标签支持 --full-page、--ref 和 --element；在 snapshot 中，附带的截图仍然 仅限视口。现有会话/chrome-mcp 配置文件会在页面截图上渲染叠加标签，但不会返回 annotations 或使用 Playwright 的 full-page/ref/element 投影助手。没有 Playwright 或 chrome-mcp 时， 不可用带标签的截图。
  • --urls 会将发现的链接目标附加到 AI 快照中。

​
快照和 ref

OpenClaw 支持两种“快照”样式：
  • AI 快照（数字 refs）：openclaw browser snapshot（默认；--format ai）
    • 输出：包含数字 refs 的文本快照。
    • 操作：openclaw browser click 12、openclaw browser type 23 "hello"。
    • 在内部，ref 通过 Playwright 的 aria-ref 解析。
  • Role 快照（类似 e12 的 role refs）：openclaw browser snapshot --interactive（或 --compact、--depth、--selector、--frame）
    • 输出：带有 [ref=e12]（以及可选 [nth=1]）的基于 role 的列表/树。
    • 操作：openclaw browser click e12、openclaw browser highlight e12。
    • 在内部，ref 通过 getByRole(...)（以及重复项的 nth()）解析。
    • 添加 --labels 可包含一张带叠加 e12 标签的截图。在 基于 Playwright 的配置文件中，这还会返回每个 ref 的边界框元数据 （annotations[]）。
    • 当链接文本含糊且代理需要明确的导航目标时，添加 --urls。
  • ARIA 快照（类似 ax12 的 ARIA refs）：openclaw browser snapshot --format aria
    • 输出：作为结构化节点的可访问性树。
    • 操作：当快照路径可以通过 Playwright 和 Chrome 后端 DOM id 绑定 ref 时，openclaw browser click ax12 可正常工作。
  • 如果 Playwright 不可用，ARIA 快照仍可用于检查，但 refs 可能不可操作。在需要操作 refs 时，使用 --format ai 或 --interactive 重新快照。
  • 当驱动暴露稳定的文档标识时，同一配置文件、标签页、文档和选项族的连续 AI 和 role 快照会在前一快照中不存在的带 ref 行后追加 [new]。导航会开始一个不带标记的新基线；现有会话快照不会显示差异。第一次快照会在不带标记的情况下建立基线；后续响应还会暴露 newElements，并在该值非零时添加一个计数页脚。带有 axN refs 的结构化 --format aria 快照不使用差异标记。
  • 原始 CDP 回退路径的 Docker 证明：pnpm test:docker:browser-cdp-snapshot 启动带 CDP 的 Chromium，运行 browser doctor --deep，并验证 role 快照包含链接 URL、由光标提升为可点击项的元素，以及 iframe 元数据。
Ref 行为：
  • Refs 在导航之间不稳定；如果某项失败，请重新运行 snapshot 并使用新的 ref。
  • 批处理会在提交主框架导航后停止——包括同 URL 的 重新加载——或在页面关闭后停止。其 aborted 摘要会报告动作 编号和跳过数量；在发出后续相关动作之前，请先获取新的快照，或者在预期会发生导航时使用单独的 act 调用。
  • /act 会在动作触发替换后返回当前原始 targetId，前提是它能够证明替换后的标签页。后续命令请继续使用稳定的标签页 id/标签。
  • 如果 role 快照是使用 --frame 生成的，则 role refs 的作用域仅限于该 iframe，直到下一次 role 快照。
  • 未知或过期的 axN refs 会快速失败，而不会回退到 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 将整个批次限定到一个标签页。
  • 引用生命周期：引用来自批次执行前的一次 snapshot 运行（snapshot 不是嵌套动作）。会改变页面状态的嵌套动作——例如触发导航的 click，或修改 DOM 的 evaluate——可能会使整个批次后续部分中更早的引用失效。请将会改变状态的动作放在前面，或者在重新执行 snapshot 后拆分到后续批次。导航和重新 snapshot 在批次外进行（openclaw browser navigate / snapshot），因为 open、navigate 和 snapshot 不是 /act 的 kind。
  • 目标 id 冲突：嵌套动作可以省略 targetId，也可以重复请求级别的 targetId；如果嵌套中显式提供的 targetId 解析到不同的标签页，则会在任何动作执行前被拒绝，并返回 ACT_TARGET_ID_MISMATCH。批量动作按设计共享请求的标签页。
  • 错误摘要：响应为 { "results": [{ "ok": true }, { "ok": false, "error": "<message>" }, ...] }，按顺序每个动作对应一项。默认 stopOnError 时，数组会在首次失败处结束；使用 --continue 时则会覆盖全部动作。任何失败项都会使 CLI 以非零状态退出；脚本可传入 --json 以保留完整的有序响应。

​
等待增强功能

你可以等待的不仅仅是时间/文本：
  • 等待 URL（Playwright 支持 glob）：
    • openclaw browser wait --url "**/dash"
  • 等待加载状态：
    • openclaw browser wait --load networkidle
    • 适用于受管理的 openclaw 和原始/远程 CDP 配置文件。使用 existing-session 驱动的配置文件（包括默认的 user 配置文件）会拒绝 networkidle；在这些情况下请使用 --url、--text、选择器或 --fn 等待。
  • 等待 JS 谓词：
    • openclaw browser wait --fn "window.ready===true"
  • 等待选择器变为可见：
    • openclaw browser wait "#main"
这些可以组合使用：

​
调试工作流

当某个操作失败时（例如，“not visible”、“strict mode violation”、“obscured”）：
  1. openclaw browser snapshot --interactive
  2. 使用 click <ref> / type <ref>（在交互模式中优先使用 role refs）
  3. 如果仍然失败：openclaw browser highlight <ref> 查看 Playwright 正在定位什么
  4. 如果页面行为异常：
    • openclaw browser errors --clear
    • openclaw browser requests --filter api --clear
  5. 深度调试：记录 trace：
    • openclaw browser trace start
    • 复现问题
    • openclaw browser trace stop（输出 TRACE:<path>）。

​
JSON 输出

--json 适用于脚本和结构化工具。 示例：
JSON 中的 Role 快照包含 refs，以及一个小型 stats 块（lines/chars/refs/interactive），这有助于工具推断负载大小和密度。

​
状态和环境开关

这些对类似“让站点表现得像 X”的工作流很有用：
  • Cookies：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 profiles 可能包含已登录会话；请将它们视为敏感信息。
  • browser act kind=evaluate / openclaw browser evaluate 和 wait --fn 会在页面上下文中执行任意 JavaScript。提示注入可能会影响它们。 如果不需要，请使用 browser.evaluateEnabled=false 将其禁用。
  • openclaw browser evaluate --fn 接受函数源码、表达式或 语句体。语句体会被包装为异步函数，因此请使用 return 返回你想要的值。当你的前端函数可能需要比默认 evaluate 超时更长的时间时， 请使用 --timeout-ms <ms>。
  • 关于登录和反机器人说明（X/Twitter 等），请参见 Browser login + X/Twitter posting。
  • 保持 Gateway/node 主机私有（仅限 loopback 或 tailnet）。
  • 远程 CDP 端点具有极高权限；请通过隧道访问并妥善保护它们。
严格模式示例（默认会阻止私有/内部目标）：

​
相关内容