Documentation

AI agent integration guide — managed fingerprints and proxy routing over standard CDP.

Quick Start

Pre-built prompt

Use this prompt to get started faster

Drop this into any AI agent (Claude, GPT-4, Gemini, etc.) to have it automatically install and deploy Clawbrowser. Fill in the [BRACKETED] placeholders before sending — or let the agent ask you for them.

Set your API key, then launch with a fingerprint profile ID. On first use the profile is generated from the API and cached locally — subsequent launches reuse the same identity, cookies, and session state.

export CLAWBROWSER_API_KEY=clawbrowser_xxxxx

# First launch — generates fingerprint via API and caches it
clawbrowser --fingerprint=my_agent_profile --remote-debugging-port=9222

Agent Integration

Connect your automation framework to the CDP endpoint the same way you would with any Chromium build. Fingerprint spoofing and proxy routing are transparent to your agent.

Playwright (Python)

from playwright.async_api import async_playwright

async with async_playwright() as p:
    browser = await p.chromium.connect_over_cdp("http://127.0.0.1:9222")
    page = browser.contexts[0].pages[0]
    await page.goto("https://example.com")
    content = await page.content()

Playwright (Node.js)

const { chromium } = require('playwright');

const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');
const page = browser.contexts()[0].pages()[0];
await page.goto('https://example.com');

Puppeteer

const puppeteer = require('puppeteer');

const browser = await puppeteer.connect({ browserURL: 'http://127.0.0.1:9222' });
const [page] = await browser.pages();
await page.goto('https://example.com');

CLI Reference

# Launch with fingerprint profile
clawbrowser --fingerprint=<profile_id>

# Launch with CDP port for automation
clawbrowser --fingerprint=<profile_id> --remote-debugging-port=9222

# Launch in headless mode
clawbrowser --fingerprint=<profile_id> --headless

# Launch vanilla (no fingerprint, no proxy)
clawbrowser

# List all local profiles
clawbrowser --list

# Regenerate a fingerprint (new identity, preserves cookies/history)
clawbrowser --fingerprint=<profile_id> --regenerate

Output Modes

Default (clean)

Suppresses Chromium noise. Only Clawbrowser status lines are printed.

[clawbrowser] Profile my_agent_profile loaded
[clawbrowser] Proxy verified
[clawbrowser] Fingerprint verified
[clawbrowser] CDP listening on ws://127.0.0.1:9222
[clawbrowser] Browser ready

JSON mode

Pass --output=json for machine-readable newline-delimited JSON events. Parse the ready event to know when the browser is available for automation.

clawbrowser --fingerprint=my_agent_profile --output=json
{"event":"profile_loaded","profile_id":"my_agent_profile"}
{"event":"proxy_verified"}
{"event":"fingerprint_verified"}
{"event":"cdp_ready","url":"ws://127.0.0.1:9222"}
{"event":"ready"}

Verbose mode

Pass --verbose to include full Chromium logs alongside Clawbrowser messages — useful for debugging.

Multi-Profile Management

Each profile carries a unique fingerprint, a dedicated proxy, and isolated browser state (cookies, localStorage, history). Run multiple profiles simultaneously on different CDP ports:

clawbrowser --fingerprint=agent_us_1 --remote-debugging-port=9222 &
clawbrowser --fingerprint=agent_de_1 --remote-debugging-port=9223 &
clawbrowser --fingerprint=agent_uk_1 --remote-debugging-port=9224 &

Tips for AI Agents

  • Reuse profiles for session continuity — cookies and login state persist across launches.
  • Use --output=json to programmatically detect when the browser is ready.
  • Use --skip-verify if your agent handles verification and you want faster startup.
  • One proxy per session — the proxy does not rotate mid-session, which is more realistic for anti-detect purposes.
  • Don't override fingerprint properties via CDP — Clawbrowser handles all spoofing at the engine level. CDP-level overrides may conflict and create detectable inconsistencies.
  • Use descriptive profile IDs like us_residential_1 or de_scraper_main for easier management.

Error Handling

Monitor stdout (or JSON events) for errors. On error the process exits with a non-zero exit code — check it and parse the message to decide whether to retry or alert.

[clawbrowser] Error: CLAWBROWSER_API_KEY not set
[clawbrowser] Error: cannot reach fingerprint API
[clawbrowser] Error: proxy connection failed
[clawbrowser] Error: fingerprint verification failed
[clawbrowser] Error: out of credits, please top up at clawbrowser.ai
← Back to home