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#

bash

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

Environment variables (all optional):

VariableDefaultDescriptionCHROMIUM_PROFILE_DIR``$HOME/.openclaw/workspace/chromium-profileUser data directoryCHROMIUM_DEBUG_PORT``18801CDP remote debugging portCHROMIUM_LOG_FILE``$HOME/.openclaw/workspace/logs/chromium.logLog file pathCHROMIUM_BINauto-detect ( chromium, chromium-browser, google-chrome)Browser binary

2. Verify CDP is ready#

bash

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#

text

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

Browser tool cheatsheet#

ActionCommandOpen pagebrowser navigate url=<URL>Wait for loadbrowser wait --load networkidleRead page contentbrowser snapshotClick elementbrowser click ref=<ref>Type textbrowser type ref=<ref> text=<text>Scroll to elementbrowser scrollintoview <ref>Take screenshotbrowser screenshotRun JavaScriptbrowser evaluate --fn "document.title"

Snapshot format — important#

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

text

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:

text

browser wait --load networkidle
browser snapshot

Before clicking:

text

browser scrollintoview <ref>
browser click <ref>

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:

bash

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#

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

bash

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