セルフホスト版 Steel Browser に CAPTCHA ソルバーを追加する方法

要約

• Steel Local はブラウザセッションを提供しますが、公式の機能一覧には組み込みの CAPTCHA 解決機能は記載されていません。
• 自前でホストした Steel インスタンスから返される WebSocket URL に Python で接続し、現在の Playwright ページを CAPTCHA SDK に渡します。
• 以下のサンプルは実際のローカル Steel サーバーに対して実行され、開発用ページから reCAPTCHA v2 のパラメータを読み取りました。
• パラメータ検出には CapSolver の API キーは不要です。有料の解決には独自の認証情報が必要であり、この例ではテストしていません。
• CAPTCHA 処理の間もブラウザセッションを生かしておき、アプリケーション側の結果を検証してからセッションを解放します。

セルフホストしたブラウザは正しいページまで遷移できても、ワークフローを CAPTCHA 画面で待機させたままにしてしまうことがあります。Steel をローカルで実行している場合、クラウドサービスの “solving” フラグを追加するだけでは不十分です。ローカルとクラウドでは機能が異なります。

このガイドでは、CAPTCHA ソルバをセルフホスト版 Steel Browser にどう組み込むかを示し、簡単な Python の接続チェックを 1 つ紹介します。サンプルではローカル開発用ページと Google 公開の reCAPTCHA テストキーを使用します。サードパーティ Web サイトを対象にはせず、AI モデルも不要です。

Steel Browser の役割とソルバの位置付け

Steel Browser は、Web エージェントや自動化アプリケーションを構築する開発者向けのブラウザ API です。クライアントはおなじみの自動化ツールを通じて、Steel が管理するブラウザセッションを操作できます。公式 Steel リポジトリには、セルフホスト方法や Playwright・Puppeteer・Selenium からの接続方法が記載されています。

正規のフォーム処理フローを構築する開発者にとって、作業の分担はシンプルです。Steel がブラウザを提供し、Playwright がページ遷移と操作を行い、CAPTCHA ソルバが表示された対応済みチャレンジを処理します。そのうえで、アプリケーション側が意図した操作を受け付けたかどうかをワークフローで確認します。

このチュートリアルでは、その CAPTCHA 処理に CapSolver Core SDK を使用します。SDK は Playwright ページを検査し、別個の解決オペレーションを提供できます。これらのコンポーネントをつなぐためにわざわざ LLM を追加する必要はありません。

想定している有用なシナリオは、すでに CAPTCHA 処理が必要なセルフホストブラウザのジョブです。自分が所有するソフトウェアのルーチンテストであれば、CAPTCHA ベンダーのテスト設定で十分な場合もあります。正規のワークフローが実際に必要とするときだけソルバを使い、すべてのブラウザ遷移を有料リクエストに依存させないようにしましょう。

Steel Local に別途 CAPTCHA ステップが必要な理由

Steel Local にはクラウド版の組み込み CAPTCHA 解決機能が含まれていません。Steel の ローカル版とクラウド版の機能比較表では、この 2 つのデプロイが明確に区別されています。

この違いは実装に影響します。クラウド版のチュートリアルでは、セッション作成時に solving を有効化できる場合がありますが、セルフホスト連携では欠けている処理を自前で補う必要があります。クラウド用の設定項目がローカルサーバーでも同じように機能すると決めつけてはいけません。

ここで使う流れは以下のとおりです。

1. ローカルの Steel インスタンス上にセッションを作成する。
2. そのセッションの websocketUrl を読み取る。
3. Steel がすでに管理しているブラウザに Playwright から接続する。
4. そのセッション内のページを CAPTCHA SDK に渡す。
5. 結果を確認してからワークフローを続行する。
6. Steel セッションを解放する。

3 つ目のステップで無関係な別ブラウザを起動するのは避けてください。2 つ目のブラウザは Steel が返したセッションと無関係になるため、実際のジョブが待機しているページとは別のページを検査してしまうリスクがあります。

ローカルサーバーと Python 環境の準備

専用の Steel Local インスタンスを起動し、Python 3.12 を用意します。検証済みの構成は、macOS 上でリポジトリのリビジョン 8362bbd における Steel API 0.5.3、Playwright 1.64.0、および capsolver-core 0.1.1 を使用しました。

ご自身のデプロイに対しては、リポジトリのローカルセットアップ手順に従ってください。この例で使ったソースベースのサーバーでは、API を HOST=127.0.0.1、PORT=3300、CDP_REDIRECT_PORT=9323 で起動しました。これらはテスト環境でのポート選択例であり、必須のデフォルトではありません。開発用 API は、想定したクライアントからのみ到達できるようにしておいてください。

Python の依存パッケージは隔離された環境にインストールします。

python -m pip install "playwright==1.64.0" "capsolver-core==0.1.1" "httpx==0.28.1"

Steel がブラウザを起動するため、このクライアント側では別の Chromium インスタンスを起動しません。Playwright の CDP 接続メソッドは既存の Chromium 系ブラウザにアタッチし、そのデフォルトコンテキストを公開します。

