How to Solve CAPTCHAs in OpenClaw: Step-by-Step Guide with CapSolver Extension

Introduction

When your AI assistant browses the web for you, CAPTCHAs are the number one obstacle. Protected pages block the agent, forms can't be submitted, and tasks stall out waiting for human intervention.

OpenClaw is a personal AI assistant that can browse the web, fill forms, click buttons, and extract data — all through natural language. But like any browser automation, it gets stuck on CAPTCHAs.

CapSolver changes this completely. By loading the CapSolver Chrome extension into OpenClaw's browser, CAPTCHAs are solved automatically and invisibly in the background. No code. No API calls from your side. No changes to how you talk to your AI assistant.

The best part? You don't even need to mention CAPTCHAs to the AI. You just tell it to wait a moment before submitting — and by the time it clicks Submit, the CAPTCHA is already solved.

What is OpenClaw?

OpenClaw is a personal AI assistant you run on your own devices. It answers you on the channels you already use — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Google Chat, Microsoft Teams, and more.

Key Features

• Multi-channel inbox: Talk to your AI from WhatsApp, Discord, Telegram, Slack, and more
• Built-in browser: The agent can open tabs, navigate pages, click buttons, fill forms, and take screenshots
• Local-first: Runs on your own hardware — your data stays with you
• Plugin system: Extend with custom extensions and integrations
• Voice support: Speak to your agent on macOS, iOS, and Android

The Browser Tool

OpenClaw runs a dedicated Chromium browser profile that only the AI agent controls. It's completely isolated from your personal browser. The agent can:

• Open and navigate to any URL
• Read page content and take snapshots
• Click buttons, fill forms, select dropdowns
• Take screenshots and generate PDFs
• Manage multiple tabs

Think of it as giving your AI assistant its own browser window.

What is CapSolver?

CapSolver is a leading CAPTCHA solving service that provides AI-powered solutions for bypassing various CAPTCHA challenges. With support for multiple CAPTCHA types and fast response times, CapSolver integrates seamlessly into automated workflows.

Supported CAPTCHA Types

• reCAPTCHA v2 (image-based & invisible)
• reCAPTCHA v3 & v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA
• Other widely used CAPTCHA and anti-bot mechanisms

Why This Integration is Different

Most CAPTCHA-solving integrations require you to write code — create API calls, poll for results, inject tokens into hidden form fields. That's how it works with tools like Crawlee, Puppeteer, or Playwright.

OpenClaw + CapSolver is fundamentally different:

The key insight: The CapSolver Chrome extension runs inside the agent's browser session. When the agent navigates to a page with a CAPTCHA, the extension detects it, solves it in the background, and injects the token — all before the agent even tries to submit the form.

You just need to give it time. Instead of telling the AI "solve the CAPTCHA", you simply say:

"Go to that page, wait 60 seconds, then click Submit."

That's it. The AI doesn't need to know about CapSolver at all.

Prerequisites

Before setting up the integration, make sure you have:

1. OpenClaw installed and the gateway running
2. A CapSolver account with API key (sign up here)
3. Chromium or Chrome for Testing (see the important note below)

Important: You Need Chromium, Not Google Chrome

Google Chrome 137+ (released mid-2025) silently removed support for --load-extension in branded builds. This means Chrome extensions cannot be loaded in automated sessions using standard Google Chrome. There is no error — the flag is simply ignored.

This affects Google Chrome and Microsoft Edge. You must use one of these alternatives:

How to install Chrome for Testing:

# Option 1: Via Playwright (recommended)
npx playwright install chromium

# The binary will be at a path like:
# ~/.cache/ms-playwright/chromium-XXXX/chrome-linux64/chrome  (Linux)
# ~/Library/Caches/ms-playwright/chromium-XXXX/chrome-mac/Chromium.app/Contents/MacOS/Chromium  (macOS)

# Option 2: Via Chrome for Testing direct download
# Visit: https://googlechromelabs.github.io/chrome-for-testing/
# Download the version matching your OS

After installation, note the full path to the binary — you'll need it for the config.

