captcha-solver

# 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 3. **CapSolver rejects test/demo sitekeys** (2captcha.com demo keys, `0xFF` test keys) — 2Captcha does not 4. **2Captcha is the better fallback** — accepts all sitekeys including demo/test ones 5. **hCaptcha is the hardest to solve** — both services struggle. Best strategy: avoid or use headed mode 6. **Reddit uses reCAPTCHA v3** — now supported with `solve_recaptcha_v3_2captcha()` 7. **hCaptcha sitekeys are UUIDs** — extracted from page HTML, not from `data-sitekey` attributes 8. **GeeTest takes longest** — 97s average, requires `gt` and `challenge` params extracted from page 9. **ClickSolver is free** — tries clicking Turnstile iframe before spending API credits 10. **Default solver is now 2captcha** — changed from capsolver (which rejects demo/test sitekeys) ## Setup ### Prerequisites ```bash # 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. ```bash 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 ```python 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. ```python # 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. ```bash # 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: ```bash # 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)