PinchTab + CapSolver: CAPTCHA処理: ブラウザエージェント向け

TL;DR

• PinchTab 0.15.2には、autoSolver.external.capsolverKeyが設定されている場合にCapSolverを読み込むAutoSolverレジストリが含まれています。
• PinchTabをローカルホストにバインドし、サーバーのトークンを必要とし、ブラウザのナビゲーションを自動化タスクに承認されたドメインに制限してください。
• GET /solversを使用して、POST /solve/capsolverまたはタブスコープの解決ルートを呼び出す前にプロバイダーの登録を確認してください。
• solved: trueをチャレンジステップの結果として扱い、元のフォーム、テスト、またはデータタスクの成功を証明するものとしないでください。
• カプチャの種類、セッション、または認証の境界が不明な場合、制限された試行回数後に制御を人間に引き渡してください。

PinchTabは、Chrome用のコンパクトなHTTP、CLI、MCPコントロールプレーンをAIエージェントに提供します。現在のAutoSolverレイヤーは、CapSolverを含む外部プロバイダーを登録でき、認証されたブラウザワークフローがサポートされているCAPTCHAを処理できますが、モデルに直接APIペイロードを教える必要はありません。

このガイドでは、CapSolverをPinchTabで設定し、ローカルサービスを確認し、名前付きソルバーを呼び出し、最終的なワークフローのチェックをソルバーの外に保つ方法を説明します。例ではPinchTab 0.15.2とプレースホルダーの資格情報を使用しています。これらは、許可されたQA、RPA、および公開データワークフローに適しています。

PinchTabとCapSolverの統合で可能になること

PinchTabとCapSolverの統合により、PinchTabがすでに制御しているブラウザセッションに名前付きのCAPTCHA処理ステップが追加されます。

PinchTabのAutoSolverドキュメントでは、内部および外部のソルバーのレジストリが説明されています。capsolverプロバイダーはautoSolver.external.capsolverKeyの構成フィールドを通じて有効になります。PinchTabはアクティブなタブとブラウザの状態を保持し、外部プロバイダーはサポートされているチャレンジタスクを処理します。

この分離はブラウザエージェントにとって重要です。エージェントはタスクタイプを発明したり、資格情報をプロンプトにコピーしたり、返された解決がビジネスアクションを完了したと仮定してはなりません。PinchTabはページセッションを所有しています。CapSolverはドキュメントされたチャレンジ結果を返します。あなたのアプリケーションは、継続、再試行、停止、または人間のレビューを要求するかどうかを決定する必要があります。

前提条件

統合を設定する前に以下のものを用意してください:

• リリースノートとソルバー参照が同じフィールドを文書化し続ける、0.15.2以降のバージョンのPinchTab。
• Chromeまたは他のPinchTabでサポートされているChromiumランタイム。
• ソースコード管理外に保存されたCapSolverアカウントとAPIキー。
• ワークフロー用の専用で権限の低いブラウザプロファイル。
• サポートされているチャレンジを提示できる所有または明示的に許可されたテストページ。

PinchTabのセキュリティガイドでは、サーバーのトークン、ローカルホストのバインディング、ドメインの制御を推奨しています。これらのセキュリティ対策はローカルマシンでも関連があります。コントロールプレーンにアクセスできる任意のローカルプロセスがブラウザを制御できる可能性があるためです。

この記事の検証実行では、公式のPinchTab 0.15.2 macOS ARM64バイナリを使用しました。バイナリはpinchtab 0.15.2を返し、認証された/healthルートはHTTP 200でauthRequired: trueを返しました。この環境には承認されたCapSolverキーまたは認証されたCAPTCHAテストターゲットがなかったため、本格的な支払いチャレンジは提出されませんでした。

PinchTabをインストールしてバージョンを確認する

プロジェクトの公式リリースまたはインストール方法に従ってPinchTabをインストールし、実行中のバイナリを確認してください。

pinchtab version

このガイドで検証されたバージョンの予期される出力:

pinchtab 0.15.2

関連しない作業に使用される個人のブラウザ設定を変更する代わりに、専用の構成ファイルを初期化してください。

export PINCHTAB_CONFIG="$PWD/pinchtab-config.json"
pinchtab config init

