AIエージェントのCAPTCHAがローカル環境では動作するがクラウドでは失敗する場合の対処法

要約

• CAPTCHA 処理がローカルでは動くのにクラウドでは失敗する場合、エージェントのプロンプトを変える前に、デプロイされたランタイムとブラウザを比較する。
• デスクトップブラウザにインストールした拡張機能は、クラウドワーカーやリモートサービスが作成したブラウザには自動では入らない。
• CapSolver のブラウザ向け Core SDK メソッドには Playwright 依存関係が必要であり、トークンのみのインストールでは同じ機能は得られない。
• ヘッドレスモードだからといって拡張機能が必ず使えないわけではない。Playwright は対応する Chromium セットアップを文書化しており、マネージドブラウザもそれぞれ固有の機能を持つ。
• 実際にソルバーを呼び出すプロセスで、認証情報と外向き接続を確認し、そのプロセスが意図したページを制御していることを検証する。
• 許可された 1 つのタスクを再現し、1 つのデプロイ差分を修正し、定期実行を再開する前にアプリケーションの最終結果を確認する。

AI エージェントは開発マシンでは CAPTCHA を処理できるのに、デプロイ後は同じステップで止まることがある。モデルは変わっていないかもしれない。足りないのはもっと単純な要素である可能性が高い。クラウドのイメージに依存関係がない、ブラウザに拡張機能がない、あるいはワーカーが設定された API キーを読み取れない、などだ。

CapSolver には複数の CAPTCHA 連携パスがあり、エージェントをクラウドに移動させると、実際に動作しているパスが変わることがある。本ガイドでは、ローカルでは動作している実行と、デプロイ後に失敗している実行を比較する。これは新しいフレームワークを統合するためではなく、既存の認可済みワークフローを対象としている。追加ツールやエージェントの再構築をせずに、再現可能な環境差分を見つけることが目的である。

まずローカルとクラウドのデプロイ差分から始める

最も手早い出発点は、各実行で使われたブラウザ、ソルバーハンドラー、認証情報、およびページを横並びで記録することである。

「ローカル」とは、ブラウザはリモートホスト上にありつつも、エージェントプロセスがローカルで動いている状況を指すこともある。「クラウド」とは、自前の仮想マシン、コンテナ、あるいはマネージドブラウザサービスを指し得る。これらの構成は異なる制御手段を持つため、ラベルに頼るのではなく、実際のコンポーネント名で記述する。

直近のローカルでの成功実行と、クラウドでの失敗実行について、次を記録する：

コンポーネント	比較すべき項目
ブラウザ	実行ファイルまたはマネージドサービス、バージョン、起動モード、セッション識別子
CAPTCHA ハンドラー	拡張機能、直接 API、Core SDK、エージェントツール、マネージドブラウザ機能
ランタイム	インストールされているパッケージのバージョンとオプション依存関係
認証情報	実行中プロセスが意図したシークレットのバージョンを受け取っているか
ネットワーク	どのコンポーネントがソルビング API、プロキシ、対象ページへ到達する必要があるか
ページ	最終 URL、選択されたタブ、チャレンジタイプ、ナビゲーションタイミング

これは設定と観測結果の比較であり、ブラウザプロファイル全体のエクスポートを要求するものではない。トークン、パスワード、Cookie、プライベートなページ内容はマスクすること。

可能であれば、両方の観測において同じ小さな・許可されたブラウザタスクを使用する。対象 URL、タスク、アプリケーション状態が異なる場合は、その差分も記録する。そうしないと、ページ側の変更をデプロイの退行と誤認しかねない。

ソルバーがデプロイ先のブラウザに到達しているか確認する

デスクトップブラウザにすでに CAPTCHA ハンドラーがあっても、クラウドブラウザには別途機能する CAPTCHA ハンドラーが必要である。

典型的な開発環境では、手動インストールした拡張機能と、同じブラウザを制御するエージェントを組み合わせている。クリーンなデプロイは、その拡張機能インストールを継承しない。ワーカーがどのブラウザを作成または接続しているかを確認し、サポートされている管理インターフェースから、そのブラウザの拡張機能またはツール設定を調べる。

CapSolver 拡張機能イントロダクション にセットアップと設定が説明されている。対象のバージョンが存在し、関連ページで有効化され、そのインターフェースが要求するアカウント情報で設定されているかを確認する。別のブラウザプロファイルで拡張機能が成功していることは、クラウドセッションに関する証拠にはならない。

自分で Chromium を起動する場合

ブラウザ自動化ライブラリの最新の拡張機能要件に従う。

Playwright の 拡張機能ドキュメント では、永続コンテキストを持つ Chromium を指定し、拡張機能のサイドロードには Playwright 同梱の Chromium を推奨している。また、ヘッドレスモードで拡張機能をサポートする Chromium チャンネルについても文書化している。したがって「ヘッドレスだと拡張は使えない」というのは一般的な診断として信頼できない。

ヘッドレスブラウザ とは、表示インターフェースなしで動作するブラウザのことである。ここで重要なのは、どの実行ファイルと起動設定を使っているか、その組み合わせが拡張機能をサポートしているか、という点だ。クラウド上のジョブをすべて可視ブラウザに切り替えても、拡張機能パッケージの欠如や誤ったブラウザ接続は修正されない。

