stable-browser

intent

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.

inputs

environment & system

• macOS, Linux, or Windows with Chrome/Chromium installed (version 60+)
• bash shell or equivalent for running setup script
• port 9222 available on localhost (or alternate port of your choice)

openClaw config

• existing OpenClaw installation with browser automation support
• config file location: ~/.openclaw/config.json or project-level config
• current setup likely uses profile="chrome" (will be replaced)

external connections

• none required; this is a local-only protocol. no cloud dependencies, no auth tokens, no rate limits.

optional: pre-logged sessions

• if automation needs to interact with authenticated sites (Gmail, GitHub, X, LinkedIn), you'll log in once to ~/.chrome-debug-profile during setup and CDP reuses those cookies/sessions.

procedure

1. run setup script to initialize CDP

   • input: system with bash and Chrome installed
   • command: bash scripts/setup-cdp.sh
   • output: ~/.chrome-debug-profile directory created, Chrome LaunchAgent installed (macOS) or systemd service (Linux), browser.cdpUrl added to OpenClaw config pointing to http://localhost:9222

2. log into required sites (first run only)

   • input: none
   • action: launch Chrome manually or via the setup script, visit each site you need (Google, GitHub, X, etc.), log in once
   • output: cookies and session data stored in ~/.chrome-debug-profile, persisted across automation runs

3. update automation code to use CDP profile

   • input: existing browser automation code using profile="chrome"
   • action: replace all profile="chrome" with profile="openclaw"
   • output: all browser() calls now route through CDP instead of extension relay
   • example: browser(action="navigate", profile="openclaw", targetUrl="https://example.com")

4. verify CDP connection is live

   • input: Chrome running with debug port enabled
   • action: curl or ping http://localhost:9222/json/version to confirm protocol endpoint responds
   • output: JSON response with Chrome version info confirms connection is active

5. run your automation

   • input: updated browser automation code using profile="openclaw"
   • action: execute your OpenClaw script or workflow
   • output: browser actions (navigate, screenshot, click, type) execute directly against CDP, no extension relay involved

decision points

if setup script fails or you prefer manual configuration:

• see references/manual-setup.md for step-by-step instructions to launch Chrome with debug port and configure OpenClaw manually.

if port 9222 is already in use:

• check what's using it: lsof -i :9222
• if it's a stale Chrome process, kill it: pkill -f 'remote-debugging-port=9222'
• if it's another service, change the debug port (e.g., to 9223) in both the Chrome launch command and the browser.cdpUrl config value.

if you need headless (invisible) browser operation:

• add --headless=new flag to the Chrome launch command in setup-cdp.sh or your manual launch script.
• headless Chrome runs in the background with no visible window, useful for scheduled/server-side automation.

if Chrome profile gets corrupted or sessions are stale:

• delete ~/.chrome-debug-profile entirely.
• re-run bash scripts/setup-cdp.sh to recreate a clean profile.
• log back into sites that require authentication.

if you need to manage multiple tabs or specific tab targeting:

• CDP manages all open tabs in the dedicated profile.
• use the targetId parameter in browser() calls to pin automation to a specific tab if needed.
• otherwise, CDP will target the first available tab.

output contract

success state:

• browser.cdpUrl config value is set to http://localhost:9222 (or your alternate port)
• Chrome process is running with --remote-debugging-port=9222 and using profile ~/.chrome-debug-profile
• curl to http://localhost:9222/json/version returns valid JSON with version metadata
• all browser() function calls in automation code use profile="openclaw"
• browser automation executes without WebSocket errors, port confusion, or dropped connections
• cookies and auth sessions persist across automation runs

file locations:

• chrome debug profile: ~/.chrome-debug-profile/
• OpenClaw config with CDP URL: ~/.openclaw/config.json or project config
• setup script logs: stdout from bash scripts/setup-cdp.sh

outcome signal

you know it worked when:

• Chrome launches automatically on login (macOS LaunchAgent or Linux systemd enabled)
• your automation code runs to completion without "can't reach browser", WebSocket 403, or port errors
• screenshots, form fills, and navigation commands execute reliably on the first try
• you can navigate to authenticated sites without re-logging in between runs
• port 9222 stays responsive and doesn't drop mid-task
• if you run the same automation twice in a row, both runs succeed (no random failures like the extension relay)