captcha

CAPTCHA ソルバースキル

ウェブ自動化ワークフローで CAPTCHA をプログラムから解決します。

トークンベースの CAPTCHA 解決の仕組み

最新の CAPTCHA（reCAPTCHA、hCaptcha、Turnstile）では、歪んだテキストを読み取る必要はありません。解決すると署名付きトークンが発行されます。サードパーティサービスが代わりにチャレンジを解決し、そのトークンを返します。トークンをページに挿入すると、ページはユーザーが解決したものとみなします。

Page with CAPTCHA
    │
    ├─ 1. Extract sitekey + page URL
    ├─ 2. Submit to solving service (waits 15–45s)
    ├─ 3. Receive token string
    ├─ 4. Inject token into hidden field on page
    ├─ 5. Trigger the CAPTCHA callback
    └─ 6. Submit form / continue automation

トークンの有効期限は約 2 分です。送信する直前に解決してください。

---

対応する CAPTCHA の種類

種類	--type フラグ	ページ上での検出方法
reCAPTCHA v2（チェックボックス）	recaptcha-v2	.g-recaptcha div、[data-sitekey] 属性
reCAPTCHA v2（非表示）	recaptcha-v2 --invisible	表示されるウィジェットなし。grecaptcha.execute() の呼び出し
reCAPTCHA v3	recaptcha-v3	JS 内の grecaptcha.execute(sitekey, {action:...})
hCaptcha	hcaptcha	.h-captcha div または [data-hcaptcha-sitekey]
Cloudflare Turnstile	turnstile	.cf-turnstile div
画像／テキスト CAPTCHA	image	src または alt に「captcha」を含む <img>

種類ごとの検出用 JS スニペットと挿入パターンについては、references/captcha-types.md を参照してください。

---

解決サービス

解決サービスの API キーが必要です。以下の 3 つはいずれも同じ API 形式を使用するため、ソルバースクリプトはどのサービスでも動作します。

サービス	フラグ	速度	1,000 件あたりの費用
2captcha（推奨）	--service 2captcha	20～40 秒	約 $1.00
CapMonster Cloud	--service capmonster	10～30 秒	約 $0.60
Anti-Captcha	--service anticaptcha	15～35 秒	約 $0.70

認証情報は環境変数で設定してください（推奨）：

export CAPTCHA_API_KEY=your_key_here
export CAPTCHA_SERVICE=2captcha

登録リンク、無料トライアルの詳細、API の互換性については、references/services.md を参照してください。

---

セットアップ

使用する前に、ソルバースクリプトをプロジェクトにコピーしてください。

# From your project directory — adjust path to match your skill install location
cp ~/.claude/plugins/captcha/scripts/solve_captcha.py ./solve_captcha.py

このスクリプトは Python の標準ライブラリのみを使用するため、pip install は不要です。

クイックスタート：reCAPTCHA v2

同梱スクリプトを使う（推奨）

python solve_captcha.py \
  --type recaptcha-v2 \
  --sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- \
  --pageurl https://www.google.com/recaptcha/api2/demo \
  --api-key $CAPTCHA_API_KEY
# → {"success": true, "token": "03AGdBq25...", "type": "recaptcha-v2"}

Playwright を使った完全なワークフロー（Python）

重要なポイント：ブラウザーを開く前に解決を開始してください。 サービスがトークンを返すまで 15～40 秒かかります。最初に解決呼び出しを開始しておけば、ブラウザーの起動やページへの移動中にバックグラウンドで待機でき、並行処理を活用できます。

import json, os, subprocess, sys
from playwright.sync_api import sync_playwright

SOLVER = "solve_captcha.py"   # must be in same directory or on PATH

def solve(captcha_type, sitekey, pageurl, service=None):
    cmd = [sys.executable, SOLVER,
           "--type", captcha_type,
           "--sitekey", sitekey,
           "--pageurl", pageurl]
    if service:
        cmd += ["--service", service]
    result = subprocess.run(cmd, capture_output=True, text=True, env=os.environ)
    data = json.loads(result.stdout)
    if not data["success"]:
        raise RuntimeError(data["error"])
    return data["token"]

PAGE_URL = "https://www.google.com/recaptcha/api2/demo"
SITEKEY  = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"

# Step 1: start solving (this takes 15–40s) — do it BEFORE opening the browser
token = solve("recaptcha-v2", SITEKEY, PAGE_URL)

