- name
- chromium
- description
- Launch a persistent headless Chromium with remote debugging (CDP) for browser automation — page navigation, clicks, form filling, screenshots, and cookie import. Use when the user asks to open a website, browse, click, read page content, or work with a browser.
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.1for browser tool integration. - Supports cookie import for pre-authenticated sessions.
Quick start
1. Launch Chromium
~/.openclaw/workspace/skills/chromium/scripts/start_chromium.shEnvironment variables (all optional):
| Variable | Default | Description |
|---|---|---|
CHROMIUM_PROFILE_DIR | $HOME/.openclaw/workspace/chromium-profile | User data directory |
CHROMIUM_DEBUG_PORT | 18801 | CDP remote debugging port |
CHROMIUM_LOG_FILE | $HOME/.openclaw/workspace/logs/chromium.log | Log file path |
CHROMIUM_BIN | auto-detect (chromium, chromium-browser, google-chrome) | Browser binary |
2. Verify CDP is ready
curl -s http://127.0.0.1:18801/json/versionIf 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 snapshotBrowser tool cheatsheet
| Action | Command |
|---|---|
| Open page | browser navigate url=<URL> |
| Wait for load | browser wait --load networkidle |
| Read page content | browser snapshot |
| Click element | browser click ref=<ref> |
| Type text | browser type ref=<ref> text=<text> |
| Scroll to element | browser scrollintoview <ref> |
| Take screenshot | browser screenshot |
| Run JavaScript | browser evaluate --fn "document.title" |
Snapshot format — important
Always use the default snapshot format (no extra parameters):
browser snapshotDo NOT use:
refs=aria— returns accessibility tree without actionable refsdepth=2or 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 snapshotBefore clicking:
browser scrollintoview <ref>
browser click <ref>If click fails ("Element not found or not visible"):
- Take a fresh
browser snapshot— never reuse old refs - Use
browser screenshotto see the visual state - For links, navigate directly by URL instead of clicking
- 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.comStep 3 — Verify by navigating to the site and checking if you're logged in.
Data locations
| What | Path |
|---|---|
| Browser profile | $CHROMIUM_PROFILE_DIR (default: ~/.openclaw/workspace/chromium-profile) |
| Launch log | $CHROMIUM_LOG_FILE (default: ~/.openclaw/workspace/logs/chromium.log) |
Troubleshooting
If CDP doesn't respond within 3 seconds after launch, check the log:
cat ~/.openclaw/workspace/logs/chromium.logCommon 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
chromiumbinary — setCHROMIUM_BINto 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