xbrowser 浏览器自动化调试：CDP 协议与实战模式

2026-06-11浏览器自动化CDP调试xbrowser

xbrowser vs Playwright：什么时候用哪个

xbrowser 是 OpenClaw 内置的浏览器自动化 Skill，通过 Chrome DevTools Protocol (CDP) 直接控制真实 Chrome/Edge/QQ 浏览器。和 Playwright 最大的区别：xbrowser 可以使用用户正在使用的浏览器实例，复用已登录的 cookie 和 session，不需要额外配置认证。

维度xbrowser (CDP)Playwright
认证复用浏览器登录态，零配置需要手动注入 cookie 或登录流程
浏览器用户真实浏览器（Chrome/Edge/QQ）自带 Chromium 实例
部署无需额外安装需安装浏览器二进制
适用场景需要登录态的交互式调试无头自动化测试、CI 环境

核心操作流程

xbrowser 的根本操作模式是四步循环：

1. snapshot  → 获取页面结构和交互元素（可访问性树）
2. 分析      → 找到目标元素的 ref（如 e15、aria-ref）
3. act       → 执行点击/输入/滚动等操作
4. snapshot  → 确认操作结果，页面是否更新

snapshot：获取页面结构

snapshot 返回的是可访问性树（a11y tree），比纯截图更适合 AI 理解。两种 ref 模式：

# role 模式（默认）：基于角色+名称定位
# 格式：role "button" name "提交"
# 优点：语义化，易理解
# 缺点：跨调用可能失效（元素重渲染后 ref 变化）

# aria 模式（推荐）：基于 aria-ref 定位
# 格式：aria-ref "e15"
# 优点：跨调用稳定，不因重渲染失效
# 缺点：不够语义化

# 推荐用法：始终用 refs="aria"

act：执行操作

# 点击
{ kind: "click", ref: "e15" }

# 输入文本
{ kind: "type", ref: "e20", text: "搜索内容" }

# 按键
{ kind: "press", key: "Enter" }

# 滚动到元素
{ kind: "hover", ref: "e8" }

# 页面导航
{ kind: "navigate", url: "https://example.com" }

实战案例：调试侧边栏折叠功能

用 xbrowser 本地调试 Astro 博客的侧边栏交互：

# 1. 启动本地 dev server
npm run dev   # → http://localhost:4321

# 2. 用 xbrowser 打开并 snapshot
snapshot url="http://localhost:4321"

# 3. 分析 snapshot 输出，找到侧边栏切换按钮的 ref
# 输出中看到：button "切换侧边栏" [e32]

# 4. 点击切换按钮
act kind="click" ref="e32"

# 5. 再次 snapshot 验证
snapshot  # → 确认侧边栏已隐藏

# 6. 缩小视口测试响应式
act kind="resize" width=800 height=600
snapshot  # → 确认自动折叠逻辑生效

SSE 流式响应设计模式

当 Agent 通过 xbrowser 操作浏览器时，结果以 SSE（Server-Sent Events）流式返回，前端可以实时展示操作进度：

# SSE 事件类型设计
event: start
data: {"message": "开始执行浏览器操作"}

event: tool
data: {"name": "snapshot", "status": "running"}

event: tool
data: {"name": "snapshot", "status": "done", "result": "页面已加载，共 45 个交互元素"}

event: tool
data: {"name": "click", "status": "running", "target": "切换侧边栏按钮"}

event: tool
data: {"name": "click", "status": "done"}

event: done
data: {"message": "操作完成"}

event: error
data: {"message": "元素 e32 不存在，可能已被移除或页面已刷新"}

避坑经验

  • 操作后加延迟：点击按钮后 DOM 更新可能不是同步的，用 delayMs 等待 300-500ms 再 snapshot
  • 不用 act:wait：用 delayMs + 具体的 UI 状态检查（等特定元素出现），而非盲目等待固定时间
  • aria ref 优于 role ref：aria ref 跨 snapshot 调用不失效
  • profile 区分：私密操作用 sandbox（无登录态），需要登录态用 user（用户真实浏览器）
  • 单步超时：snapshot 和 act 都设置 30s 超时，防止页面卡住
未标记