Imported from clawdbrunner/captcha-solver (SKILL.md). Install upstream with npx skills add clawdbrunner/captcha-solver. Copyright stays with the author.

name: captcha-solver description: Three-layer CAPTCHA handling supporting 30+ CAPTCHA types. Layer 1: CloakBrowser prevents CAPTCHAs. Layer 2: ClickSolver (free) clicks Turnstile checkboxes + ALTCHA/Prosopo auto-solve. Layer 3: 2Captcha/CapSolver API fallback solves everything else. Supports reCAPTCHA v2/v3/Enterprise, hCaptcha, Cloudflare Turnstile, GeeTest, FunCaptcha, Amazon WAF, Friendly Captcha, KeyCaptcha, DataDome, Kasada, Akamai, Imperva, Yandex, VK, Tencent, Lemin, MTCaptcha, CyberSiARA, Cutcaptcha, Capy, atbCAPTCHA, ALTCHA, Prosopo, and image/text CAPTCHAs. ALWAYS use fully automated solving - never ask user to solve manually.

CAPTCHA Solver (30+ Types | CloakBrowser + ClickSolver + 2Captcha/CapSolver)

Three-layer CAPTCHA handling supporting 30+ CAPTCHA types: CloakBrowser prevents CAPTCHAs, ClickSolver/auto-solvers handle free types, 2Captcha/CapSolver solves everything else. Never ask the user to solve CAPTCHAs manually.

Architecture

Layer 1: CloakBrowser (FREE — prevents CAPTCHAs)
├─ 57 C++ source-level patches on Chromium 146
├─ 0.9 reCAPTCHA v3 score (human-level)
├─ Passes Cloudflare Turnstile auto-resolve
├─ humanize=True defeats behavioral detection
└─ Cost: $0 per request

Layer 2: Free Solvers (NO API KEY NEEDED)
├─ ClickSolver — clicks Turnstile iframe checkbox
├─ ALTCHA — local proof-of-work (SHA-256)
├─ Prosopo Procaptcha — click-based widget
└─ Cost: $0 per attempt

Layer 3: 2Captcha / CapSolver (FALLBACK — solves CAPTCHAs)
├─ 2Captcha: 20+ CAPTCHA types
├─ CapSolver: 12+ CAPTCHA types (fallback)
├─ See Supported Types table below
└─ Cost: ~$3/1000 solves

Test Results (2026-05-12)

Sites where CloakBrowser prevents CAPTCHAs entirely (Layer 1)

Solver results (Layer 2)

solvecaptcha.com demo results (2026-05-12)

8/8 solved. 2Captcha handles all standard CAPTCHA types reliably.

2captcha.com demo results (2026-05-20)

Key Lessons

1. CloakBrowser handles ~80% of CAPTCHAs by prevention — most sites never trigger a challenge
2. Use fresh browser instances per site — long sessions crash (Chromium memory leak). Exception: OIDC/SSO flows — keep the same instance through the full login → redirect → target app chain so cookies carry through
3. OIDC/SSO multi-redirect flows work — login at the identity provider, then navigate to the OIDC-protected app. The same browser session carries cookies/auth through the entire redirect chain (tested: ElfHosted store → auth.elfhosted.party → filebrowser)
4. Page.evaluate() only takes 1 arg — CloakBrowser's Playwright binding doesn't support extra positional arguments like standard Playwright's page.evaluate(js, arg1, arg2). Use string interpolation or page.evaluate("async () => { ... }") with values baked into the JS string instead
5. CapSolver rejects test/demo sitekeys (2captcha.com demo keys, 0xFF test keys) — 2Captcha does not
6. 2Captcha is the better fallback — accepts all sitekeys including demo/test ones
7. hCaptcha is the hardest to solve — both services struggle. Best strategy: avoid or use headed mode
8. Reddit uses reCAPTCHA v3 — now supported with solve_recaptcha_v3_2captcha()
9. hCaptcha sitekeys are UUIDs — extracted from page HTML, not from data-sitekey attributes
10. GeeTest takes longest — 97s average, requires gt and challenge params extracted from page
11. ClickSolver is free — tries clicking Turnstile iframe before spending API credits
12. Default solver is now 2captcha — changed from capsolver (which rejects demo/test sitekeys)

Setup

Prerequisites

# Python venv with cloakbrowser + requests
cd ~/clawd
source .venv/bin/activate
# Already installed: cloakbrowser, requests, playwright

API Keys (already configured)

• CapSolver — ~/.config/capsolver/api_key (balance: ~$6)
• 2Captcha — ~/.config/2captcha/api_key (balance: ~$3)

Usage

Method 1: StealthBrowser (Recommended)

All-in-one: CloakBrowser + auto-detect + auto-solve.

