browse-stealth

browse-stealth：AI エージェント向けステルス Web 自動化

対象を判断 — 必ず最初に確認してください

browse-stealth のコマンドを実行する前に、対象がステルス機能の目的に合っていることを確認してください。

ユーザーの目的	対象	コマンドパターン
Cloudflare／Turnstile の背後にあるサイトを開く	Camoufox	browse --runtime camoufox --headed goto <url>
Google の「通常と異なるトラフィック」ブロックを回避する	Camoufox	browse --runtime camoufox --camoufox-profile google --headed goto @google "query"
403 またはチャレンジページを返すサイトをスクレイピングする	Camoufox	browse --runtime camoufox --headed goto <url>
特定の camoufox フィンガープリントまたはプロキシプロファイルを使用する	Camoufox	browse --runtime camoufox --camoufox-profile <name> --headed goto <url>
ステルスセッションをまたいでログイン状態を維持する	Camoufox + ブラウザプロファイル	browse --runtime camoufox --camoufox-profile <n> --profile <p> --headed goto <url>
ブロックされていない通常のサイトを開く	デフォルトのブラウザー	このスキルではなく、browse スキルを使用してください
iOS／Android／macOS アプリを操作する	ネイティブターゲット	このスキルではなく、browse スキルを使用してください

重要なルール：

• --runtime camoufox は、C++ レベルのフィンガープリント偽装機能を備えた強化版 Firefox エンジンを選択します。
• --headed の使用を強く推奨します。ヘッドレス Firefox は検出されやすくなります。
• --camoufox-profile <name> は .browse/camoufox-profiles/<name>.json を読み込みます。設定が適用されるのはサーバーの起動時のみです。プロファイルを切り替える場合は、先に browse stop を実行してください。
• --profile <name> はブラウザーの Cookie／localStorage を再起動後も保持します。--camoufox-profile とは独立しています。
• --profile と --session を絶対に併用しないでください。 --profile は識別情報を保持し、--session は 1 台のサーバー内で並列エージェントを分離します。
• ステルス機能は IP レピュテーションの代わりにはなりません。 フィンガープリントの偽装だけでは、IP ベースのブロックを回避できません。保護が厳重なサイトでは、住宅用プロキシを使用してください。
• ステルス機能なしでサイトが問題なく読み込まれる場合は、browse スキルに戻してください。 Camoufox は動作が遅くなります。
• 使用する対象がわからない場合は、ユーザーに確認してください。 推測で決めないでください。

目標

camoufox ランタイムで永続的な browse CLI を使用して、次のことを行います。

• 通常のブラウザーをブロックするサイトにアクセスする
• Cloudflare Turnstile などの類似したアンチボットチャレンジを通過する
• 保護されたページのレンダリング済みコンテンツと状態を調べる
• 検出を招かずに UI 要素を操作する
• スクリーンショット、コンソールログ、ネットワークアクティビティを取得する
• 再起動後も認証済みセッションを維持する
• タスクごとにプロキシとフィンガープリントを切り替える

ステップ 0：利用可能か確認し、ステルスプロファイルを選択する

まず、次を確認します。

browse --version
browse --runtime camoufox doctor

browse がインストールされていない場合は、そこで停止してユーザーに次のように伝えてください。

次のコマンドでインストールしてください：npm install -g @ulpi/browse

camoufox がインストールされていない場合は、そこで停止してユーザーに次のように伝えてください。

次のコマンドでインストールしてください：npm install camoufox-js && npx camoufox-js fetch

自動で何もインストールしないでください。

次に、タスクに適したステルスプロファイルを決めます。/browse-config を実行してプロファイルを生成するか、既存のプリセットを選択してください。

プリセット	用途
stealth	一般的な検出回避（geoip + humanize）
google	Google 検索、SERP のスクレイピング（geoip + humanize + random OS）
scrape	高スループットのスクレイピング（画像、WebRTC、WebGL をブロックし、キャッシュを有効化）
custom	ユーザーと一緒に各オプションを選択

次に、必要なセッションの種類を決めます。

• 通常の単一エージェント作業にはデフォルトセッション
• 並列エージェントを分離するには --session <id>（同一の camoufox サーバーを使用）
• ブラウザーの識別情報を保持するには --profile <name>（Cookie は再起動後も維持）

成功条件：browse と camoufox が利用可能で、ステルスプロファイルが選択され、タスクに適したセッション／ブラウザープロファイルが選ばれていること。

ステップ 1：安全に移動し、ページを安定させる

実行中のサーバーを停止してから（--camoufox-profile を切り替える場合は必須）、次を起動します。

browse stop
browse --runtime camoufox --camoufox-profile <name> --headed goto <url>

指定したプロファイルが存在しない場合は、browse.json の camoufox セクションが自動的に使用されます。

browse stop
browse --runtime camoufox --headed goto <url>

移動後は、読み取りや操作を行う前に必ずページを安定させます。

• 一般的なページや SPA では browse wait --network-idle
• ページに既知のシグナルがある場合は、より具体的な browse wait 条件