クライアントは、Steel から返される WebSocket アドレスにもアクセスする必要があります。Steel がコンテナ内や別マシンで動いている場合、Python からそのアドレスに到達できることを確認してください。127.0.0.1 は接続を行うマシン自身を指します。

以下の検出チェックには CapSolver の認証情報は不要です。実際に解決を行うには、有効な独自の API キーとアカウント上のリソースが必要です。このガイドでは、有料解決、トークンのページへの書き戻し、アプリケーション側での受け入れは実行していません。これらは本番導入時の検証項目として別途チェックしてください。

Steel を SDK に接続し開発用ウィジェットを確認する

このスクリプトは実際の Steel セッションを作成し、そのブラウザに接続して、公式 SDK を通じて開発用ウィジェットを読み取ります。steel_sdk_check.py という名前で保存し、Python で実行してください。

サンプルはポート 3300 上のローカルサーバーをデフォルトにしています。別アドレスを使う場合は STEEL_URL を設定してください。専用インスタンスを使ってください。セッションの作成と解放は、そのインスタンス上のアクティブなブラウザセッションを変更します。

ページは Playwright のルート経由で供給されるため、ポート 8765 上に Web サーバーを立てる必要はありません。なお、Google のウィジェットスクリプトは引き続きネットワークアクセスを必要とします。公開サイトキーは Google の reCAPTCHA テストガイドに記載されているもので、開発用途向けであり本番用ではありません。

import asyncio
import json
import os

import httpx
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

STEEL_URL = os.environ.get("STEEL_URL", "http://127.0.0.1:3300")
TEST_URL = "http://127.0.0.1:8765/"
HTML = """<!doctype html><html><head><title>Steel CAPTCHA check</title></head>
<body><h1>Owned development page</h1>
<div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</body></html>"""


async def main():
    async with httpx.AsyncClient(base_url=STEEL_URL, timeout=90) as api:
        response = await api.post("/v1/sessions", json={"headless": True})
        response.raise_for_status()
        session = response.json()
        try:
            async with async_playwright() as playwright:
                browser = await playwright.chromium.connect_over_cdp(session["websocketUrl"])
                try:
                    context = browser.contexts[0]
                    page = await context.new_page()
                    await page.route(TEST_URL, lambda route: route.fulfill(
                        content_type="text/html", body=HTML))
                    await page.goto(TEST_URL)
                    await page.wait_for_function(
                        "() => !!window.___grecaptcha_cfg && "
                        "Object.keys(window.___grecaptcha_cfg.clients || {}).length > 0",
                        timeout=30000)
                    async with create_capsolver() as cap:
                        infos = await cap.get_captcha_info(page)
                    result = [{"type": info.type.value,
                               "url": info.website_url,
                               "site_key": info.website_key} for info in infos]
                    print(json.dumps({"session_id": session["id"],
                                      "captcha_parameters": result}))
                    assert result and result[0]["type"] == "reCaptchaV2"
                finally:
                    await browser.close()
        finally:
            released = await api.post(f"/v1/sessions/{session['id']}/release")
            released.raise_for_status()
            print(json.dumps({"released": released.json().get("success")}))


if __name__ == "__main__":
    asyncio.run(main())

実行結果では、ローカルページの URL と公開テストサイトキーを持つ reCaptchaV2 記述子が 1 件返されました。最後の解放レスポンスは true を報告しました。これらにより、実際の Steel セッション・CDP 接続・ページアクセス・SDK によるパラメータ読み取りの経路が確認できます。

一方で、これらは有料 CAPTCHA が解決されたことを示すものではありません。開発用キーは本番チャレンジではなく、このスクリプトも解決トークンを要求していません。

コードは Steel が管理する既存のブラウザコンテキスト内でページを維持します。クリーンアップでは、検出に失敗した場合でもクライアント接続を閉じ、サーバーに対してセッション解放を要求します。これを共有サービス向けに応用する場合は、無関係なジョブ同士が互いのセッションを解放しないよう、どのコンポーネントがセッションのライフサイクルを管理するかを 1 つに決めてください。

同じページで解決処理を追加する

正規のアプリケーションページ上に対応済み CAPTCHA が読み込まれたあと、ブラウザ接続と SDK クライアントがまだ開いている間に、解決呼び出しを追加します。ローカル開発用の疑似環境は独自のアプリケーションワークフローに置き換えてください。テストキーを本番入力として使ってはいけません。

SDK クライアントはドキュメント記載の api_key オプションで作成し、認証情報は承認済みのシークレット設定から読み込みます。CapSolver がチャレンジ要求を処理し、Steel は引き続きブラウザセッションを管理します。

以下の行は、変更していない公式のブラウザモード呼び出しです。設定済み API キーが必要であり、この Steel 接続での有料実行はこのチュートリアルでは未検証です。

results = await cap.solve_on_page(page)

呼び出しは必ずクライアントが生きているコンテキスト内に置いてください。サンプルのクリーンアップ処理のあとに貼り付けてしまうと、閉じたブラウザやクライアントを参照することになります。