config initはサーバーのトークンを作成します。CIログにそのトークンを出力したり、結果のファイルをコミットしたりしないでください。

PinchTabのAutoSolverにCapSolverを設定する

autoSolver.externalの下にCapSolverを設定し、レビューされたリモートアクセス設計がない限り、ブラウザコントロールサーバーを127.0.0.1に保ってください。

{
  "server": {
    "bind": "127.0.0.1",
    "port": "9867",
    "token": "PINCHTAB_SERVER_TOKEN"
  },
  "security": {
    "allowedDomains": ["qa.example.com"],
    "idpi": {
      "enabled": true,
      "strictMode": true,
      "scanContent": true,
      "wrapContent": true
    }
  },
  "autoSolver": {
    "enabled": true,
    "autoTrigger": false,
    "triggerOnNavigate": false,
    "triggerOnAction": false,
    "maxAttempts": 3,
    "solverTimeoutSec": 30,
    "retryBaseDelayMs": 500,
    "retryMaxDelayMs": 5000,
    "solvers": ["capsolver", "cloudflare", "semantic"],
    "llmFallback": false,
    "external": {
      "capsolverKey": "CAPSOLVER_API_KEY"
    }
  }
}

シクレットマネージャーを使用して、実際の値をランタイム構成に挿入してください。上記のプレースホルダーは使用できない資格情報です。

自動トリガーを無効にした状態で開始すると、最初のテストがより簡単に監査できます。アプリケーションがページを承認された検証チェックポイントとして分類した場合にのみ、名前付きソルバーを呼び出すことができます。ワークフローが安定したら、自動トリガーを別途評価し、同じ試行回数とタイムアウト制限を維持してください。

CapSolverのボーナスコードを取得する

自動化予算を即座に増やす！
CapSolverアカウントにチャージする際にボーナスコード CAP26 を使用すると、毎回チャージに5%のボーナスが追加されます — 限度はありません。
今すぐCapSolverダッシュボードで取得してください

サーバーを起動し、プロバイダーの登録を確認する

ターゲットワークフローを開く前に、コントロールプレーンとソルバーのレジストリを確認してください。

専用の構成でPinchTabを起動します:

PINCHTAB_CONFIG="$PWD/pinchtab-config.json" pinchtab server

別のターミナルで、サーバーのトークンをシクレットストアから読み込み、ローカルの健康状態ルートを呼び出します:

curl -sS \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  http://127.0.0.1:9867/health

健全な応答はstatus: "ok"を報告します。デフォルトのブラウザインスタンスが準備できるまで待ってから、ソルバー一覧を確認してください。

curl -sS \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  http://127.0.0.1:9867/solvers

PinchTabの解決ルートリファレンスでは、APIキーが構成されている場合、capsolverが含まれていると述べています。なければ、アクティブな構成パスを確認し、サービスを再起動し、PinchTabを起動したプロセスにキーが挿入されていることを確認してください。

有効なタブでCapSolverを呼び出す

有効なタブが承認されたチャレンジページに到達したときに、名前付きcapsolverルートを呼び出してください。

curl -sS -X POST \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:9867/solve/capsolver \
  -d '{"maxAttempts": 3, "timeout": 30000}'

特定のタブに対しては、タブスコープのルートを使用して、現在アクティブなタブに関係なく同時にエージェントが動作しないようにしてください:

curl -sS -X POST \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  "http://127.0.0.1:9867/tabs/TAB_ID/solve/capsolver" \
  -d '{"maxAttempts": 3, "timeout": 30000}'

ドキュメントされた応答には、タブID、ソルバー名、解決フラグ、チャレンジタイプ、試行回数、最終的なページタイトルが含まれます。これらのフィールドをブラウザタスクの相関IDとともに保存してください。APIキーまたは返されたチャレンジアーティファクトを通常のアプリケーションログに保存しないでください。

元のブラウザタスクを確認する

チャレンジステップが返された後、元のブラウザタスクには独自の承認チェックが必要です。

QAワークフローでは、同じタブで期待されるURL、ページタイトル、認証状態、またはフォーム結果を確認してください。データワークフローでは、期待されるレコードスキーマが存在し、応答が別のチャレンジまたはエラーページでないことを検証してください。ブラウザタイトルだけでは不十分です。

