OpenClaw 的浏览器控制 API 提供本地回环 HTTP 接口和 CLI，用于管理浏览器标签、执行点击/输入/导航等动作、获取快照（AI / 角色 / ARIA）以及设置 Cookie、设备模拟等。需要 Playwright 支持 navigate/act/AI 快照，否则回退到纯 CDP 模式。Docker 用户需单独安装 Chromium 二进制。

OpenClaw 浏览器控制 API 与 CLI 参考

配置、故障排除请参见 Browser 概览。本页是本地控制 HTTP API、openclaw browser CLI 以及脚本模式（快照、ref、等待、调试流程）的参考。

控制 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
• 权限：POST /permissions/grant
• 调试：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=<name>。POST /start?headless=true 请求一次性无头启动本地受管理配置文件，不会持久化浏览器配置；仅附加、远程 CDP 和现有会话配置文件会拒绝该覆盖，因为 OpenClaw 不启动这些浏览器的进程。

如果配置了共享密钥网关认证，浏览器 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)：动作 payload 未通过规范化或校验。
• ACT_SELECTOR_UNSUPPORTED (HTTP 400)：对不支持的动作 kind 使用了 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 依赖

部分功能（navigate/act/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，然后重启网关。对于 Docker，还需按下方说明安装 Chromium 浏览器二进制。

Docker Playwright 安装

如果 Gateway 运行在 Docker 中，避免使用 npx playwright（npm 覆盖冲突）。对于自定义镜像，将 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 的浏览器。高级动作（点击/输入/快照/PDF）通过 Playwright 操作在 CDP 之上；当 Playwright 缺失时，只有非 Playwright 操作可用。智能体看到一个稳定的接口，而本地/远程浏览器和配置文件在底层自由切换。

CLI 快速参考

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

基础：status、tabs、open/focus/close

openclaw browser status
openclaw browser start
openclaw browser start --headless # 一次性本地管理无头启动
openclaw browser stop            # 也会清除仅附加/远程 CDP 上的模拟
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

检查：screenshot、snapshot、console、errors、requests

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12        # 或 --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 console --level error
openclaw browser errors --clear
openclaw browser requests --filter api --clear
openclaw browser pdf
openclaw browser responsebody "**/api" --max-chars 5000

动作：navigate、click、type、drag、wait、evaluate

openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double           # 角色 ref 用 e12
openclaw browser click-coords 120 340        # 视口坐标
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 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 --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 移除
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 是 预装 调用；在触发选择器/对话框的 click/press 之前运行。如果某个动作打开了模态框，动作响应中会包含 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,/uploads}（回退：${os.tmpdir()}/openclaw/...）。
• upload 也可以通过 --input-ref 或 --element 直接设置文件输入。

当 OpenClaw 能够证明替换标签为同一页面时（例如相同 URL，或表单提交后一个旧标签变为一个新标签），稳定的标签 ID 和标签会存活 Chromium 原始标签替换。原始 target ID 仍然是易变的；脚本中应优先使用 tabs 返回的 suggestedTargetId。

快照标志速查：

• --format ai（默认，有 Playwright）：AI 快照，带数字 ref（aria-ref="<n>"）。
• --format aria：无障碍树，带 axN ref。当 Playwright 可用时，OpenClaw 通过后端 DOM id 将 ref 绑定到实时页面，后续动作可以使用它们；否则输出仅用于检查。
• --efficient（或 --mode efficient）：紧凑角色快照预设。设置 browser.snapshotDefaults.mode: "efficient" 使其成为默认值（参见 Gateway 配置）。
• --interactive、--compact、--depth、--selector 强制生成角色快照，ref 为 e12。--frame "<iframe>" 将角色快照范围限定到 iframe。
• --labels 添加一张视口截图，叠加 ref 标签（输出 MEDIA:<path>）。
• --urls 将发现的链接目标附加到 AI 快照。

快照与 ref

OpenClaw 支持两种“快照”风格：