デプロイで実際に使われている起動オプションとブラウザインストールを、公式の最新サンプルと照合する。診断実行の間は、その既知の構成を維持する。

プロバイダがブラウザを起動する場合

デスクトップのインストール手順がリモートにも適用できると決めつけず、プロバイダが文書化している拡張機能や CAPTCHA 機能を用いる。

プロバイダは、拡張機能アップロード手段、組み込みのソルビング機能、あるいはそうした制御を持たないブラウザ接続手段を提供している可能性がある。利用している特定サービスとアカウント設定について、サポートされている経路を確認する。すべてのホスト型ブラウザが自動 CAPTCHA 処理を備えていると決めつけてはならないし、既存のハンドラーを理解せずに二重にハンドラーを追加するべきでもない。

既存の Browser Use ローカル・クラウドガイド は、該当フレームワークの選択肢を説明している。ここでの診断原則はより広く当てはまる：失敗している実行で使われているブラウザに、実際にどのハンドラーが存在するのかを特定することだ。

インストールされている依存関係と利用可能なメソッドを比較する

デプロイされたパッケージはトークンリクエストには対応していても、ローカルコードが想定しているブラウザ依存メソッドを欠いている可能性がある。

CapSolver Core SDK ドキュメント では、トークンモードとブラウザ向け操作とを区別している。検出やページ操作などのブラウザメソッドには、任意依存として Playwright が必要であると明記されている。「CapSolver」という名前のパッケージが存在するかだけでなく、デプロイ時のマニフェストと実際にインストールされているパッケージを、成功している環境と比較する。

失敗が import や依存関係欠如のエラーであれば、CAPTCHA 自体を調べる前にそれを解決する。メソッドは動作するがチャレンジが存在しないと報告する場合は、クラウド環境でチャレンジタイプが変わったと決めつける前に、選択されているページとタイミングを確認する。

エージェントツールを使う場合、デプロイされたワーカーでツールが登録されているか確認する。ノートブックや開発プロセスでローカルに登録したツールは、新しく起動したサービスには自動で設定されない。公開されているツール名を 公式 agent-tools リファレンス と比較し、使用しているサンプルとインストールバージョンを揃える。

この確認のために新しいアダプタを導入する必要はない。まず、意図したハンドラーが利用可能であり、既存の統合が期待する引数を受け取っているかを確認する。

CapSolver ボーナスコードを利用する

自動化予算をすぐに増やそう！
CapSolver アカウントにチャージする際にボーナスコード CAP26 を使用すると、すべてのリチャージで追加 5% ボーナス が無制限でもらえます。
今すぐ CapSolver ダッシュボード から引き換えましょう。

実行プロセスでの認証情報とネットワークアクセスを検証する

ソルバーを呼び出すプロセスは、正しい認証情報とサービスへ到達する権限を持っていなければならない。

開発用シェル、アプリケーションコンテナ、バックグラウンドワーカーでは、受け取る環境変数が異なる場合がある。値を直接出力せずに、ランタイムのサポートする設定または診断機能を通じてシークレットの存在を確認する。プラットフォームに応じて、設定変更後にワーカーの再起動や再デプロイが必要な場合は、それを実行しているか確認する。

実際のエラー内容を確認する。CapSolver の エラーリファレンス では、アカウントキー、残高、タスクデータ、サービスエラーが区別されている。API に到達していないリクエストは、別のネットワーク問題である。ブラウザパッケージを増やしても、アカウントキーの欠如や外向き接続の拒否は解消されない。

ワークフローでプロキシを使用している場合、どこで設定されているかを特定する。ブラウザのプロキシ、ソルバータスクのプロキシ、API クライアントが使うネットワークプロキシは、それぞれ異なる接続を担当する。タスクドキュメントが必要とする場合にのみ比較し、1 つの設定が 3 つすべてに自動で伝搬すると考えないこと。

コンテナやリモートワーカーの場合、「ローカルアドレス」が何を意味するかも確認する。localhost 上のエンドポイントは、呼び出し元自身の環境を指す。ノート PC 上で動作しているブラウザサービスは、別マシンから同じローカルエンドポイントとしては到達できない。ブラウザデバッグ用エンドポイントを外部公開するのではなく、デプロイ側がサポートしているプライベート接続方式を用いる。

ハンドラーが正しいページに紐づいていることを確認する

ソルバーは、チャレンジが存在するライブページ上で動作している必要があり、古いタブや新たに作られた空のコンテキストで動作していてはならない。

リモートブラウザ接続コードは、エージェントが実際に使っているページを選択しなくても、「接続成功」となることがある。ハンドラーを呼び出す前に現在のページ URL とブラウザセッションを記録し、戻ってきたときにも再確認する。特にエージェントがナビゲーション、タブの追加、ブラウザの再起動などを待機中に行う可能性がある場合は重要だ。

