什么是 browser-cdp？

browser-cdp 通过 Chrome DevTools 协议（CDP）直接连接到本地 Chrome，为 AI 代理提供：

• - 完整的登录状态 — 携带你的 cookies 和会话信息
• 反爬虫绕过 — 访问那些屏蔽静态抓取器的页面（搜索结果、视频平台）
• 交互式操作 — 点击、填写表单、滚动、拖拽、文件上传
• 动态内容提取 — 读取 JavaScript 渲染后的 DOM
• 截图功能 — 随时捕获任意页面

架构

Chrome (远程调试端口=9222)
↓ CDP WebSocket
CDP 代理 (cdp-proxy.mjs) — 在 localhost:3456 提供 HTTP API
↓ HTTP REST
OpenClaw AI 代理

设置

1. 启动带调试端口的 Chrome

bash

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 &

验证：
bash
curl -s http://127.0.0.1:9222/json/version

2. 启动 CDP 代理

bash
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 参考

bash

列出所有标签页

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

导航

curl -s http://localhost:3456/navigate?target=TARGET_ID&url=https://...

关闭标签页

curl -s http://localhost:3456/close?target=TARGET_ID

工具选择：三层策略

场景	使用	原因
公开页面（GitHub、Wikipedia、博客）	agent-reach	快速、低 token、结构化
搜索结果（Bing/Google/YouTube）

browser-cdp | agent-reach 被屏蔽 | | 需要登录的内容 | browser-cdp | agent-reach 没有 cookies | | JS 渲染的页面 | browser-cdp | 读取渲染后的 DOM | | 简单自动化、独立截图 | agent-browser | 无需设置 Chrome | | 大规模并行抓取 | agent-reach + 并行 | browser-cdp 会被限速 |

决策流程：

公开内容 → agent-reach（快速、低成本）
搜索结果 / 被屏蔽 → browser-cdp
仍然失败 → agent-reach 回退 + 记录到 site-patterns

已知限制

• - Chrome 必须使用独立的用户配置文件（/tmp/chrome-debug-profile）
• 同一站点的并行标签页可能会被限速
• 需要 Node.js 22+（原生 WebSocket）
• macOS：使用完整的二进制路径启动 Chrome，不要用 open -a

站点模式与使用日志

bash
~/.openclaw/skills/browser-cdp/references/site-patterns/ # 按域名记录的经验
~/.openclaw/skills/browser-cdp/references/usage-log.md # 按使用记录追踪

来源

改编自 eze-is/web-access（MIT 协议），用于 OpenClaw。
本版本修复了原版中的一个 bug（在 ES 模块中使用 require()，在此报告）。