什么是 browser-cdp？

browser-cdp 通过 Chrome DevTools Protocol（CDP）直接连接本地 Chrome 浏览器，为 AI agent 提供以下能力：

• 完整的登录状态 —— 复用您的 Cookie 和会话信息
• 反机器人绕过能力 —— 可访问屏蔽静态抓取器的页面（如搜索引擎结果页、视频平台）
• 交互式操作 —— 支持点击、表单填写、滚动、拖拽、文件上传等
• 动态内容提取 —— 可读取 JavaScript 渲染后的 DOM
• 截图功能 —— 可在任意时刻对任意页面进行截图

架构

Chrome（remote-debugging-port=9222）
    ↓ CDP WebSocket
CDP Proxy（cdp-proxy.mjs）—— 运行于 localhost:3456 的 HTTP API
    ↓ HTTP REST
OpenClaw AI Agent

配置步骤

1. 启动启用调试端口的 Chrome

# macOS —— 必须使用完整二进制路径（不可使用 `open -a`）
pkill -9 "Google Chrome"; sleep 2
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" 
  --remote-debugging-port=9222 
  --user-data-dir=/tmp/chrome-debug-profile 
  --no-first-run &

验证是否启动成功：

curl -s http://127.0.0.1:9222/json/version

2. 启动 CDP Proxy

node ~/.openclaw/skills/browser-cdp/scripts/cdp-proxy.mjs &
sleep 3
curl -s http://localhost:3456/health
# {"status":"ok","connected":true,"sessions":0,"chromePort":9222}

API 参考

# 列出所有标签页
curl -s http://localhost:3456/targets

# 在新标签页中打开 URL
curl -s "http://localhost:3456/new?url=https://example.com"

# 执行 JavaScript
curl -s -X POST "http://localhost:3456/eval?target=TARGET_ID" 
  -d 'document.title'

# JS 级点击（速度快，推荐使用）
curl -s -X POST "http://localhost:3456/click?target=TARGET_ID" 
  -d 'button.submit'

# 真实鼠标点击
curl -s -X POST "http://localhost:3456/clickAt?target=TARGET_ID" 
  -d '.upload-btn'

# 截图
curl -s "http://localhost:3456/screenshot?target=TARGET_ID&file=/tmp/shot.png"

# 滚动（支持懒加载）
curl -s "http://localhost:3456/scroll?target=TARGET_ID&direction=bottom"

# 导航至指定 URL
curl -s "http://localhost:3456/navigate?target=TARGET_ID&url=https://..."

# 关闭标签页
curl -s "http://localhost:3456/close?target=TARGET_ID"

工具选择：三层策略

决策流程：

公开内容 → 使用 agent-reach（快速、低成本）
搜索结果 / 被屏蔽页面 → 使用 browser-cdp
仍失败 → 回退至 agent-reach，并将该站点模式记录至 site-patterns

已知限制

• Chrome 必须使用独立的用户配置文件（例如 /tmp/chrome-debug-profile）
• 同站多标签页可能触发频率限制
• 需要 Node.js 22+（依赖原生 WebSocket 支持）
• macOS 下：必须使用 Chrome 的完整二进制路径启动，不可使用 open -a

站点模式与使用日志

~/.openclaw/skills/browser-cdp/references/site-patterns/   # 按域名存储的经验规则
~/.openclaw/skills/browser-cdp/references/usage-log.md    # 每次调用的详细记录

起源

本项目基于 eze-is/web-access（MIT 协议）适配改造，专为 OpenClaw 设计。 原始版本存在一个 Bug（ES 模块中误用 require()，已在本版本修复）。