# Captcha Solver

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

- Skill: `clawdbrunner/captcha-solver` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add clawdbrunner/captcha-solver`
- Raw SKILL.md: https://api.skillmd.com/api/skills/clawdbrunner/captcha-solver/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: clawdbrunner (https://skillmd.com/u/clawdbrunner)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/clawdbrunner/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)
- **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