エラー応答をすべて成功と見なすのではなく、小さな状態マシンを使用してください:

CapSolverのタスク結果ドキュメントでは、処理タスクと準備ができている結果を区別しています。PinchTabはそのプロバイダーの相互作用を抽象化していますが、あなたのアプリケーションは依然として全体のワークフローの期限と最終的な承認ルールを強制する必要があります。

一般的な問題

/solversにcapsolverが表示されない

アクティブなPinchTabプロセスはおそらく別の構成ファイルを使用しており、再起動されていないか、外部APIキーを受信していない可能性があります。PINCHTAB_CONFIGを確認し、サーバーを再起動し、シークレットを出力せずに再びレジストリを照会してください。

/solversが503を返す

PinchTabのブラウザインスタンスがまだ起動中または再起動中かもしれません。/healthを確認し、インスタンスの状態を確認し、選択されたプロファイルで構成されたChromiumバイナリが起動できることを確認してください。

ソルバーが成功を報告するがフォームは依然として失敗する

ページが移動した可能性があります。トークンが別のブラウザコンテキストに属している可能性があります。または、アプリケーションが元のアクションを拒否した可能性があります。タブの所有権を安定させ、チャレンジ処理後にビジネス結果を確認してください。

エージェントが同じチャレンジを無限ループする

繰り返し解決は無制限にしてはなりません。maxAttemptsを小さく保ち、最初の失敗証拠を保持し、同じチェックポイントが返る場合、ワークフローをneeds_reviewに移動してください。

ワークフローがログイン、2FA、またはアカウント検証に到達する

CAPTCHA処理は資格情報の入力、アカウント作成、電話検証、または制限されたデータへのアクセスを認証しません。アプリケーションの通常のアクセスポリシーに従って、人間のアクションを要求してください。

結論

PinchTabは、CapSolverを名前付きの外部ソルバーとして使用するために必要な統合ポイントをすでに公開しています。本番環境の設定では、サーバーをローカルまたは強力に認証し、ターゲットドメインを制限し、すべての解決を特定のタブにバインドし、試行回数を制限し、元のページの結果を確認する必要があります。

CapSolverは、自動化が許可されているワークフロー内でのみ使用してください。プロバイダーの結果はブラウザステートマシンの1つの制御されたステップであり、単なる継続のシグナルではありません。

ブラウザエージェントワークフローに制御されたCAPTCHA処理を追加する

CapSolverアカウントを作成し、所有しているQAページでPinchTabの統合をテストし、APIキーをランタイムのシークレットストアに保持してください。自動トリガーを有効にする前に、手動でソルバーを呼び出し、厳格な試行予算を設定してください。

FAQ

Q: PinchTabはCapSolverを直接サポートしていますか？

はい。PinchTabのAutoSolverドキュメントとsolveリファレンスでは、capsolverがautoSolver.external.capsolverKeyによって有効化される外部プロバイダーとしてリストされています。

Q: PinchTabのMCP経由でCapSolverを使用できますか？

PinchTabはMCPを通じてブラウザコントロールを公開し、HTTP AutoSolverルートは名前付きソルバーを処理します。インストールされたPinchTabバージョンで正確なツールの表面を確認し、ソルバーの呼び出しを制限されたアプリケーションワークフロー内で行う必要があります。

Q: 即座に自動解決を有効にすべきですか？

いいえ。承認されたテストページで明示的な呼び出しを開始し、タブスコープの応答を確認し、明確な検出、停止、監査ルールがあることを確認した後で、自動トリガーを追加してください。

Q: solved: trueは何を証明していますか？

solved: trueはチャレンジステップの結果を報告します。あなたのアプリケーションは、元のナビゲーション、フォーム送信、テストアサーション、またはデータリクエストが成功したことを依然として検証する必要があります。

Q: カプチャの種類がサポートされていない場合、エージェントは何をすべきですか？

設定された試行予算後に停止し、人間のレビューを要求する必要があります。プロバイダーのフィールドを即興で変更したり、承認されていないターゲットに切り替えたり、ログイン、2FA、またはアイデンティティ検証に進んではなりません。