captcha-solver

---

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)

Site	Previous Issue	CloakBrowser Result
Google Search	IP-level CAPTCHA (May 5)	✅ No CAPTCHA
Google Accounts	reCAPTCHA on OAuth (Apr 16-19)	✅ No CAPTCHA
MyFitnessPal	Cloudflare Turnstile (Apr 2)	✅ No CAPTCHA
LinkedIn Login	—	✅ No CAPTCHA
ClosedRouter Portal	Cloudflare detection	✅ No CAPTCHA
Discord Login	—	✅ No CAPTCHA
Best Buy	Cloudflare	✅ No CAPTCHA
ElfHosted Store (store.elfhosted.com)	Cloudflare bot detection	✅ No CAPTCHA
ElfHosted OIDC (auth.elfhosted.party)	Cloudflare + OIDC redirect chain	✅ No CAPTCHA
HuggingFace Join	hCaptcha (Apr 22)	⚠️ hCaptcha still present
Reddit Login	—	⚠️ reCAPTCHA on login form

Solver results (Layer 2)

CAPTCHA Type	Service	Result	Notes
reCAPTCHA v2 (2captcha demo)	2Captcha	✅ Solved in 15s	"Captcha is passed successfully!"
reCAPTCHA v2 (Reddit)	CapSolver	❌ Invalid captcha type	Reddit uses v3, not v2
hCaptcha (HuggingFace)	CapSolver	❌ Site not supported	CapSolver blocks this domain
hCaptcha (HuggingFace)	2Captcha	❌ Timeout >100s	hCaptcha is much harder to solve

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

CAPTCHA Type	Service	Result	Time
Image CAPTCHA	2Captcha	✅ Solved	58s
reCAPTCHA v2	2Captcha	✅ Solved	5s
reCAPTCHA v3	2Captcha	✅ Solved	5s
reCAPTCHA v2 Callback	2Captcha	✅ Solved	43s
reCAPTCHA v2 Invisible	2Captcha	✅ Solved	37s
Cloudflare Turnstile	2Captcha	✅ Solved	5s
GeeTest CAPTCHA	2Captcha	✅ Solved	97s
Text CAPTCHA	2Captcha	✅ Solved	21s

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

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

CAPTCHA Type	Service	Result	Time	Notes
reCAPTCHA v2	2Captcha	✅ Solved	5s
reCAPTCHA v2 Enterprise	2Captcha	✅ Solved	62s	NEW
reCAPTCHA v3	2Captcha	✅ Solved	5s
Cloudflare Turnstile	2Captcha	✅ Solved	5s
MTCaptcha	2Captcha	✅ Solved	5s	NEW
Normal Image	2Captcha	✅ Solved	~30s	Fixed SVG skip bug
hCaptcha	—	✅ Detected	—	HuggingFace
GeeTest v4	—	✅ Detected	—	Real demo
KeyCAPTCHA	—	✅ Detected	—	Demo is docs-only
Lemin	—	✅ Detected	—	Demo is docs-only

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

#	CAPTCHA Type	2Captcha	CapSolver	Notes
1	reCAPTCHA v2	✅ userrecaptcha	✅ ReCaptchaV2TaskProxyLess	~5s
2	reCAPTCHA v3	✅ userrecaptcha&version=v3	✅ ReCaptchaV3TaskProxyLess	~5s
3	reCAPTCHA Enterprise	✅ userrecaptcha&enterprise=1	✅ ReCaptchaV2EnterpriseTaskProxyLess	Google paid version
4	Cloudflare Turnstile	✅ turnstile	✅ AntiTurnstileTaskProxyLess	~5s, ClickSolver first
5	hCaptcha	✅ hcaptcha	✅ HCaptchaTaskProxyLess	Hard, often fails
6	GeeTest	✅ geetest	—	~97s
7	FunCaptcha / Arkose Labs	✅ funcaptcha	✅ FunCaptchaTaskProxyLess	Interactive puzzles
8	Amazon WAF	✅ amazon_waf	✅ AntiAwsWafTaskProxyLess	Cookie-based
9	Friendly Captcha	✅ friendly_captcha	✅ FriendlyCaptchaTaskProxyLess	EU privacy CAPTCHA
10	KeyCaptcha	✅ keycaptcha	✅ KeyCaptchaTaskProxyLess	Drag-piece puzzles
11	Image/Text CAPTCHA	✅ base64	—	21-58s, screenshot-based
12	DataDome	✅ datadome	✅ DataDomeSliderTaskProxyLess	Bot protection
13	Kasada	—	✅ KasadaTaskProxyLess	Anti-bot
14	Akamai BMP	—	✅ AntiAkamaiBmpTaskProxyLess	Enterprise anti-bot
15	Imperva/Incapsula	—	✅ AntiIncapsulaTaskProxyLess	WAF
16	Yandex SmartCaptcha	✅ yandex	—	Russian sites
17	VK Captcha	✅ image-based	—	Russian social
18	Tencent Captcha	✅ tencent	—	Chinese sites
19	Lemin CAPTCHA	✅ lemin	✅ LeminTaskProxyLess	Slider/puzzle
20	MTCaptcha	✅ mt_captcha	—	Enterprise
21	CyberSiARA	✅ cybersiara	—	AI-themed
22	Cutcaptcha	✅ cutcaptcha	—	Image puzzle
23	Capy CAPTCHA	✅ capy	—	Japanese
24	atbCAPTCHA	✅ atb_captcha	—	Russian
25	ALTCHA	🆓 Local PoW	—	FREE, no API key
26	Prosopo Procaptcha	🆓 Click-based	—	FREE, no API key

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

#	CAPTCHA Type	Status
27	Yidun/NECaptcha (NetEase)	🔍 Detected, solver TBD
28	Alibaba Cloud Captcha	🔍 Detected, solver TBD
29	Binance Captcha	🔍 Detected, solver TBD
30	Temu CAPTCHA	🔍 Detected, solver TBD
31	CaptchaFox	🔍 Detected, solver TBD
32	Hunt CAPTCHA	🔍 Detected, solver TBD

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

Script	Purpose	Usage
stealth_browse.py	CloakBrowser + auto-detect + auto-solve	Main entry point
solve_recaptcha_v2.py	reCAPTCHA v2 via 2Captcha	Legacy standalone
solve_capsolver.py	reCAPTCHA + grids via CapSolver	Legacy standalone
solve_recaptcha_grid.py	Image grid via 2Captcha	Legacy standalone

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