Step-by-Step Setup

Step 1: Download the CapSolver Chrome Extension

Download the CapSolver Chrome extension and extract it to ~/.openclaw/capsolver-extension/:

1. Go to the CapSolver extension releases on GitHub
2. Download the latest CapSolver.Browser.Extension-chrome-vX.X.X.zip
3. Extract the zip:

mkdir -p ~/.openclaw/capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d ~/.openclaw/capsolver-extension/

4. Verify the extraction worked:

ls ~/.openclaw/capsolver-extension/manifest.json

You should see manifest.json — this confirms the extension is in the right place.

Step 2: Set Your CapSolver API Key

Open the extension's config file at ~/.openclaw/capsolver-extension/assets/config.js and replace the apiKey value with your own:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  // ← your key here
  useCapsolver: true,
  // ... rest of config
};

You can get your API key from your CapSolver dashboard.

Step 3: Configure the Browser

Edit your OpenClaw config file at ~/.openclaw/openclaw.json to enable the browser and load the extension:

{
  "browser": {
    "enabled": true,
    "executablePath": "/path/to/chrome-for-testing/chrome",
    "extensions": [
      "~/.openclaw/capsolver-extension"
    ],
    "noSandbox": true,
    "defaultProfile": "openclaw"
  }
}

Replace /path/to/chrome-for-testing/chrome with the actual path to your Chrome for Testing or Chromium binary. For example:

• Linux (Playwright): ~/.cache/ms-playwright/chromium-1200/chrome-linux64/chrome
• macOS (Playwright): ~/Library/Caches/ms-playwright/chromium-1200/chrome-mac/Chromium.app/Contents/MacOS/Chromium

Note: noSandbox: true is required on most server environments, Docker containers, and CI systems where the Chrome sandbox cannot be initialized. On desktop systems with proper sandboxing, you can omit this.

Step 4: Restart the Gateway

# If using PM2:
pm2 restart opencrawl --update-env

# If running directly:
openclaw gateway restart

Step 5: Verify the Setup

Check the gateway logs to confirm everything loaded correctly:

pm2 logs opencrawl --lines 20 --nostream

You should see these key lines:

[browser/chrome] Loading 1 extension(s)
[browser/chrome] Spawning Chrome: /path/to/chrome-for-testing (args: 15)

Advanced check — verify the extension is active via Chrome DevTools Protocol:

curl -s http://127.0.0.1:8091/json/list

Look for a service_worker entry with chrome-extension:// in the URL:

{
  "title": "Service Worker chrome-extension://cnopfoopenkdblckmekkipihdnambjhf/background.js",
  "type": "service_worker",
  "url": "chrome-extension://cnopfoopenkdblckmekkipihdnambjhf/background.js"
}

If you see this, CapSolver is loaded and running.

How to Use It

This is the most important section. Once setup is complete, using CapSolver with OpenClaw is dead simple.

The Golden Rule

Don't mention CAPTCHAs or CapSolver to the AI. Just give it time before submitting forms.

The AI agent doesn't need to know about CAPTCHAs. The extension handles everything in the background. All you need to do is include a wait time in your instructions so the extension has time to solve the challenge before the form is submitted.

Example 1:

Send this to your OpenClaw agent (via Discord, WhatsApp, Telegram, or any channel):

Go to https://example.com, wait 60 seconds,
then click Submit and tell me what text appears on the page.

What happens behind the scenes:

1. The agent navigates to the reCAPTCHA demo page
2. CapSolver's content script detects the reCAPTCHA widget
3. The extension calls the CapSolver API and solves the challenge (usually within 10-20 seconds)
4. The token is injected into the hidden form field
5. After 60 seconds, the agent clicks Submit
6. The page shows: "Verification Success... Hooray!"

Example 2: Login to a Protected Site

Go to https://example.com/login, fill in the email field with
"[email protected]" and the password with "mypassword123",
then wait 30 seconds and click the Sign In button.
Tell me what page loads after signing in.

Example 3: Submit a Form Behind Turnstile

