浏览器控制 API

For setup, configuration, and troubleshooting, see Browser. This page is the reference for the local control HTTP API, the openclaw browser CLI, and scripting patterns (snapshots, refs, waits, debug flows).

Control API (optional)

For local integrations only, the Gateway exposes a small loopback HTTP API. This standalone server is opt-in — set the environment variable OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1 in the gateway service environment and restart the gateway before the HTTP endpoints become available. Without this variable the browser control runtime still works through the CLI and agent tools, but nothing listens on the loopback control port.

Status/start/stop: GET /, GET /doctor, POST /start, POST /stop, POST /reset-profile
Profiles: GET /profiles, POST /profiles/create, DELETE /profiles/:name
Tabs: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId, POST /tabs/action
Snapshot/screenshot: GET /snapshot, POST /screenshot
Actions: POST /navigate, POST /act
Hooks: POST /hooks/file-chooser, POST /hooks/dialog
Downloads: POST /download, POST /wait/download
Permissions: POST /permissions/grant
Debugging: GET /console, POST /pdf
Debugging: GET /errors, GET /requests, GET /dialogs, POST /trace/start, POST /trace/stop, POST /highlight
Network: POST /response/body
State: GET /cookies, POST /cookies/set, POST /cookies/clear
State: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
Settings: 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 会请求对本地托管配置文件进行一次性无头启动，而不更改持久化的浏览器配置；attach-only、远程 CDP 和 existing-session 配置文件会拒绝该覆盖，因为 OpenClaw 不会启动这些浏览器进程。对于标签页端点，targetId 是兼容性字段名。优先传入 GET /tabs 或 POST /tabs/open 返回的 suggestedTargetId；标签以及 t1 等 tabId 句柄也可以接受。原始 CDP target id 和唯一的原始 target-id 前缀仍然可用，但它们是不稳定的诊断句柄。如果配置了共享密钥 Gateway 网关认证，浏览器 HTTP 路由也需要认证：

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

注意：

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

