Chromium (persistent headless profile)

What it does

• Launches headless Chromium with a persistent profile (logins, cookies, localStorage survive restarts).
• Exposes Chrome DevTools Protocol (CDP) on 127.0.0.1 for browser tool integration.
• Supports cookie import for pre-authenticated sessions.

Quick start

1. Launch Chromium

~/.openclaw/workspace/skills/chromium/scripts/start_chromium.sh

Environment variables (all optional):

2. Verify CDP is ready

curl -s http://127.0.0.1:18801/json/version

If you get JSON with Browser and webSocketDebuggerUrl — it's ready.

3. Use browser tools

browser navigate url=https://example.com
browser wait --load networkidle
browser snapshot

Browser tool cheatsheet

Snapshot format — important

Always use the default snapshot format (no extra parameters):

browser snapshot

Do NOT use:

• refs=aria — returns accessibility tree without actionable refs
• depth=2 or other depth limits — truncates DOM and hides content

The default AI format returns full page text with refs (e12, e293, etc.) suitable for click/type.

Working with dynamic pages (SPAs)

Single-page apps (React, Next.js, etc.) continuously update the DOM. Refs become stale between snapshots.

After every navigation:

browser wait --load networkidle
browser snapshot

Before clicking:

browser scrollintoview \x3Cref>
browser click \x3Cref>

If click fails ("Element not found or not visible"):

1. Take a fresh browser snapshot — never reuse old refs
2. Use browser screenshot to see the visual state
3. For links, navigate directly by URL instead of clicking
4. As a last resort, use JavaScript: browser evaluate --fn "document.querySelector('...').click()"

Cookie import (pre-authenticated sessions)

To use a site that requires login, export cookies from a browser where you're already logged in and import them:

Step 1 — Export cookies (in your regular browser):

• Install Cookie-Editor extension
• Go to the target site (make sure you're logged in)
• Export cookies as JSON, save as cookies.json
• Copy to server: scp cookies.json server:/tmp/

Step 2 — Import:

python3 ~/.openclaw/workspace/skills/chromium/scripts/import_cookies.py \
  /tmp/cookies.json \
  --domain example.com

Step 3 — Verify by navigating to the site and checking if you're logged in.

Data locations

Troubleshooting

If CDP doesn't respond within 3 seconds after launch, check the log:

cat ~/.openclaw/workspace/logs/chromium.log

Common issues:

• "Address already in use" — another Chromium is running. The script kills previous instances automatically, but you can run pkill -f "chromium.*remote-debugging" manually.
• SingletonLock — stale lock file. The script removes it if Chromium isn't running.
• No chromium binary — set CHROMIUM_BIN to the correct path (e.g., /usr/bin/google-chrome).

Requirements

• Chromium, Chromium Browser, or Google Chrome installed on the host
• Python 3 (for cookie import script)
• OpenClaw with browser tool support