重要なルール：

• browse は PATH 上の単独のコマンドとして呼び出します
• browse コマンドのプレフィックスにシェル変数を使用しないでください
• #id CSS セレクターは避け、[id=foo] を優先します
• 後続のコマンドでは必ず --runtime camoufox を渡すか、環境変数に BROWSE_RUNTIME=camoufox を設定します
• BROWSE_CONSENT_DISMISS=1 を設定すると、Cookie バナーが自動的に閉じられます（EU ロケールで便利です）

成功基準：保護されたページが読み込まれ、チャレンジ（ある場合）が解決され、コンテンツが信頼できる状態になっています。

ステップ 2：効果的で最もコストの低い確認方法を選ぶ

質問に答えられる最も軽量なコマンドを使用します。

• 整理されたページコンテンツには text
• ナビゲーション構造には links
• 正確な対象の抽出には js
• ランタイムのデバッグには console、errors、network
• インタラクティブ要素と安定した参照には snapshot -i
• 参照を使わずに SERP 構造で抽出するには、Google で --serp

操作が多いタスクでは、セレクターを推測する前に snapshot -i を優先してください。

次を読み込みます。

• コマンド構文全体については /browse のリファレンス（browse スキル内の references/commands.md）
• 速度に関するルールについては /browse のリファレンス（references/guides.md）

成功基準：不要なトークンを消費したり、脆弱なセレクターを使ったりせず、必要な情報を得ています。

ステップ 3：まず参照を使い、次にセレクターを使って操作する

クリック、入力、チェック、選択などの操作では、次の手順に従います。

1. browse --runtime camoufox snapshot -i を優先します
2. @eN 参照を使って操作します
3. 参照が利用できない場合に限り、CSS セレクターに切り替えます

移動後または DOM の更新後：

• 参照は無効になっている可能性があると考えます
• 続行する前に新しいスナップショットを取得します

ルール：

• 人間らしい間隔を設けるため、プロファイルで humanize: true（または 1.5～2.0 のようなより大きな数値）を有効にします
• .browse/sessions/<id>/ に説明的な名前でスクリーンショットを保存します
• 意図的に分離する場合を除き、状態を維持するフローは同じセッション内で続けます
• iframe のコンテンツを操作する前に frame を使用します（Turnstile は iframe 内にあります）

成功基準：操作が安定しており、検出されず、現在レンダリングされているページの状態に基づいています。

ステップ 4：ブロッカーと特殊なケースをデバッグする

問題が発生した場合：

• ページやランタイムの問題には console と errors を使用します
• リクエストの確認には network を使用します（チャレンジのエンドポイントを探します）
• src に challenges.cloudflare.com が含まれる iframe があるか確認します（Turnstile）
• 「unusual traffic」や「verify you are human」のようなテキストがあるか確認します

サイトにまだブロックされる場合の、ステルス関連の段階的な対応手順：

1. camoufox プロファイルの humanize を上げます（1.5 または 2.0 を試します）
2. OS フィンガープリントを切り替えます（ランダムに選択するには os: ["windows", "macos", "linux"] を指定します）
3. プロファイルに住宅用プロキシを追加し、browse stop を実行して再起動します
4. ヘッドレスで実行していた場合は --headed を使用します
5. 最終手段として、browse handoff を使ってユーザーに引き継ぎます。その前に AskUserQuestion で確認してください

サイトが正常に読み込まれたら、タスクの残りはデフォルトの browse スキルに切り替えてください。

成功基準：ブロッカーがステルスランタイム内で解決されているか、正しい引き継ぎ手順でエスカレーションされています。

ステップ 5：証拠を記録し、明確に報告する

タスクに検証が含まれる場合は、必要最小限の証拠を記録します。

• 関連するページテキストまたは構造化された抽出結果
• 視覚情報が重要な場合はスクリーンショットのパス
• デバッグ時のコンソール／ネットワークの調査結果
• 問題を報告する際は、失敗した正確な手順またはセレクター／ref
• 再現性に関係する場合は、使用した camoufox プロファイルとプロキシ

次の内容を報告します。

• 移動したページ
• 使用した camoufox プロファイルとブラウザプロファイル
• 実行した操作
• ページで実際に起きたこと（検出されたチャレンジを含む）
• スクリーンショット、HAR、動画など、作成した成果物

成功基準：別のエンジニアが同じプロファイルとプロキシを使って、確認されたステルス動作を再現できます。

重要なルール