`/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_EXISTING_SESSION_UNSUPPORTED（HTTP 501）：existing-session 配置文件不支持该操作。

其他运行时失败仍可能返回不带 code 字段的 { "error": "<message>" }。

Playwright 要求

部分功能（navigate/act/AI snapshot/role snapshot、元素截图、 PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回明确的 501 错误。没有 Playwright 时仍可使用的功能：

ARIA 快照
当每个标签页的 CDP WebSocket 可用时，role 风格的无障碍快照（--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 override 冲突）。对于自定义镜像，请将 Chromium 烘焙进镜像：

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

对于现有镜像，请改为通过内置 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 或 bind mount 持久化。OpenClaw 会在 Linux 上自动检测持久化的 Chromium。参见 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 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

状态：cookies、storage、offline、headers、geo、device

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"

注意：

upload 和 dialog 是预备调用；请在触发选择器/对话框的点击/按键之前运行它们。如果某个操作打开了模态框，操作响应会包含 blockedByDialog 和 browserState.dialogs.pending；传入该 dialogId 以直接响应。OpenClaw 外部处理的对话框会出现在 browserState.dialogs.recent 下。
click/type/等操作需要来自 snapshot 的 ref（数字 12、role ref e12 或可操作的 ARIA ref ax12）。操作故意不支持 CSS 选择器。当可见视口位置是唯一可靠目标时，请使用 click-coords。
下载和 trace 路径被限制在 OpenClaw 临时根目录：/tmp/openclaw{,/downloads}（回退：${os.tmpdir()}/openclaw/...）。
upload 接受来自 OpenClaw 临时上传根目录和 OpenClaw 托管入站媒体的文件。托管入站媒体可以引用为 media://inbound/<id>、沙箱相对路径 media/inbound/<id>，或托管入站媒体目录内的解析后路径。嵌套媒体 ref、 traversal、符号链接、硬链接和任意本地路径仍会被拒绝。
upload 也可以通过 --input-ref 或 --element 直接设置文件输入。

稳定的标签页 ID 和标签会在 Chromium raw-target 替换后保留，前提是 OpenClaw 能够证明替换后的标签页，例如 URL 相同，或表单提交后单个旧标签页变成单个新标签页。原始 target ID 仍然不稳定；在脚本中优先使用 tabs 里的 suggestedTargetId。 Snapshot 标志速览：

--format ai（使用 Playwright 时的默认值）：带数字引用的 AI snapshot（aria-ref="<n>"）。
--format aria：带 axN 引用的无障碍树。Playwright 可用时，OpenClaw 会通过后端 DOM ID 将引用绑定到实时页面，以便后续操作使用；否则请将输出仅视为检查用途。
--efficient（或 --mode efficient）：紧凑角色 snapshot 预设。设置 browser.snapshotDefaults.mode: "efficient" 可将其作为默认值（参见 Gateway 配置）。
--interactive、--compact、--depth、--selector 会强制使用带 ref=e12 引用的角色 snapshot。--frame "<iframe>" 会将角色 snapshot 的作用域限定到 iframe。
使用 Playwright 时，--labels 会添加一张带叠加引用标签的截图（打印 MEDIA:<path>），并附带一个 annotations 数组，其中包含每个引用的边界框。在 screenshot 上，Playwright 支持的标签可与 --full-page、 --ref 和 --element 配合使用；在 snapshot 上，随附截图仍然只包含视口。existing-session/chrome-mcp 配置文件会在页面截图上渲染叠加标签，但不会返回 annotations，也不会使用 Playwright 的整页/ref/element 投影辅助工具。没有 Playwright 或 chrome-mcp 时，无法使用带标签的截图。
--urls 会向 AI snapshot 追加发现到的链接目标。

Snapshot 和引用

OpenClaw 支持两种 “snapshot” 样式：

AI snapshot（数字引用）：openclaw browser snapshot（默认；--format ai）
- 输出：包含数字引用的文本 snapshot。
- 操作：openclaw browser click 12、openclaw browser type 23 "hello"。
- 在内部，引用通过 Playwright 的 aria-ref 解析。
角色 snapshot（类似 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 标签的截图。在 Playwright 支持的配置文件上，这还会返回每个引用的边界框元数据（annotations[]）。
- 当链接文本含糊而智能体需要具体导航目标时，添加 --urls。
ARIA snapshot（类似 ax12 的 ARIA 引用）：openclaw browser snapshot --format aria
- 输出：作为结构化节点的无障碍树。
- 操作：当 snapshot 路径可以通过 Playwright 和 Chrome 后端 DOM ID 绑定引用时，openclaw browser click ax12 可用。
如果 Playwright 不可用，ARIA snapshot 仍可用于检查，但引用可能不可操作。需要操作引用时，请用 --format ai 或 --interactive 重新 snapshot。
raw-CDP fallback 路径的 Docker 证明：pnpm test:docker:browser-cdp-snapshot 会使用 CDP 启动 Chromium，运行 browser doctor --deep，并验证角色 snapshot 包含链接 URL、光标提升的可点击项和 iframe 元数据。

引用行为：

引用不会跨导航保持稳定；如果某项失败，请重新运行 snapshot 并使用新的引用。
当可以证明替换标签页时，/act 会在操作触发的替换后返回当前原始 targetId。后续命令继续使用稳定标签页 ID/标签。
如果角色 snapshot 是通过 --frame 获取的，角色引用会限定在该 iframe 内，直到下一次角色 snapshot。
未知或陈旧的 axN 引用会快速失败，而不是回退到 Playwright 的 aria-ref 选择器。发生这种情况时，请在同一标签页上运行新的 snapshot。

等待增强功能

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

等待 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"

这些可以组合使用：

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>（在交互模式下优先使用角色引用）
如果仍然失败：使用 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 status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

JSON 中的角色 snapshot 包含 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 basic auth：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 接受函数源、表达式或语句体。语句体会被包装为 async 函数，因此请使用 return 返回你想取回的值。当页面端函数可能需要超过默认 evaluate 超时时间时，请使用 --timeout-ms <ms>。
关于登录和反 Bot 说明（X/Twitter 等），请参阅浏览器登录 + X/Twitter 发帖。
保持 Gateway 网关/节点主机私有（loopback 或仅 tailnet）。
远程 CDP 端点权限很强；请对其进行隧道封装并加以保护。

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

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

​Control API (optional)

​/act 错误契约

​Playwright 要求

​Docker Playwright 安装

​工作原理（内部）

​CLI 快速参考

​Snapshot 和引用

​等待增强功能

​调试工作流

​JSON 输出

​状态和环境控制项

​安全和隐私

​相关