# Step 2: now launch and navigate — solve is already done or finishing
with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = browser.new_page()
    page.goto(PAGE_URL)

    # Step 3: inject token — use json.dumps() for safe JS interpolation
    import json as _json
    token_js = _json.dumps(token)
    page.evaluate(f"""
        const token = {token_js};
        const el = document.querySelector('[name="g-recaptcha-response"]');
        if (el) {{ el.value = token; }}
        if (window.___grecaptcha_cfg) {{
            Object.values(window.___grecaptcha_cfg.clients || {{}}).forEach(c => {{
                Object.keys(c).forEach(k => {{
                    if (c[k]?.callback) c[k].callback(token);
                }});
            }});
        }}
    """)

    page.click('#recaptcha-demo-submit')
    browser.close()

重要： JS にトークンを埋め込むときは、必ず json.dumps(token) を使用してください。'{token}' のように f 文字列で直接埋め込むことは避けてください。現在、トークン文字列は base64url で安全に扱えますが、この方法は脆弱です。

---

手順ごとのワークフロー

手順 1 — CAPTCHA の種類を検出して sitekey を抽出する

ブラウザーで（page.evaluate または browser_evaluate 経由で）次の JS を実行します。

(() => {
  const q = s => document.querySelector(s);
  if (q('.g-recaptcha, [data-sitekey]:not(.h-captcha):not(.cf-turnstile)'))
    return { type: 'recaptcha-v2', sitekey: q('[data-sitekey]')?.dataset?.sitekey };
  if (q('.h-captcha, [data-hcaptcha-sitekey]'))
    return { type: 'hcaptcha', sitekey: q('[data-sitekey]')?.dataset?.sitekey };
  if (q('.cf-turnstile'))
    return { type: 'turnstile', sitekey: q('.cf-turnstile')?.dataset?.sitekey };
  if (q('img[src*="captcha" i], img[alt*="captcha" i]'))
    return { type: 'image' };
  return { type: null };
})();

reCAPTCHA v3（表示されるウィジェットがない）の場合は、ページのソースで次を探します。

grecaptcha.execute('SITEKEY', {action: 'ACTION_NAME'})

手順 2 — ソルバースクリプトを実行する

API 呼び出しには必ず solve_captcha.py を使用してください。独自のポーリングループは作成しないでください。このスクリプトは初期待機、再試行、エラーコード、サービスの切り替えを処理します。

# reCAPTCHA v2
python solve_captcha.py --type recaptcha-v2 --sitekey SITEKEY --pageurl URL

# reCAPTCHA v3
python solve_captcha.py --type recaptcha-v3 --sitekey SITEKEY --pageurl URL --action verify

# hCaptcha
python solve_captcha.py --type hcaptcha --sitekey SITEKEY --pageurl URL

# Cloudflare Turnstile
python solve_captcha.py --type turnstile --sitekey SITEKEY --pageurl URL

# Image CAPTCHA (send screenshot of the captcha image)
python solve_captcha.py --type image --image captcha_screenshot.png

手順 3 — トークンを挿入する

CAPTCHA の種類ごとに挿入方法が異なります。各種類に対応する正確な JS については、references/captcha-types.md を参照してください。

reCAPTCHA v2（最も一般的）：

// 1. Set the hidden response field
document.querySelector('[name="g-recaptcha-response"]').value = TOKEN;

// 2. Trigger the registered callback
if (window.___grecaptcha_cfg) {
  Object.values(window.___grecaptcha_cfg.clients || {}).forEach(client => {
    Object.keys(client).forEach(key => {
      if (client[key]?.callback) client[key].callback(TOKEN);
    });
  });
}

---

画像グリッドチャレンジ（ビジョン AI）

reCAPTCHA v2 のチェックボックスをクリックした後に、グリッドが表示されることがあります。例：「信号機がある画像をすべて選択してください」。これは独立した視覚的チャレンジであり、トークンを解決しても対応できません。同梱の solve_image_grid.py はグリッドのスクリーンショットを撮り、ビジョン AI（Claude または GPT-4V）にクリックするセルを判断させます。

Requirements: pip install anthropic   (or openai as fallback)
Environment:  ANTHROPIC_API_KEY  or  OPENAI_API_KEY

仕組み

Checkbox clicked
    │
    ├─ Grid appeared? → screenshot grid cells → ask vision AI → click matching cells
    │                                                          → click Verify
    │                                                          → new round? → repeat
    └─ No grid (trusted IP) → returns True immediately

スクリプトとの統合

from playwright.sync_api import sync_playwright
from solve_image_grid import solve_image_grid  # copy from scripts/

with sync_playwright() as p:
    page = p.chromium.launch(headless=False).new_page()
    page.goto("https://www.google.com/recaptcha/api2/demo")

    # Step 1: click the checkbox (inside its iframe)
    page.frame_locator('iframe[title="reCAPTCHA"]') \
        .locator('.recaptcha-checkbox-border').click()

    # Step 2: handle grid if it appears (returns immediately if no grid)
    solved = solve_image_grid(page)

    if solved:
        page.click('#recaptcha-demo-submit')