• ブラウザはコマンド間で保持され、Cookie、タブ、セッション状態は引き継がれます。
• goto の後は、コンテンツを読んだり操作したりする前に待機します。
• snapshot -i はデフォルトの操作インターフェースで、通常の browse スキルと同じです。
• --camoufox-profile は サーバー起動時のみ指定できます。プロファイルを切り替えるには、先に browse stop を実行してください。
• humanize はクリックや入力にランダムな遅延を加えます。true または数値（0.5～2.0）を設定します。
• geoip は出口 IP に基づいて位置情報を偽装します。プロキシと組み合わせると、タイムゾーン／ロケール／位置情報はプロキシ IP に基づきます。
• ヘッドフルモードを強く推奨します。ヘッドレス Firefox は検出されやすいためです。
• IP の評価は重要です。フィンガープリントの偽装だけでは、IP ベースのブロックを回避できません。
• --profile（永続ブラウザ）と --session（共有多重化）を決して併用しないでください。
• スクリーンショットは .browse/sessions/<session-id>/ または .browse/sessions/default/ に保存します。
• 自動で何もインストールしないでください。
• Claude の設定を自動で変更しないでください。ユーザーには browse/references/permissions.md を案内してください。

参照資料を読み込むタイミング

• browse/references/commands.md 正確なコマンド構文、フラグ、拡張例を確認するときに使用します。すべて --runtime camoufox で動作します。

• browse/references/guides.md 速度に関するルール、コマンド選択の指針、アーキテクチャに関する注記、必須の CAPTCHA／MFA 引き継ぎプロトコルを確認するときに使用します。

• browse/references/permissions.md ユーザーが Claude の設定で browse コマンドを事前に許可したい場合に使用します。

ガードレール

• disable-model-invocation を追加しないでください。ユーザーが求めたときにステルス機能を利用できる状態にしておく必要があります。
• context: fork を追加しないでください。通常、ステルスの結果は現在のフローで必要になります。
• paths: を追加しないでください。これは汎用ワークフロースキルです。
• CLI のマニュアル全体をインラインで記載しないでください。browse スキルの参照資料を案内してください。
• camoufox、プロキシ、システム依存関係を自動でインストールしないでください。
• 明示的なユーザー確認なしに browse handoff を実行しないでください。
• browse セッションディレクトリ以外にスクリーンショットを保存しないでください。
• 最終報告にプロキシの認証情報やセッション Cookie を含めないでください。

ステルス対策プレイブック

よくあるブロックに対する具体的なパターンです。各プレイブックは上記のステップ 1～5 に組み込めます。

Cloudflare Turnstile

チャレンジを特定します。

browse --runtime camoufox --headed goto https://target-site.com/login
browse --runtime camoufox snapshot -i

src に challenges.cloudflare.com を含む iframe、「Verify you are human」というラベルのチェックボックス、または class／ID に cf-turnstile を含む要素を探します。

自動解除を待ちます（humanize で通過できることがよくあります）。

browse --runtime camoufox wait --network-idle
browse --runtime camoufox snapshot -i

解除されない場合は、ref を使ってチェックボックスをクリックし、再度スナップショットを取得します。それでもブロックされる場合は、humanize を 2.0 に上げてから browse stop を実行し、再起動します。

Google の「通常と異なるトラフィック」ブロックの回避

Google 用の安全なプロファイル（geoip + humanize + random OS）を使用します。

browse stop
browse --runtime camoufox --camoufox-profile google --headed goto @google "your query"
browse --runtime camoufox wait --network-idle
browse --runtime camoufox snapshot -i

同意ダイアログが表示された場合は、対応します（Accept の ref をクリック）。レート制限を避けるため、検索の間に browse wait --network-idle を追加します。それでもブロックされる場合は、IP にフラグが立てられています。住宅用プロキシに切り替えてください。

認証済みセッション

--camoufox-profile（フィンガープリント）と --profile（Cookie）を組み合わせます。

browse stop
browse --runtime camoufox --camoufox-profile stealth --profile mysite --headed goto https://target-site.com/login
# log in once through the normal flow

同じ --profile を指定して以降の起動を行うと、ログインがスキップされます。

browse stop
browse --runtime camoufox --camoufox-profile stealth --profile mysite --headed goto https://target-site.com/dashboard

自動化されたフローでは、認証情報ボルト（browse auth save ／ browse auth login）を使用してください。認証情報をコマンドライン引数に貼り付けることは絶対に避けてください。

プロキシのローテーション

各プロキシは、それぞれ名前付きの camoufox プロファイルで管理します。

.browse/camoufox-profiles/proxy-us.json
.browse/camoufox-profiles/proxy-eu.json
.browse/camoufox-profiles/proxy-asia.json

プロファイルの例：

{
  "geoip": true,
  "humanize": true,
  "proxy": {
    "server": "http://proxy:8080",
    "username": "user",
    "password": "pass"
  }
}

サーバーを停止し、別のプロファイルで再起動すると、リージョンを切り替えられます。

browse stop
browse --runtime camoufox --camoufox-profile proxy-eu --headed goto <url>

プロキシはブラウザーの起動時に設定されるため、切り替えるたびに再起動が必要です。

出力仕様

次の内容を報告してください。

1. テストしたページまたはフロー
2. camoufox プロファイル（使用した場合はブラウザープロファイルも）
3. 該当する場合はプロキシのリージョン
4. 実行した主なコマンドまたは操作
5. 発生したチャレンジも含め、観察された結果
6. スクリーンショット、コンソールエラー、ネットワーク障害、引き継ぎ状態などの成果物や阻害要因