Browser 控制 API（CLI 参考与脚本化操作）

概述

OpenClaw 浏览器控制 API 的完整参考，包括本地 loopback HTTP API、openclaw browser CLI 命令，以及 snapshot、ref、wait 等脚本化操作模式。适用于本地集成和调试场景。

核心功能

控制 API 端点（loopback HTTP）

类别	端点
生命周期	`GET /`、`POST /start`、`POST /stop`
标签页	`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
快照/截图	`GET /snapshot`、`POST /screenshot`
动作	`POST /navigate`、`POST /act`
状态	`GET /cookies`、`POST /cookies/set`、`GET /storage/:kind`
调试	`GET /console`、`GET /errors`、`POST /trace/start`、`POST /trace/stop`

所有端点支持 ?profile=<name> 参数。配置了 gateway 共享密钥时需要 Bearer token 认证。

CLI 快速参考

# 基础操作
openclaw browser status
openclaw browser start [--headless]
openclaw browser open https://example.com
 
# 快照与截图
openclaw browser snapshot                    # AI snapshot（默认）
openclaw browser snapshot --interactive      # Role snapshot（e12 ref）
openclaw browser snapshot --format aria      # ARIA snapshot（ax12 ref）
openclaw browser screenshot [--full-page]
 
# 动作（需要 ref）
openclaw browser click 12                    # AI ref
openclaw browser click e12                   # Role ref
openclaw browser type 23 "hello" --submit
openclaw browser navigate https://example.com
 
# 等待
openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
 
# 状态与环境
openclaw browser cookies
openclaw browser set offline on
openclaw browser set device "iPhone 14"
openclaw browser set timezone America/New_York

Ref 机制

Ref 不跨导航稳定：页面跳转后需重新 snapshot 获取新 ref
AI snapshot 数字 ref（12）通过 Playwright aria-ref 解析
Role snapshot ref（e12）通过 getByRole() + nth() 解析
ARIA ref（ax12）通过 Chrome backend DOM id 绑定，Playwright 不可用时仅供检查

Playwright 依赖

需要 Playwright 的功能：navigate、act、AI snapshot、CSS 元素截图、PDF 导出。

不需要 Playwright 的功能：ARIA snapshot、Role snapshot（CDP fallback）、页面截图（managed profile）。

配置/权限

Docker 安装 Playwright：

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

调试工作流：

openclaw browser snapshot --interactive
使用 click <ref> / type <ref>
失败时：openclaw browser highlight <ref> 查看 Playwright 目标
深度调试：openclaw browser trace start → 复现 → openclaw browser trace stop

Wiki AI

目录