Playwright の BrowserType API リファレンス では、Chromium 専用の CDP パスを含むブラウザ接続メソッドと、その Playwright プロトコル接続に比べた忠実度の低さが説明されている。これらの接続パスは、それぞれ異なる制限を伴う文書化された選択肢として扱う。ローカル起動と任意のリモートアタッチが、同一の挙動を提供すると想定してはならない。

診断中はページの変化を可視のままに保つ

1 つのチャレンジを調べている間は、関係のないエージェントの動作を一時停止する。リフレッシュやコンテキストの置き換えにより、遅れて返ってきた結果が、すでに過去のページ状態を指すことがある。

仮に、あるクラウドワーカーがスクリーンショット用に 2 番目のタブを開き、そのタブを CAPTCHA ハンドラーに渡してしまうとする。API キー、モデル、パッケージが正しくても、検出は失敗する。この場合に決定的なのは、ハンドラーに渡されたページである。「もっと頑張って」とプロンプトを変えても、タブ選択ミスは直らない。

もう 1 つの仮想的なデプロイでは、ツール呼び出しごとに新しいブラウザが起動されるとする。その場合、ソルブステップと次のアプリケーションステップは別々のセッションで実行される。修正すべきは、その操作を通じて意図したブラウザ所有権を維持することであり、統合側でサポートされている接続ライフサイクルを用いることだ。

これらはあくまで構成ミスの可能性の一例であり、特定のインシデントを測定したものでも、すべてのエージェントフレームワークに関する主張でもない。

すべてをリトライに変えずにタイミングを確認する

クラウドデプロイでは、キューイングやブラウザ起動時間が追加され得るため、タスク全体を延長する前に、失敗しているステップのタイムスタンプを比較する。

ブラウザ起動、ページロード、ソルバーへの送信、ソルバー完了、次のアプリケーションアクションを切り分ける。拡張機能の欠如は待ち時間を伸ばしても解決しない。ページが置き換えられた後に返ってきた結果は、自動再利用ではなく、新たなコンテキスト評価を必要とする。

reCAPTCHA について特に言えば、Google の サーバー検証ドキュメント では、レスポンストークンは 2 分間有効であり、1 度しか検証できないと説明している。これは reCAPTCHA レスポンストークン固有の性質であり、すべての CAPTCHA ソリューションやブラウザセッションに共通する有効期間ではない。

ワークフローの次のアクションは、有効な結果が利用可能になったポイントから近いタイミングで実行する。タスクがキャンセルされた、あるいはページが変わった場合は、古い操作を止め、別の認可済み試行を始める前に現在の状態を確認する。同じチャレンジに対して複数ワーカーを同時に動かすのは避ける。

スケジュールを戻す前に、修正済みクラウド実行を 1 つ証明する

修正されたデプロイは、ローカルで成功したのと同じ許可済みアプリケーション操作を完了できる必要がある。

環境比較に戻り、省かれていた依存関係、存在しない拡張機能、欠落したシークレット、誤ったブラウザ接続など、示された不整合だけを修正する。小さなタスクを 1 つ繰り返し、最終的なページまたはアプリケーションの確認結果を検証する。

修正した構成と観測結果の簡単な記録を残す。失敗したバージョンと動作したデプロイバージョンも含めることで、後日のイメージ再構築時に、同じ問題がこっそり再発するのを防ぐ。問題が続く場合は、より広範な失敗マップを提供する一般的な AI エージェント CAPTCHA トラブルシューティングガイド を参照する。

サポートされている CAPTCHA ハンドラーが必要な箇所には CapSolver を用い、そのうえでエージェントが完了したかどうかはアプリケーションの結果で判断する。実務的な修正は、多くの場合、「実際にどのブラウザとどのプロセスが動いているか」を特定したうえで行う小さなデプロイ修正である。

FAQ

Q: なぜノート PC では CAPTCHA 処理が動くのに、コンテナでは失敗するのですか？

コンテナには、ローカルの拡張機能、ブラウザインストール、オプション依存関係、認証情報、ネットワークアクセスなどが欠けている可能性がある。エージェントロジックを変える前に、実効環境と最初に失敗しているステップを比較する。

Q: CAPTCHA 拡張機能は常に可視ブラウザを必要としますか？

いいえ。Playwright は、ヘッドレスモードで拡張機能をサポートする Chromium 構成を文書化している。互換性は実行ファイル、起動構成、ホスティングサービスに依存するため、それらの詳細を確認すること。

Q: Core SDK をインストールすれば、ブラウザ検出は自動で提供されますか？

ドキュメントに記載されているブラウザ依存メソッドには、任意依存の Playwright が必要である。トークンのみのセットアップでは、同等のブラウザ環境は提供されない。

Q: ソルバーのレスポンスが成功しても、クラウドエージェントが固まったままになることはありますか？

はい。ページが変わっている、ハンドラーが別タブに紐づいている、あるいはアプリケーションが結果を受け付けていない、といった可能性がある。現在のページと、意図された最終アクションを別々に検証すること。

Q: デプロイ後にこうした問題が出た場合、モデルを切り替えるべきですか？

まずデプロイ差分を確認すべきである。拡張機能の欠如、利用できないツール、誤ったブラウザ接続といった問題は、言語モデルを変えても残り続ける。