How to bypass captcha in OpenClaw

Learn how to set up automated CAPTCHA solving in your local OpenClaw AI assistant using the 2Captcha browser extension. A step-by-step zero-code guide, Chromium setup, and AI prompting tips.

OpenClaw is a powerful personal AI assistant that you can host on your own hardware. One of its standout features is its multi-channel inbox: you can communicate with your agent via familiar interfaces like WhatsApp, Telegram, Discord, Slack, Signal, or iMessage.

The workflow is straightforward: you simply drop a link to your Telegram bot and ask it to perform a task. The agent spins up a hidden, isolated Chromium browser profile, navigates to the site, analyzes the content, fills out forms, and clicks buttons. However, during web automation, the bot inevitably hits a brick wall—CAPTCHAs—and the process stalls.

Traditionally, bypassing CAPTCHAs requires writing custom scripts and making API calls. But OpenClaw’s architecture allows for an elegant zero-code approach: integrating the official 2Captcha browser extension. The extension runs in the background, automatically detects CAPTCHAs, and injects the solution token.

Supported CAPTCHA Types

Integrating the 2Captcha extension into the OpenClaw environment ensures automated bypass for the following security mechanisms:

• Image (Picture)
• reCAPTCHA V2 (including invisible)
• reCAPTCHA V3
• Cloudflare Turnstile
• Cloudflare Challenge
• Arkose Labs (FunCaptcha)
• GeeTest

Crucial Technical Requirement: Choosing the Right Browser

Starting with Google Chrome version 137+ (mid-2025), developers silently dropped support for the --load-extension flag in standard consumer builds. This means a regular Google Chrome or Microsoft Edge installation will simply ignore any attempts to load an extension during an automated session.

For this to work, you must use alternatives that still support extensions:

• Chrome for Testing
• Standalone Chromium
• The Chromium build bundled with Playwright.

Step-by-Step 2Captcha Integration in OpenClaw

Step 1: Prepare the 2Captcha Extension

Download the 2Captcha extension archive for Chromium-based browsers and unpack it into a directory accessible by the OpenClaw daemon. Recommended path: ~/.openclaw/2captcha-extension/.

Step 2: Configure the API Key

Since the AI drives the browser in headless mode, you won't be able to manually enter your API key via the extension's popup UI. Open the extension's configuration file (usually assets/config.js) and hardcode your 2Captcha API key directly into the code.

Step 3: Configure the OpenClaw Gateway

Open your main config file at ~/.openclaw/openclaw.json. You need to point it to the correct browser binary and pass the extension directory:

{
  "browser": {
    "executablePath": "/path/to/chrome-for-testing/chrome",
    "extensions": [
      "/home/user/.openclaw/2captcha-extension"
    ],
    "noSandbox": true,
    "defaultProfile": "chrome"
  }
}

Note: The noSandbox: true parameter is strictly required when running on servers, in Docker containers, or CI environments where the Chrome sandbox lacks the necessary Linux kernel privileges.

Step 4: Advanced Extension Loading Check

Restart the OpenClaw gateway (pnpm openclaw gateway start).

Instead of just blindly checking the logs, developers can accurately verify that the extension loaded by querying the Chrome DevTools Protocol (CDP) directly. Run the following command:

curl -s http://localhost:9222/json

If the JSON response includes a service_worker with a URL starting with chrome-extension://, the integration was successful—the 2Captcha extension is active and monitoring pages.

Prompting Strategy: How to Guide the AI Correctly

The key takeaway of this setup is that the AI agent doesn't need to know that a CAPTCHA or the 2Captcha extension even exists.

The extension loads with the browser and works entirely autonomously. All you need to do is give the extension enough time to do its job before the AI attempts to click the "Submit" button.

The Golden Rule (Examples of Correct Commands)

"Navigate to the login page, fill in the fields with my data, wait for 60 seconds, and then click Submit."

"Open this URL, wait about a minute for the page to fully load, then submit the form and tell me the result."

The recommended wait time is between 30 and 60 seconds. Adding this delay won't hurt the execution logic, but it guarantees that even on a slow network connection, the 2Captcha token will be successfully injected into the hidden field.

Anti-Patterns: What NEVER to Tell the Agent

Avoid the following phrases—they are guaranteed to confuse the AI or cause logic errors:

• ❌ "Wait for the CAPTCHA to be solved" (The OpenClaw agent doesn't understand what a CAPTCHA is on the page).
• ❌ "Use the extension to pass verification" (The agent doesn't know how to manage browser extensions).
• ❌ "Click the reCAPTCHA checkbox" (The most common mistake: the agent will try to manually click the widget, which interrupts the 2Captcha background scripts that are already handling it).

Troubleshooting Common Issues

1. Critical Error: Browser Profile Conflict After Updating
When users switch from standard Google Chrome to Chrome for Testing (to bypass the v137+ restrictions), the browser often crashes with disk cache errors. This happens because the old user data folder is completely incompatible with the new binary.

• Solution: Clear the old browser profile before launching:
  bash Copy

  rm -rf ~/.openclaw/browser-data

2. Timeout on the First Action (Cold Start)
During a cold start of Chromium and the initialization of the CDP connection, the very first action might exceed OpenClaw's default 20-second timeout.

• Solution: This is a known behavior. Just repeat your command in the chat—it will execute instantly on the already "warmed-up" browser.

3. The Extension Won't Load
If DevTools doesn't show the extension, make sure you aren't using a standard consumer build of Google Chrome 137+, which silently ignores the --load-extension flag. Double-check your path in the executablePath variable.

4. Running on Headless Servers without a Monitor (Linux)
Chrome extensions absolutely require a graphical environment to run, even if the browser is operating in the background on a Linux server.

Solution: Use Xvfb to create a virtual display before starting the gateway:

DISPLAY=:99 xvfb-run pnpm openclaw gateway start