ワークフローを続行する前に、返された各結果を検査してください。SDK は error、存在する場合の solution、そして filled による自動入力の有無を報告します。結果が空、または solution が欠けている場合、それをもってアプリケーション側が CAPTCHA を通過したと判断してはいけません。

Core SDK が提供するトークンモードは、reCAPTCHA v2 / v3 と Cloudflare Turnstile をカバーしています。CapSolver 全体の API ドキュメントに列挙されているすべてのチャレンジタイプを、同じ呼び出しで解決できると決めつけてはいけません。reCAPTCHA v2 タスクドキュメントには、そのパスで必要となるタスク固有要件が記載されています。

CAPTCHA ステップ後のワークフロー確認

ワークフローが完了したと言えるのは、アプリケーションが意図した状態に到達したときだけです。トークンレスポンス・ページ上のフィールドへの書き戻し・フォーム送信の成功は、それぞれ別個の観測事項です。

自分が管理するアプリケーションであれば、確認メッセージや想定されたレスポンスなど、具体的な成功シグナルを選びます。通常どおりフォーム操作を行ったあと、そのシグナルを待機します。期待したシグナルが現れない場合、理由もわからないまま解決リクエストだけを繰り返すのではなく、アプリケーション側のレスポンスを調査してください。

処理中はページの同一性を保ってください。解決プロセスの最中にページ遷移したり、タブを閉じたり、セッションを解放してはいけません。アプリケーションがウィジェットをリロードする場合は、以前のページ状態から取得したパラメータを再利用するのではなく、現在のチャレンジを改めて検査してください。

CAPTCHA 用語集では検証の概念を説明しており、CAPTCHA トークンと Cookie の解説は異なる出力の区別に役立ちます。ブラウザの Cookie もトークン文字列も、アプリケーションの成功判定そのものの代わりにしてはいけません。

最初に失敗したステップをトラブルシュートする

トラブルシューティングは、もっとも早い段階で失敗した操作から始めてください。接続問題が原因で不要な解決要求を生まないようにするためです。

診断ログはコンパクトに保ちましょう。記録するのはステージとマスク済みのエラー内容であり、API キー・レスポンストークン・ブラウザストレージ全体などは含めないようにします。まず 1 ページだけでテストし、一時的な障害をリトライで解消できると判断できてから、リトライ処理を追加してください。

セルフホスト統合を完成させる

Steel Local の統合では、管理されたブラウザページから CAPTCHA 処理への明確な引き渡しが必要です。ここで示した動作確認用コードは、有料リクエストを行わずにその受け渡し部分を検証します。本番利用前には、独自の認証情報で解決を検証し、許可された環境でアプリケーション結果を確認してください。

セッションは、そのセッションが引き受けている処理の間だけ開き、処理が終了したら解放します。これにより、トラブルシューティングと将来のパッケージアップグレードの両方に役立つ、明確な境界が確保できます。

CapSolver で信頼性の高い自動化ワークフローを構築する

Steel ワークフロー内のサポート対象 CAPTCHA ステップで CapSolver を接続してください。まずは検証済みの検出パスから始め、その後で認証情報付きの実行を検証し、ワークロードを増やしていきましょう。

CapSolver を試す。キャンペーン条件のもと、ボーナスコード CAP26 を使用すると 5% ボーナスが付与されます。

FAQ

Q: セルフホストした Steel Browser は自動的に CAPTCHA を解決しますか？

いいえ。Steel の公式比較では、Steel Local に組み込み CAPTCHA 解決機能は記載されていません。クラウド版の解決機能は別個の機能です。

Q: この例を試すのに Steel Cloud アカウントは必要ですか？

いいえ。この例は起動済みのローカルインスタンスに接続します。そのインスタンスの起動と運用は、利用者自身の責任です。

Q: Playwright の Chromium を起動するのではなく、CDP 経由で接続する理由は何ですか？

CDP は、Steel が管理するブラウザに Python をアタッチします。別のブラウザを起動すると、この例が利用すべきセッションとは別のセッションが作成されてしまいます。

Q: 検出チェックを行うと CapSolver クレジットは消費されますか？
このチェックはウィジェットのパラメータを読み取るだけで、有料のソルビングリクエストは行いません。別途ソルビングを行う呼び出しには、有効な CapSolver 資格情報が必要です。

Q: ここで有料ソルビングのフロー全体はテスト済みですか？

いいえ。実際の実行では、セッション作成、CDP 接続、SDK 検出、および解放を検証したのみです。有料ソルビング、結果の反映（フィルバック）、およびアプリケーション側での受け入れについては、別途資格情報付きのテストが必要です。

Q: これは公式な Steel とのパートナーシップまたはネイティブ統合ですか？

いいえ。これは Steel の公開ブラウザーインターフェイスと CapSolver の公式 SDK を利用した、接続例のテストです。将来のリリースにおけるパートナーシップや互換性を保証するものではありません。