dvcrn 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 scripts/setup-cdp.sh
This will:
- Create a dedicated Chrome profile at
~/.chrome-debug-profile - Add
browser.cdpUrlto your OpenClaw config - Create a LaunchAgent (macOS) so Chrome starts on login
- Verify the connection works
Manual Setup
If you prefer to set things up manually, see 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
targetIdto pin a specific tab - Headless mode: Add
--headless=newto 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.shor 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-profileand re-run setup