Open https://example.com/contact, fill in the contact form:
- Name: "John Doe"
- Email: "[email protected]"
- Message: "Hello, I have a question about your services."
Wait 45 seconds, then click Send Message. What confirmation appears?

Recommended Wait Times

Tip: When in doubt, use 60 seconds. It's better to wait a bit longer than to submit too early. The extra wait doesn't affect the result.

Natural Language Patterns That Work

Here are proven phrasings you can use:

• "Go to [URL], wait 60 seconds, then submit the form"
• "Navigate to [URL], fill in [fields], wait 30 seconds, then click [button]"
• "Open [URL] and after about a minute, click Submit and tell me the result"
• "Visit [URL], wait a moment for the page to fully load, then submit"

What NOT to Say

Avoid these — they can confuse the AI or trigger refusals:

• "Wait for the CAPTCHA to be solved" (the AI doesn't know about CAPTCHAs)
• "Use CapSolver to solve the verification" (the AI can't control extensions)
• "Click the reCAPTCHA checkbox" (the extension handles this — clicking may interfere)

How It Works Under the Hood

For the technically curious, here's what happens when the CapSolver extension is loaded:

  Your message                    OpenClaw Gateway
  ───────────────────────────────────────────────────
  "go to page,          ──►  AI Agent receives message
   wait 60s, submit"         │
                              ▼
                         Browser Tool: navigate to URL
                              │
                              ▼
                         Chromium loads the page
                         ┌─────────────────────────────┐
                         │  Page with reCAPTCHA widget  │
                         │                              │
                         │  CapSolver Extension:        │
                         │  1. Content script detects   │
                         │     reCAPTCHA on the page    │
                         │  2. Service worker calls     │
                         │     CapSolver API            │
                         │  3. Token received           │
                         │  4. Token injected into      │
                         │     hidden form field        │
                         └─────────────────────────────┘
                              │
                              ▼
                         AI Agent waits 60 seconds...
                              │
                              ▼
                         Browser Tool: click Submit
                              │
                              ▼
                         Form submits WITH valid token
                              │
                              ▼
                         "Verification Success!"

How the Extension Loads

When OpenClaw's browser starts, it reads the extensions list from your config and passes each path to Chrome via the --load-extension flag. This is the same mechanism Chrome uses for developer extensions — no special plugin system required.

1. Chrome launches with --load-extension=~/.openclaw/capsolver-extension
2. The extension activates — its service worker starts and content scripts are injected into every page
3. On pages with CAPTCHAs — the content script detects the widget, calls the CapSolver API, and injects the solution token into the page

Complete Configuration Reference

Here's a full ~/.openclaw/openclaw.json configuration with the CapSolver extension:

{
  "browser": {
    "enabled": true,
    "executablePath": "/path/to/chrome-for-testing/chrome",
    "extensions": [
      "~/.openclaw/capsolver-extension"
    ],
    "noSandbox": true,
    "defaultProfile": "openclaw"
  }
}

Configuration Options

The CapSolver API key is configured directly in the extension's assets/config.js file (see Step 2 above).

Troubleshooting

Extension Not Loading

Symptom: Gateway logs show Loading 1 extension(s) but no chrome-extension:// targets appear in CDP.

Cause: You're using branded Google Chrome 137+ which silently ignores --load-extension.

Fix: Switch to Chrome for Testing or Chromium. Update browser.executablePath in your config to point to the correct binary.

Verify your Chrome version:

/path/to/your/chrome --version
# Chrome for Testing: "Chromium 143.0.7499.4"
# Branded Chrome: "Google Chrome 143.0.7499.109"

CAPTCHA Not Solved (Form Fails)

Possible causes:

1. Not enough wait time — Increase to 60 seconds
2. Invalid API key — Check your CapSolver dashboard
3. Insufficient balance — Top up your CapSolver account
4. Extension not loaded — See "Extension Not Loading" above

Browser Timeout on First Action

Symptom: The first browser action after a gateway restart times out, but subsequent actions work.

Cause: Chromium cold start + Playwright CDP connection retries can exceed the 20-second tool timeout on the first attempt.

Fix: This is a known issue. Simply retry the command — the second attempt will succeed since the browser is now warm.

Chrome Crashes After Switching Browsers

Symptom: After switching from branded Chrome to Chrome for Testing, the browser crashes with disk cache errors.

Cause: The user data directory was created by a different Chrome version and is incompatible.

Fix: Delete the old browser profile and restart:

rm -rf ~/.openclaw/browser/openclaw/user-data
# Then restart the gateway

Best Practices

1. Always Use Generous Wait Times

More wait time is always safer. The CAPTCHA is usually solved in 5-20 seconds, but network latency, complex challenges, or retries can add time. 30-60 seconds is the sweet spot.

2. Keep Your Messages Natural

Instead of:

"Navigate to URL, wait for captcha solver, then submit"

Use:

"Go to URL, wait about a minute, then submit the form"

Natural phrasing works better with the AI and avoids triggering safety refusals.

3. Monitor Your CapSolver Balance

Each CAPTCHA solve costs credits. Check your balance at capsolver.com/dashboard regularly to avoid interruptions.

4. Use noSandbox on Servers

When running OpenClaw on a remote server, Docker container, or CI environment, always set noSandbox: true in your browser config. The Chrome sandbox requires special kernel capabilities that aren't available in most server environments.

5. Set DISPLAY for Headless Servers

Chrome extensions require a display, even on headless servers. Use Xvfb to create a virtual display:

# Install Xvfb
sudo apt-get install xvfb

# Start a virtual display
Xvfb :99 -screen 0 1280x720x24 &

# Set DISPLAY for OpenClaw
export DISPLAY=:99

Conclusion

The OpenClaw + CapSolver integration represents a fundamentally new approach to CAPTCHA solving. Instead of writing code to detect CAPTCHAs, call APIs, and inject tokens, you simply:

1. Download the extension and add it to your config
2. Point to Chromium (not branded Chrome)
3. Talk to your AI naturally — just include a wait time before form submissions

The CapSolver Chrome extension handles everything else — detecting CAPTCHAs, solving them via the CapSolver API, and injecting tokens into the page. Your AI assistant never needs to know about CAPTCHAs at all.

This is what CAPTCHA solving looks like when you have an AI assistant: invisible, automatic, and zero-code.

Ready to get started? Sign up for CapSolver and use bonus code OPENCLAW for an extra 6% bonus on your first recharge!

FAQ

Do I need to tell the AI about CapSolver?

No. In fact, you should avoid mentioning CAPTCHAs or CapSolver in your messages. The extension works invisibly in the background. Just include a wait time in your instructions (e.g., "wait 60 seconds, then submit") to give the extension time to solve any CAPTCHAs on the page.

Why can't I use regular Google Chrome?

Google Chrome 137+ (released mid-2025) removed support for the --load-extension command-line flag in branded builds. This means Chrome extensions cannot be loaded in automated sessions. You need Chrome for Testing or standalone Chromium, which still support this flag.

What CAPTCHA types does CapSolver support?

CapSolver supports reCAPTCHA v2 (checkbox and invisible), reCAPTCHA v3, Cloudflare Turnstile, AWS WAF CAPTCHA and more. The Chrome extension automatically detects the CAPTCHA type and solves it accordingly.

How much does CapSolver cost?

CapSolver offers competitive pricing based on CAPTCHA type and volume. Visit capsolver.com for current pricing.

Is OpenClaw free?

OpenClaw is open-source and free to run on your own hardware. You'll need API keys for the AI model provider of your choice and, for CAPTCHA solving, a CapSolver account with credits.

How long should I tell the AI to wait?

For most CAPTCHAs, 30-60 seconds is sufficient. The actual solve time is usually 5-20 seconds, but adding extra buffer ensures reliability. When in doubt, use 60 seconds.

Can I use this on a headless server?

Yes. You'll need Xvfb (X Virtual Framebuffer) for the display since Chrome extensions require a display context. Set DISPLAY=:99 and run Xvfb :99 in the background. Also set noSandbox: true in your browser config.