source ~/clawd/.venv/bin/activate
export PYTHONPATH=~/clawd/skills/captcha-solver/scripts

# Navigate to a protected site (auto-handles CAPTCHAs)
python3 stealth_browse.py --url "https://protected-site.com"

# Check if CAPTCHA is present
python3 stealth_browse.py --url "https://protected-site.com" --output detect

# Get full page HTML
python3 stealth_browse.py --url "https://protected-site.com" --output html

# Get page text
python3 stealth_browse.py --url "https://protected-site.com" --output text

Method 2: StealthBrowser in Python code

import sys
sys.path.insert(0, '/Users/clawdbrunner/clawd/skills/captcha-solver/scripts')
from stealth_browse import StealthBrowser

sb = StealthBrowser(headless=True, humanize=True, auto_solve=True)
# Default solver is now 2captcha. Override with prefer="capsolver" if needed.
page = sb.navigate("https://protected-site.com")
# page is ready — CAPTCHAs handled automatically
title = page.title()
content = page.content()
sb.close()

⚠️ Important: Create a new StealthBrowser instance for each site to avoid Chromium crashes.

Exception for OIDC/SSO flows: When a target app requires login through an identity provider (e.g., OAuth2/OIDC redirect chains), keep the same StealthBrowser instance through the entire flow. Login at the identity provider first, then navigate to the target app — the session cookies carry through automatically.

# OIDC flow pattern (same browser instance)
sb = StealthBrowser(headless=True, humanize=True, auto_solve=True)
page = sb.navigate("https://id-provider.example.com/login")
# ... fill credentials, submit ...
page.goto("https://protected-app.example.com/")  # OIDC redirect chain uses same session
# Now authenticated at the target app
sb.close()

Method 3: Manual scripts (legacy)

For when you already have a browser session and just need to solve a CAPTCHA.

# reCAPTCHA v2 via 2Captcha
python3 scripts/solve_recaptcha_v2.py --sitekey SITEKEY --pageurl URL

# reCAPTCHA via CapSolver
python3 scripts/solve_capsolver.py --sitekey SITEKEY --pageurl URL

# Image grid
python3 scripts/solve_capsolver.py --image screenshot.png --question "traffic lights"

Supported CAPTCHA Types (30+)

Default solver: 2Captcha (accepts all sitekeys, tested 8/8)

Solver priority:

1. Free solvers (ClickSolver, ALTCHA, Prosopo) — no API key needed
2. 2Captcha (default, broadest type support)
3. CapSolver (fallback, some types not supported)

Full API-Supported Types

Detection-Only Stubs (detected but not yet fully solvable)

Integration with OpenClaw Browser Tool

When using the browser tool (not CloakBrowser), use manual solve scripts:

# 1. Detect CAPTCHA
browser action=snapshot -> check for reCAPTCHA/hCaptcha iframe

# 2. Extract sitekey
browser action=act request='{"kind":"evaluate","fn":"document.querySelector(\"[data-sitekey]\").getAttribute(\"data-sitekey\")"}'

# 3. Solve
TOKEN=$(python3 scripts/solve_recaptcha_v2.py --sitekey "$SITEKEY" --pageurl "$URL")

# 4. Inject
browser action=act request='{"kind":"evaluate","fn":"document.getElementById(\"g-recaptcha-response\").innerHTML=\"'"$TOKEN"'\""}'

# 5. Submit
browser action=act request='{"kind":"click","ref":"submit_button_ref"}'

Troubleshooting

"the sitekey is not supported"

• CapSolver rejects test/demo sitekeys and some domains
• Switch to 2Captcha as fallback

"Invalid input, please check captcha type"

• Likely using wrong task type (e.g., v2 solver on v3 CAPTCHA)
• Try ReCaptchaV3TaskProxyLess instead of ReCaptchaV2TaskProxyLess

"Page crashed"

• Chromium memory issue — create a new StealthBrowser instance
• Don't reuse browser across many sites

hCaptcha timeout

• hCaptcha is intentionally harder to solve
• Try headed mode (headless=False) or increase timeout
• Consider if the site truly requires automation

"No module named 'requests'"

• Activate the venv: source ~/clawd/.venv/bin/activate

Script Reference

Costs & Balances

• 2Captcha: ~$3/1000 solves (current balance: ~$3)
• CapSolver: ~$3/1000 solves (current balance: ~$6)
• Check: https://2captcha.com/setting | https://dashboard.capsolver.com

Reference Documentation

• references/2captcha-api.md — Full 2Captcha API docs, error codes, pricing
• CloakBrowser: https://github.com/CloakHQ/CloakBrowser
• CapSolver docs: https://docs.capsolver.com