候鳥ブラウザコントロール連携
NOTE
本記事の翻訳作業はまだ完了していません。 中国語版原文は 中文版 を参照してください。
MBAgent が「本当に候鳥ブラウザを操作できる」のは、候鳥クライアント ControlV2 という通信プロトコルのおかげです。本記事では MBAgent と候鳥ブラウザの接続方法、よくある問題の切り分けを詳しく紹介します。
一、候鳥ブラウザコントロールとは？
候鳥ブラウザコントロール（Houniao Client ControlV2）は候鳥ブラウザが外部に提供する 双方向通信プロトコル で、他のプログラム（MBAgent を含む）が次のことを可能にします：
- 🔍 ローカルで実行中の候鳥インスタンスを発見
- 🤝 候鳥インスタンスとハンドシェイク
- 🔑 候鳥アカウントでログイン
- 📦 候鳥設定（環境・プロキシ・指紋）を読み込み
- 🚀 候鳥環境を起動 / 停止
- 🌐 候鳥環境内のページを操作
NOTE
類比：ControlV2 を候鳥ブラウザの「リモートコントロール プロトコル」と理解できます。MBAgent はリモートコントロール、候鳥ブラウザはテレビ。
二、MBAgent と候鳥の 3 種類の接続モード
1. MBAgent コントロール（推奨）
MBAgent 起動時にローカルで 候鳥コントロールサービス を自動的に起動し、候鳥ブラウザがクライアントとして接続してきます。
適用シーン：
- 単一候鳥インスタンス
- ほとんどの個人ユーザー
- 候鳥 + MBAgent 同一マシンで実行
2. ApiServer コントロール
候鳥ブラウザ内蔵の ApiServer インターフェース（http://127.0.0.1:8186）経由で接続。
適用シーン：
- 候鳥をリモート制御
- 候鳥ブラウザが他のマシンにある
- 自動化スクリプト（Selenium / Puppeteer / Playwright）
3. 同一インスタンス
MBAgent と候鳥ブラウザが 同じクライアントインスタンス 内で、内部通信を直接行う。
適用シーン：
- 開発デバッグ
- 性能重視シーン
三、初回接続
前提条件
✅ 候鳥ブラウザが起動しアカウントにログイン済み ✅ MBAgent がインストール済み ✅ MBAgent 起動時に選択した作業ディレクトリに権限あり
自動接続フロー
MBAgent は起動時に 自動的に 次のフローを実行：
[1] ローカル ControlV2 サービス起動
↓
[2] ローカル候鳥インスタンスをスキャン
- UDP ブロードキャスト / ローカルポートスキャンで
- 候鳥ブラウザの ControlV2 ポートを発見
↓
[3] ハンドシェイク
- プロトコルバージョン番号を交換
- 暗号化方式を协商
↓
[4] アカウントログイン
- MBAgent が候鳥アカウントで ControlV2 にログイン
- 自動的に Token を読み取り
↓
[5] 設定読み込み
- 候鳥アカウント下のすべての環境
- 候鳥アカウント下のプロキシ設定
↓
[6] 能力検出
- 環境起動 / 停止をテスト
- ウェブ接管をテスト
- ファイル操作をテスト
↓
[7] 接続成功 ✅接続状態の確認
- 「設定 → 公式サービス検出」 に入る
- 「候鳥クライアント ControlV2」 オプションをクリック
- 「検出開始」 をクリック
- 数秒後に表示：
- ✅ 正常：全チェック合格
- ⚠️ 異常：具体的な失敗ステップ
- ⚪ 未有効：ControlV2 が未有効
- ⏳ 検出中：検出中
四、検出結果の解釈
✅ 正常
候鳥クライアント ControlV2 は正常使用可能
リアルタイム準備往復検出により接続・ログイン・設定・実行可能能力を検証済み。MBAgent が候鳥ブラウザを正常に操作できることを示します。
⚠️ 異常：接続失敗
可能性のある原因：
- 候鳥ブラウザが起動していない
- ControlV2 ポートが占有されている
- ファイアウォールにブロックされている
切り分け：
- 候鳥ブラウザが起動していることを確認
- 候鳥ブラウザ → 設定 → ControlV2 が有効か確認
- ファイアウォール / アンチウイルスソフトを閉じて再試行
⚠️ 異常：アカウント未ログイン
可能性のある原因：
- 候鳥アカウント Token の期限切れ
- MBAgent が Token を読み取れていない
切り分け：
- 候鳥ブラウザ内で 再ログイン
- MBAgent を再起動
⚠️ 異常：設定読み込み失敗
可能性のある原因：
- 候鳥アカウント下に環境が作成されていない
- 候鳥データベース接続失敗
切り分け：
- 候鳥ブラウザ内で 環境を 1 つ作成
- MBAgent を再起動
⚠️ 異常：実行可能能力不合格
可能性のある原因：
- 候鳥ブラウザと MBAgent のバージョン非互換
- システム権限不足
切り分け：
- 候鳥ブラウザが最新版であることを確認
- 管理者権限で MBAgent を起動
- 候鳥カスタマーサポートへ連絡
五、候鳥コントロールインスタンスの切替
ローカルに複数の候鳥ブラウザインスタンス（開発シーン）がある場合、切替可能：
第一步：すべての候鳥インスタンスを表示
- 「設定 → 候鳥クライアント ControlV2」 に入る
- 「候鳥インスタンス」 オプションをクリック
- 現在発見された候鳥インスタンス一覧を表示：
候鳥インスタンス #1 (デフォルト)
- ポート: 8186
- バージョン: v3.0.0
- 状態: 接続済
候鳥インスタンス #2 (開発)
- ポート: 8286
- バージョン: v3.0.0
- 状態: 未接続第二步：切替
- ターゲット候鳥インスタンスを選択
- 「切替」 ボタンをクリック
- MBAgent が現在のインスタンスを切断し、新しいインスタンスに接続
- 注意：切替は現在のすべての候鳥操作を停止します
TIP
日常使用：99% のユーザーは 1 つの候鳥インスタンスのみ必要、切替不要。
六、AI が候鳥ブラウザを操作する過程
MBAgent が「候鳥操作」指令を受信すると、自動的に次のフローを実行：
[1] AI がタスクを解析
「223223 この店舗を開き、今日の注文を確認」
↓
[2] ControlV2 インターフェースを呼び出し
- control.browser.start({ environment_id: "223223" })
↓
[3] 候鳥ブラウザが環境を起動
- 223223 環境を作成 / 再利用
- 指紋 / プロキシ / Cookie を適用
- browser_handle を返す
↓
[4] MBAgent が CDP でページを接管
- attach({ handle })
- ページスクリーンショット、DOM 構造を受信
↓
[5] AI がページを分析し次のステップを決定
「注文ページが見えた、次は数字を抽出」
↓
[6] 動作を実行
- click / type / extract
↓
[7] タスク完了、環境を閉じる（または開いたまま）
↓
[8] ユーザーに結果を整理
「今日の注文 23 件、金額 $1234.56」キー概念
- handle（ハンドル）：候鳥ブラウザが MBAgent に返す「環境ハンドル」、具体的な環境を参照
- attach（アタッチ）：MBAgent が候鳥環境のページを接管
- CDP：Chrome DevTools Protocol、候鳥ブラウザが内部で使用するプロトコル
七、よくあるご質問
Q1：MBAgent 起動後に「候鳥 CDP を待機中」が表示される
原因：候鳥ブラウザが起動していない、または環境が起動していない。
解決：
- 候鳥ブラウザが起動しログインしていることを確認
- 候鳥ブラウザ内で 環境を手動起動
- MBAgent が自動的に接管
Q2：AI の候鳥環境操作が常に失敗する
可能性のある原因：
- ControlV2 異常（公式サービス検出を確認）
- 候鳥アカウント枠を使い切った
- 候鳥環境が破損
切り分け：
- 設定 → 公式サービス検出 で ControlV2 が正常か確認
- 候鳥アカウント AI 枠を確認
- 候鳥ブラウザ内で該当環境を手動テスト
Q3：候鳥ページを接管後、画面が真っ黒
可能性のある原因：
- 候鳥ブラウザが起動したばかりで環境準備未完了
- 候鳥アカウントが二次認証を必要とする
解決：
- 5-10 秒待ってから再試行
- 候鳥ブラウザ内で手動で認証完了
Q4：MBAgent でリモートの候鳥ブラウザを制御できる？
❌ できません。MBAgent の候鳥クライアント ControlV2 接続は実装層で 127.0.0.1 に硬性限定 されています（ControlClientError::NonLoopbackEndpoint）、loopback 以外の IP アドレスは受け付けません。候鳥ブラウザの ControlV2 ポートを外部公開（例：0.0.0.0:8186）しても、MBAgent はハンドシェイク段階で直接接続を拒否します。
正しいリモート候鳥制御方法：
- Selenium / Puppeteer / Playwright などのスクリプトを使用し、候鳥ブラウザ内蔵の ApiServer（
http://127.0.0.1:8186）経由でリモート呼び出し - この種のシーンでは MBAgent は関与せず、通常の HTTP クライアントとして候鳥 ApiServer インターフェースを呼び出すのみ
NOTE
なぜ loopback に限定するのか：
- ControlV2 プロトコル自体に強い身份検証がなく、TCP ポートを公衆ネットワークに公開することは「候鳥アカウント制御権を誰にでも渡す」ことを意味する
- MBAgent と候鳥ブラウザは同じマシン・同じアカウント文脈で実行すると仮定、loopback は最低リスクの境界
Q5：MBAgent が候鳥ブラウザを操作しなくても使える？
✅ 完全に可能。MBAgent の核心機能（会話・文書・コード・知識ベース）は候鳥ブラウザに依存しません。明確に候鳥アカウント環境の操作を要求したときのみ ControlV2 接続を確立します。
八、ベストプラクティス
起動順序
推奨起動順序：
- 候鳥ブラウザ（先に起動しログイン）
- MBAgent（後で起動、自動接続）
逆順は避けてください。
長時間未使用時
候鳥ブラウザ操作を長時間しない場合：
- MBAgent 内の「候鳥 RAG 知識ベース」と「候鳥クライアント ControlV2」サイドバー入口を閉じる
- タスク内で候鳥操作を減らす
- 候鳥アカウントのリソース消費を節約
多人協調
チーム複数人で 1 つの候鳥アカウントを共有する場合：
- 各人の MBAgent が独立に接続可能
- ただし 同時操作 1 つの環境は衝突
- ピーク時間をずらして使用、または各自に独立した候鳥子アカウントを開設
下一步：中文版原文