Stable Browser

Item: Stable Browser
Rating: 7.3
Author: Implexa

Set up reliable browser automation using Chrome DevTools Protocol (CDP) instead of the flaky browser extension relay. Use when browser relay keeps disconnect...

copies: implexa run clawhub/stable-browser

view source

installs

stars

karma

SkillRank score ↗

7.3/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-05-26

stable-browser replaces openclaw's flaky extension relay with direct chrome devtools protocol connections, eliminating websocket 403 errors and disconnects via one-time setup script and dedicated debug profile.

structure

7.0

trigger phrases

6.0

procedure

8.0

edge cases

7.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

---
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

related skills

semantically similar in the cross-vendor index

clawhub

75% match

browser-cdp

Real Chrome browser automation via CDP Proxy — access pages with full user login state, bypass anti-bot detection, perform interactive operations (click/fill...

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.

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

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
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
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")
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
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)