組み合わせたフロー（グリッド＋トークンへのフォールバック）

グリッドチャレンジとトークンの両方が必要なページもあります。両方に対応してください。

import json, os, subprocess, sys
from solve_image_grid import solve_image_grid

SOLVER = "solve_captcha.py"
SITEKEY = "your-sitekey"

# 1. Click checkbox — may or may not trigger a grid
page.frame_locator('iframe[title="reCAPTCHA"]') \
    .locator('.recaptcha-checkbox-border').click()

# 2. Solve grid if it appeared
grid_ok = solve_image_grid(page)

# 3. If the form still needs a token (check for g-recaptcha-response being empty)
token_empty = page.evaluate(
    "document.querySelector('[name=\"g-recaptcha-response\"]')?.value === ''"
)
if grid_ok and token_empty:
    result = subprocess.run(
        [sys.executable, SOLVER, "--type", "recaptcha-v2",
         "--sitekey", SITEKEY, "--pageurl", page.url],
        capture_output=True, text=True, env=os.environ
    )
    token = json.loads(result.stdout)["token"]
    token_js = json.dumps(token)
    page.evaluate(f"""
        const t = {token_js};
        document.querySelector('[name="g-recaptcha-response"]').value = t;
        if (window.___grecaptcha_cfg)
            Object.values(window.___grecaptcha_cfg.clients||{{}}).forEach(c=>
                Object.keys(c).forEach(k=>{{ if(c[k]?.callback) c[k].callback(t) }})
            );
    """)

メモ

• 要素のクリックとピクセル座標の比較 — このスクリプトは、ピクセル座標を直接指定するのではなく、frame_locator().locator('td').nth(i) を使ってグリッドのセルをクリックします。さまざまなビューポートサイズや DPI 設定でも、こちらのほうが安定します。
• 複数ラウンドのチャレンジ — Google では通常、2～4 ラウンドが表示されます。このスクリプトは最大 max_rounds=6 まで自動的にループします。
• 「該当なし」のラウンド — AI が []（一致なし）を返した場合でも、スクリプトは Verify をクリックします。Google がこれを受け入れることもあります。
• 精度 — Claude Opus は、明瞭な画像では良好な結果を出します（第 1 ラウンドの精度は約 80～90％）。ぼやけたグリッドや判別しにくいグリッドでは、複数ラウンドが必要になる場合があります。

---

Playwright MCP ツールの使用

Playwright MCP ツール（mcp__plugin_playwright_playwright__*）が利用できる場合：

1. browser_navigate → go to the page
2. browser_evaluate → run detection JS to find CAPTCHA type and sitekey
3. Bash → python scripts/solve_captcha.py ... (takes 15-40s)
4. browser_evaluate → inject token + trigger callback
5. browser_click → submit button
6. browser_snapshot → verify success

---

トラブルシューティング

問題	原因	対処法
トークンを注入しても効果がない	レスポンスフィールドが非表示または無効になっている	表示状態にします：el.style.display='block'; el.removeAttribute('aria-hidden')
送信後に CAPTCHA が再表示される	トークンの有効期限が切れている（2 分超）	解決後、送信の直前にすぐ注入します
ERROR_ZERO_BALANCE	サービスのクレジットがない	サービスのダッシュボードでアカウントに入金します
CAPCHA_NOT_READY のタイムアウト	ソルバーの処理が滞っているか、reCAPTCHA v3 の難易度が高い	再試行するかサービスを切り替えます。v3 では --min-score を上げてみてください
コールバックが呼び出されない	サイトが独自のコールバック名を使用している	ページのソースで .ready(function または grecaptcha.render を検索し、コールバックを見つけます
CAPTCHA を通過してもサイトにブロックされる	ブラウザーのフィンガープリントがボットとして検出されている	references/stealth.md を読んでください
2captcha が誤ったテキストを返す（画像）	画像の品質が低い	CAPTCHA の部分だけを切り抜き、送信前にコントラストを上げます

---

参考ファイル

• scripts/solve_captcha.py — トークンベースの CAPTCHA 用 CLI ソルバー（標準ライブラリのみ。pip のインストールは不要）
• scripts/solve_image_grid.py — reCAPTCHA v2 の画像グリッドチャレンジ用ビジョン AI ソルバー
• references/captcha-types.md — 各 CAPTCHA タイプの検出と注入を行う JS
• references/services.md — サービスの比較、登録、料金、API キー
• references/stealth.md — CAPTCHA を回避した後にボット検出を避ける方法