{"skill":{"slug":"browser-cdp","displayName":"browser-cdp","summary":"Real Chrome browser automation via CDP Proxy — access pages with full user login state, bypass anti-bot detection, perform interactive operations (click/fill...","description":"---\nname: browser-cdp\ndescription: >\n  Real Chrome browser automation via CDP Proxy — access pages with full user login state,\n  bypass anti-bot detection, perform interactive operations (click/fill/scroll), extract\n  dynamic JavaScript-rendered content, take screenshots.\n  Triggers (satisfy ANY one):\n  - Target URL is a search results page (Bing/Google/YouTube search)\n  - Static fetch (agent-reach/WebFetch) is blocked by anti-bot (captcha/intercept/empty)\n  - Need to read logged-in user's private content\n  - YouTube, Twitter/X, Xiaohongshu, WeChat public accounts, etc.\n  - Task involves \"click\", \"fill form\", \"scroll\", \"drag\"\n  - Need screenshot or dynamic-rendered page capture\nmetadata:\n  author: adapted from eze-is/web-access (MIT licensed)\n  version: \"1.0.0\"\n---\n\n## What is browser-cdp?\n\nbrowser-cdp connects directly to your local Chrome via Chrome DevTools Protocol (CDP), giving the AI agent:\n\n- **Full login state** — your cookies and sessions are carried through\n- **Anti-bot bypass** — pages that block static fetchers (search results, video platforms)\n- **Interactive operations** — click, fill forms, scroll, drag, file upload\n- **Dynamic content extraction** — read JavaScript-rendered DOM\n- **Screenshots** — capture any page at any point\n\n## Architecture\n\n```\nChrome (remote-debugging-port=9222)\n    ↓ CDP WebSocket\nCDP Proxy (cdp-proxy.mjs) — HTTP API on localhost:3456\n    ↓ HTTP REST\nOpenClaw AI Agent\n```\n\n## Setup\n\n### 1. Start Chrome with debugging port\n\n```bash\n# macOS — must use full binary path (not `open -a`)\npkill -9 \"Google Chrome\"; sleep 2\n\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\" \\\n  --remote-debugging-port=9222 \\\n  --user-data-dir=/tmp/chrome-debug-profile \\\n  --no-first-run &\n```\n\nVerify:\n```bash\ncurl -s http://127.0.0.1:9222/json/version\n```\n\n### 2. Start CDP Proxy\n\n```bash\nnode ~/.openclaw/skills/browser-cdp/scripts/cdp-proxy.mjs &\nsleep 3\ncurl -s http://localhost:3456/health\n# {\"status\":\"ok\",\"connected\":true,\"sessions\":0,\"chromePort\":9222}\n```\n\n## API Reference\n\n```bash\n# List all tabs\ncurl -s http://localhost:3456/targets\n\n# Open URL in new tab\ncurl -s \"http://localhost:3456/new?url=https://example.com\"\n\n# Execute JavaScript\ncurl -s -X POST \"http://localhost:3456/eval?target=TARGET_ID\" \\\n  -d 'document.title'\n\n# JS click (fast, preferred)\ncurl -s -X POST \"http://localhost:3456/click?target=TARGET_ID\" \\\n  -d 'button.submit'\n\n# Real mouse click\ncurl -s -X POST \"http://localhost:3456/clickAt?target=TARGET_ID\" \\\n  -d '.upload-btn'\n\n# Screenshot\ncurl -s \"http://localhost:3456/screenshot?target=TARGET_ID&file=/tmp/shot.png\"\n\n# Scroll (lazy loading)\ncurl -s \"http://localhost:3456/scroll?target=TARGET_ID&direction=bottom\"\n\n# Navigate\ncurl -s \"http://localhost:3456/navigate?target=TARGET_ID&url=https://...\"\n\n# Close tab\ncurl -s \"http://localhost:3456/close?target=TARGET_ID\"\n```\n\n## Tool Selection: Three-Layer Strategy\n\n| Scenario | Use | Reason |\n|----------|------|------|\n| Public pages (GitHub, Wikipedia, blogs) | `agent-reach` | Fast, low token, structured |\n| **Search results** (Bing/Google/YouTube) | **`browser-cdp`** | agent-reach blocked |\n| **Login-gated content** | **`browser-cdp`** | No cookies in agent-reach |\n| JS-rendered pages | **`browser-cdp`** | Reads rendered DOM |\n| Simple automation, isolated screenshots | `agent-browser` | No Chrome setup |\n| Large-scale parallel scraping | `agent-reach` + parallel | browser-cdp gets rate-limited |\n\n**Decision flow:**\n```\nPublic content → agent-reach (fast, cheap)\nSearch results / blocked → browser-cdp\nStill fails → agent-reach fallback + record in site-patterns\n```\n\n## Known Limitations\n\n- Chrome must use a **separate profile** (`/tmp/chrome-debug-profile`)\n- Same-site parallel tabs may get rate-limited\n- Node.js 22+ required (native WebSocket)\n- macOS: use **full binary path** to start Chrome, not `open -a`\n\n## Site Patterns & Usage Log\n\n```bash\n~/.openclaw/skills/browser-cdp/references/site-patterns/   # per-domain experience\n~/.openclaw/skills/browser-cdp/references/usage-log.md    # per-use tracking\n```\n\n## Origin\n\nAdapted from [eze-is/web-access](https://github.com/eze-is/web-access) (MIT) for OpenClaw.\nA bug in the original (`require()` in ES module, [reported here](https://github.com/eze-is/web-access/issues/10)) is fixed in this version.\n","topics":["Javascript","Browser Automation"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":796,"installsAllTime":29,"installsCurrent":15,"stars":2,"versions":1},"createdAt":1774335415280,"updatedAt":1779078898155},"latestVersion":{"version":"1.0.0","createdAt":1774335415280,"changelog":"Initial release","license":"MIT-0"},"metadata":null,"owner":{"handle":"0xcjl","userId":"s17c0swjv7p83sgyqfwvqqkbed83hk19","displayName":"Jialin","image":"https://avatars.githubusercontent.com/u/38884292?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090065473}}