• AI 快照（数字 ref）：openclaw browser snapshot（默认；--format ai）

  • 输出：包含数字 ref 的文本快照。
  • 动作：openclaw browser click 12、openclaw browser type 23 "hello"。
  • 内部：通过 Playwright 的 aria-ref 解析 ref。

• 角色快照（角色 ref 如 e12）：openclaw browser snapshot --interactive（或 --compact、--depth、--selector、--frame）

  • 输出：基于角色的列表/树，带有 [ref=e12]（以及可选的 [nth=1]）。
  • 动作：openclaw browser click e12、openclaw browser highlight e12。
  • 内部：通过 getByRole(...)（加上对重复项的 nth()）解析 ref。
  • 添加 --labels 可以输出一张叠加了 e12 标签的视口截图。
  • 当链接文本不明确且智能体需要具体导航目标时，添加 --urls。

• ARIA 快照（ARIA ref 如 ax12）：openclaw browser snapshot --format aria

  • 输出：无障碍树的结构化节点。
  • 动作：openclaw browser click ax12 在快照路径能通过 Playwright 和 Chrome 后端 DOM id 绑定 ref 时生效。

• 如果 Playwright 不可用，ARIA 快照仍可用于检查，但 ref 可能不可操作。需要动作 ref 时，重新用 --format ai 或 --interactive 拍摄快照。

• Docker 中原始 CDP 回退路径的证明：pnpm test:docker:browser-cdp-snapshot 会启动带 CDP 的 Chromium，运行 browser doctor --deep，验证角色快照包含链接 URL、光标提升的可点击项和 iframe 元数据。

Ref 行为：

• Ref 在导航后不稳定；如果失败，重新运行 snapshot 并使用新的 ref。
• /act 在触发替换后返回当前的原始 targetId，前提是它能证明替换标签。后续命令应继续使用稳定的标签 ID 或标签。
• 如果角色快照是使用 --frame 拍摄的，角色 ref 的范围限定在该 iframe 内，直到下次角色快照。
• 未知或过期的 axN ref 会快速失败，而不会回退到 Playwright 的 aria-ref 选择器。当发生这种情况时，在同一个标签上运行一次全新的快照。

等待增强

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

• 等待 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 browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

调试工作流

当动作失败时（例如“not visible”、“strict mode violation”、“covered”）：

1. openclaw browser snapshot --interactive
2. 使用 click <ref> / type <ref>（交互模式下优先使用角色 ref）
3. 如果仍然失败：openclaw browser highlight <ref> 查看 Playwright 在定位什么
4. 如果页面行为异常：
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. 深度调试：记录跟踪：
   • 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 输出包含 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 --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 禁用它。
• 使用 openclaw browser evaluate --timeout-ms <ms> 当页面端函数可能需要比默认评估超时更长的时间时。
• 关于登录和反爬虫笔记（X/Twitter 等），参见 Browser 登录 + X/Twitter 发帖。
• 保持 Gateway/节点主机私密（loopback 或 tailnet-only）。
• 远程 CDP 端点功能强大；请通过隧道保护它们。

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

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

相关文档

• Browser 概览 - 概述、配置、配置文件、安全
• Browser 登录 - 登录站点
• Browser Linux 故障排除
• Browser WSL2 故障排除

常见问题

如何安装 Playwright 在 Docker 中？

使用捆绑 CLI 安装 Chromium：docker compose run --rm openclaw-cli node /app/node_modules/playwright-core/cli.js install chromium。确保设置 PLAYWRIGHT_BROWSERS_PATH 并持久化 /home/node 路径。

快照 ref 不生效怎么办？

Ref 在导航后不稳定。如果动作失败，重新运行 openclaw browser snapshot 获取新 ref。如果使用 axN 报错，可能 ref 已过期或 Playwright 不可用，请改用 --format ai 或 --interactive 拍摄新快照。

openclaw browser 命令返回 "Playwright is not available"？

说明 Gateway 构建缺少 Playwright 运行时。对于普通安装，重新安装或更新 OpenClaw 并重启网关；对于 Docker 用户，请按上方步骤安装 Chromium 二进制。