Set up reliable browser automation using Chrome DevTools Protocol (CDP) instead of the flaky browser extension relay. Use when browser relay keeps disconnect...
--- name: stable-browser description: Set up reliable browser automation using Chrome DevTools Protocol (CDP) instead of the flaky browser extension relay. Use when browser relay keeps disconnecting, throwing WebSocket 403 errors, or when you need stable headless/headed browser control for web scraping, form filling, social media posting, or any browser automation task. Replaces profile="chrome" with a rock-solid CDP connection. --- # Stable Browser Replace the unreliable browser extension relay with a direct Chrome DevTools Protocol connection. ## The Problem The OpenClaw browser extension relay (`profile="chrome"`) frequently breaks: - WebSocket 403 errors - Port confusion (gateway port vs relay port) - Dropped connections mid-automation - "Can't reach browser control service" errors - Badge/tab attachment confusion ## The Fix: Chrome CDP Launch Chrome with a debug port and connect directly. No extension needed. ### Quick Setup Run the setup script to configure everything: ```bash bash scripts/setup-cdp.sh ``` This will: 1. Create a dedicated Chrome profile at `~/.chrome-debug-profile` 2. Add `browser.cdpUrl` to your OpenClaw config 3. Create a LaunchAgent (macOS) so Chrome starts on login 4. Verify the connection works ### Manual Setup If you prefer to set things up manually, see [references/manual-setup.md](references/manual-setup.md). ### Usage After setup, always use `profile="openclaw"` (not `profile="chrome"`): ``` browser(action="snapshot", profile="openclaw") browser(action="navigate", profile="openclaw", targetUrl="https://example.com") browser(action="screenshot", profile="openclaw") ``` ### Key Differences from Extension Relay | Feature | Extension Relay | CDP Direct | |---------|----------------|------------| | Stability | Frequent disconnects | Rock solid | | Setup | Install extension + attach tab | One-time script | | Auth/Cookies | Shares your main Chrome | Dedicated profile | | Speed | Extra hop through extension | Direct protocol | | Headless | No | Optional (`--headless=new`) | ### Dedicated Profile The CDP browser uses `~/.chrome-debug-profile` — a separate Chrome profile. This means: - Log into sites once, stays logged in - Your main Chrome is untouched - No extension conflicts - Survives Chrome updates ### Tips - **First run**: Log into any sites you need (Google, GitHub, X, LinkedIn, etc.) - **Multiple tabs**: CDP manages all tabs — use `targetId` to pin a specific tab - **Headless mode**: Add `--headless=new` to the launch command for invisible operation - **Port conflict**: If port 9222 is taken, change it in both the launch command and config - **Restart Chrome**: `pkill -f 'remote-debugging-port=9222' && sleep 1 && bash scripts/setup-cdp.sh` ### Troubleshooting - **"Can't reach browser"**: Chrome isn't running with debug port. Run `setup-cdp.sh` or launch manually - **Port 9222 in use**: Another Chrome or process grabbed it. Kill it: `lsof -i :9222` - **Stale session**: Chrome crashed. Kill and restart: `pkill -f chrome-debug-profile` - **Profile corruption**: Delete `~/.chrome-debug-profile` and re-run setup
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit intent statement, structured inputs with env/system/auth details, broke procedure into discrete numbered steps with clear input/output at each stage, extracted decision logic from tips into a dedicated decision points section, formalized output contract with success criteria and file locations, and added outcome signal with user-facing success indicators.
use Chrome DevTools Protocol (CDP) for rock-solid browser automation instead of the unreliable OpenClaw browser extension relay. the extension relay frequently throws WebSocket 403 errors, drops connections mid-task, and creates port confusion. CDP gives you direct protocol access to a dedicated Chrome instance, perfect for web scraping, form filling, social media posting, screenshot capture, or any browser automation that needs to stay connected. use this when profile="chrome" keeps failing or when you need headless operation.
environment & system
openClaw config
~/.openclaw/config.json or project-level configprofile="chrome" (will be replaced)external connections
optional: pre-logged sessions
~/.chrome-debug-profile during setup and CDP reuses those cookies/sessions.run setup script to initialize CDP
bash scripts/setup-cdp.sh~/.chrome-debug-profile directory created, Chrome LaunchAgent installed (macOS) or systemd service (Linux), browser.cdpUrl added to OpenClaw config pointing to http://localhost:9222log into required sites (first run only)
~/.chrome-debug-profile, persisted across automation runsupdate automation code to use CDP profile
profile="chrome"profile="chrome" with profile="openclaw"browser(action="navigate", profile="openclaw", targetUrl="https://example.com")verify CDP connection is live
http://localhost:9222/json/version to confirm protocol endpoint respondsrun your automation
profile="openclaw"if setup script fails or you prefer manual configuration:
if port 9222 is already in use:
lsof -i :9222pkill -f 'remote-debugging-port=9222'browser.cdpUrl config value.if you need headless (invisible) browser operation:
--headless=new flag to the Chrome launch command in setup-cdp.sh or your manual launch script.if Chrome profile gets corrupted or sessions are stale:
~/.chrome-debug-profile entirely.bash scripts/setup-cdp.sh to recreate a clean profile.if you need to manage multiple tabs or specific tab targeting:
targetId parameter in browser() calls to pin automation to a specific tab if needed.success state:
browser.cdpUrl config value is set to http://localhost:9222 (or your alternate port)--remote-debugging-port=9222 and using profile ~/.chrome-debug-profilehttp://localhost:9222/json/version returns valid JSON with version metadatabrowser() function calls in automation code use profile="openclaw"file locations:
~/.chrome-debug-profile/~/.openclaw/config.json or project configbash scripts/setup-cdp.shyou know it worked when: