ブラウザ自動化

browse CLI を使用して Claude でブラウザ操作を自動化します。

セットアップの確認

ブラウザコマンドを実行する前に、CLI が利用可能であることを確認してください:

which browse || npm install -g @browserbasehq/browse-cli

環境の選択 (ローカル vs リモート)

CLI はセッションごとの明示的な環境オーバーライドをサポートしています。何もしない場合、次のセッションのデフォルトは、BROWSERBASE_API_KEY が設定されていれば Browserbase になり、そうでなければローカルになります。

ローカルモード

• browse env local は新しく独立したローカルブラウザを開始します
• browse env local --auto-connect は既に実行中のデバッグ可能な Chrome を再利用し、利用不可の場合は独立モードにフォールバックします
• browse env local <port|url> は特定の CDP ターゲットにアタッチします
• 最適な用途: 開発、localhost、信頼できるサイト、再現可能な実行

リモートモード (Browserbase)

• browse env remote は現在のセッションを Browserbase に切り替えます
• ローカルオーバーライドがない場合、BROWSERBASE_API_KEY が設定されていれば Browserbase がデフォルトです
• 提供機能: アンチボットステルス、自動 CAPTCHA 解法、レジデンシャルプロキシ、セッション永続化
• リモートモードを使用する場合: ターゲットサイトがボット検出、CAPTCHA、IP レート制限、Cloudflare 保護、または地域固有のアクセスを必要としている場合
• 認証情報の取得: https://browserbase.com/settings

どちらを選ぶか

• 反復可能なローカルテスト / クリーンな状態: browse env local
• ローカルのログイン/クッキーを再利用: browse env local --auto-connect
• シンプルな閲覧 (ドキュメント、ウィキ、パブリック API): ローカルモードで問題ありません
• 保護されたサイト (ログインウォール、CAPTCHA、アンチスクレイピング): リモートモードを使用してください
• ローカルモードがボット検出またはアクセス拒否で失敗 した場合: リモートモードに切り替えてください

コマンド

すべてのコマンドは両モードで同じように動作します。デーモンは最初のコマンドで自動起動します。

ナビゲーション

browse open <url>                        # URL に移動 (別名: goto)
browse open <url> --context-id <id>      # Browserbase コンテキストを読み込む (リモートのみ)
browse open <url> --context-id <id> --persist  # コンテキストを読み込み + 変更を保存
browse reload                            # 現在のページをリロード
browse back                              # 履歴で戻る
browse forward                           # 履歴で進む

ページの状態 (スクリーンショットより snapshot を優先)

browse snapshot                          # アクセシビリティツリーと要素リファレンスを取得 (高速、構造化)
browse screenshot [path]                 # ビジュアルスクリーンショットを撮影 (低速、ビジョンテークンを使用)
browse get url                           # 現在の URL を取得
browse get title                         # ページタイトルを取得
browse get text <selector>               # テキストコンテンツを取得 ("body" ですべてのテキスト)
browse get html <selector>               # 要素の HTML コンテンツを取得
browse get value <selector>              # フォームフィールド値を取得

ページの状態を理解するには browse snapshot をデフォルトとして使用してください。これはアクセシビリティツリーと相互作用に使用できる要素リファレンスを返します。browse screenshot は視覚的なコンテキスト (レイアウト、画像、デバッグ) が必要な場合のみ使用してください。

インタラクション

browse click <ref>                       # snapshot のリファレンスで要素をクリック (例: @0-5)
browse type <text>                       # フォーカスされた要素にテキストを入力
browse fill <selector> <value>           # 入力を埋めて Enter キーを押す
browse select <selector> <values...>     # ドロップダウンオプションを選択
browse press <key>                       # キーを押す (Enter, Tab, Escape, Cmd+A など)
browse drag <fromX> <fromY> <toX> <toY>  # あるポイントから別のポイントにドラッグ
browse scroll <x> <y> <deltaX> <deltaY> # 座標でスクロール
browse highlight <selector>              # ページ上の要素をハイライト
browse is visible <selector>             # 要素が表示されているかチェック
browse is checked <selector>             # 要素がチェックされているかチェック
browse wait <type> [arg]                 # 待機: load, selector, timeout

セッション管理

browse stop                              # ブラウザデーモンを停止 (環境オーバーライドもクリア)
browse status                            # デーモンステータスを確認 (環境を含む)
browse env                               # 現在の環境を表示 (ローカルまたはリモート)
browse env local                         # クリーンで独立したローカルブラウザを使用
browse env local --auto-connect          # 既存の Chrome を再利用、独立モードにフォールバック
browse env local <port|url>              # 特定の CDP ターゲットにアタッチ
browse env remote                        # Browserbase に切り替え (API キーが必要)
browse pages                             # すべてのオープンタブをリスト表示
browse tab_switch <index>                # インデックスでタブを切り替え
browse tab_close [index]                 # タブを閉じる

典型的なワークフロー

環境が重要な場合、browse env local、browse env local --auto-connect、または browse env remote で最初に設定してください。

1. browse open <url> — ページに移動
2. browse snapshot — アクセシビリティツリーを読んでページ構造を理解し、要素リファレンスを取得
3. browse click <ref> / browse type <text> / browse fill <selector> <value> — snapshot のリファレンスを使用して相互作用
4. browse snapshot — アクションが成功したことを確認
5. 必要に応じて 3-4 を繰り返す
6. browse stop — 完了時にブラウザを閉じる

クイック例

browse open https://example.com
browse snapshot                          # ページ構造 + 要素リファレンスを表示
browse click @0-5                        # リファレンス 0-5 の要素をクリック
browse get title
browse stop

モード比較

機能	ローカル	Browserbase
速度	より高速	やや低速
セットアップ	Chrome が必要	API キーが必要
既存のローカルクッキーを再利用	browse env local --auto-connect を使用	N/A
ステルスモード	いいえ	はい (カスタム Chromium、アンチボットフィンガープリント)
CAPTCHA 解法	いいえ	はい (自動 reCAPTCHA/hCaptcha)
レジデンシャルプロキシ	いいえ	はい (201 国、地理ターゲット)
セッション永続化	いいえ	はい (コンテキストで認証情報が永続化)
最適な用途	開発/シンプルなページ	保護されたサイト、ボット検出、本番スクレイピング

ベストプラクティス

1. ローカル戦略を意図的に選択: クリーンな状態には browse env local を、既存のローカル認証情報には browse env local --auto-connect を、保護されたサイトには browse env remote を使用してください
2. 相互作用の前に常に browse open を実行
3. browse snapshot を使用 してページの状態を確認 — 高速で要素リファレンスを提供します
4. 視覚的なコンテキストが必要な場合のみスクリーンショット (レイアウト確認、画像、デバッグ)
5. snapshot のリファレンスを使用 してクリック/相互作用 — 例: browse click @0-5
6. 完了時に browse stop してブラウザセッションをクリーンアップし、環境オーバーライドをクリア

トラブルシューティング

• 「アクティブなページなし」: browse stop を実行し、browse status を確認してください。それでも実行中と表示される場合は、pkill -f "browse.*daemon" でゾンビデーモンを強制終了し、browse open を再試行してください
• Chrome が見つからない: Chrome をインストール、デバッグ可能な Chrome を既に実行している場合は browse env local --auto-connect を使用、または browse env remote に切り替えてください
• アクション失敗: browse snapshot を実行して、利用可能な要素とそのリファレンスを確認
• Browserbase 失敗: API キーが設定されていることを確認

リモートモードへの切り替え

次の場合にリモートに切り替えてください: CAPTCHA (reCAPTCHA、hCaptcha、Turnstile)、ボット検出ページ (「ブラウザを確認中...」)、HTTP 403/429、コンテンツがあるはずのサイトの空白ページ、またはユーザーがリクエスト。

シンプルなサイト (ドキュメント、ウィキ、パブリック API、localhost) では切り替えないでください。

browse env local             # クリーンで独立したローカルブラウザ
browse env local --auto-connect  # 既存の Chrome の状態を再利用
browse env remote            # Browserbase に切り替え

オーバーライドはセッションごとにスコープされ、再度切り替えるか browse stop を実行するまで有効です。browse stop の後、次の起動は環境変数ベースの自動検出にフォールバックします。browse status を使用して、デーモン実行中に解決されたローカル戦略を検査してください。

詳細な例については、EXAMPLES.md を参照してください。 API リファレンスについては、REFERENCE.md を参照してください。