agent にクロスオリジン iframe をクリックさせる：chrome-use がこの難題を突破した話

AI agent にブラウザをつなぐと、最初さいしょはだいたい順調じゅんちょうです。ページを開ひらく、内容ないようを読よむ、検索けんさくボックスに入力にゅうりょくする。本当ほんとうに人ひとを詰つまらせるのは、クロスオリジン iframe の中なかに隠かくれたフォームです——Google Payments の受取うけとり情報じょうほう、さまざまな決済けっさいコンポーネント、KYC コントロール。agent はその中なかの文字もじを読よめるし、値あたいも入力にゅうりょくできる。でも、あの「保存」ボタンだけはクリックできない。読よめるのに、完了かんりょうできない。

この記事は、この壁かべを乗のり越こえた過程かていの記録きろくです。主役しゅやくは chrome-use——Rust で書かかれた、agent 向むけのブラウザ自動化じどうか CLI です。Playwright も headless も使つかわず、あなたが**実際じっさいにログインしている**その Chrome を直接ちょくせつ操作そうさします。

プロジェクトページ：https://chrome-use.leeguoo.com/

なぜクロスオリジン iframe はこんなに難むずかしいのか

普通ふつうのページなら簡単かんたんです。アクセシビリティツリーを取得しゅとくし、要素ようその参照さんしょうを取とり、クリックすれば終おわりです。しかしクロスオリジン iframe（たとえば adsense.google.com のページに payments.google.com の iframe が埋うめ込こまれている場合ばあい）では、一度いちどに3つの地雷じらいを踏ふみます。

1. セレクタが中なかに入はいれない。同一どういつオリジンポリシーのもとでは、外側そとがわのドキュメントで実行じっこうする CSS セレクタや eval は、iframe 内部ないぶの DOM に一切いっさい触ふれられません。ここでは document.querySelector は役やくに立たちません。
2. スクロールが外はずれる。ページをスクロールしているつもりでも、実際じっさいにスクロールできるのは iframe 内部ないぶのスクロールコンテナです。wheel イベントは外側そとがわのドキュメントに送おくられ、中なかは微動びどうだにしません——目標もくひょうの行ぎょうはいつまでも「画面外がめんがい」にあり、見みることすらできません。
3. 座標ざひょうを推測すいそくしてクリックするしかなくなる。前まえの2つの問題もんだいにより、「スクリーンショット + ピクセル座標ざひょうの推測すいそく」へ戻もどらざるを得えません。これはもっとも不正確ふせいかくで、隣となりのフィールドを誤あやまってクリックしやすい方法ほうほうです。**全体ぜんたいの支払しはらい情報じょうほう**を変更へんこうするフォームでは、クリック一回いっかいの間違まちがいの代償だいしょうは小ちいさくありません。

chrome-use の基盤きばん：agent に渡わたすのは HTML ではなく「参照さんしょう」

突破とっぱ方法ほうほうを話はなす前まえに、まず chrome-use の基本きほんを説明せつめいする必要ひつようがあります。これは、「HTML をモデルに食たべさせる」派はとの根本的こんぽんてきな違ちがいでもあります。

chrome-use はページのソースコードを agent に投なげません。かわりにアクセシビリティツリーのスナップショットを取得しゅとくし、操作そうさできる各かく要素ようそに短みじかい参照さんしょうを付つけます。

- textbox "メール" [ref=e2]
- listbox "国/地域" [ref=e60]
- button "保存" [ref=e41]

agent はその参照さんしょうを直接ちょくせつ操作そうさします。fill @e2 "..."、click @e41 のように。1ページはだいたい 200–400 token で済すみ、DOM ノイズで画面がめん全体ぜんたいが埋うまることはありません。この参照さんしょう仕組しくみこそが、あとで iframe を貫通かんつうできる前提ぜんていになります——スナップショットが iframe 内部ないぶのノードを「見みられる」なら、参照さんしょうも取得しゅとくできます。

3つの壁かべを一ひとつずつ越こえる

第一だいいちの壁かべ: スナップショットに iframe 内部ないぶを見みせる。 アクセシビリティツリーがクロスオリジン iframe を貫通かんつうし、内部ないぶのノードにも参照さんしょうを付つけて持もってこられるようにします。修正しゅうせいすると、snapshot が直接ちょくせつこう列挙れっきょします。

- textbox "電話番号 (任意)" [ref=e59]
- listbox "国/地域コード：日本 (+81)" [ref=e60]

——セレクタが入はいれない場所ばしょにも、参照さんしょうは入はいれます。

第二だいにの壁かべ: スクロールを iframe のスクロールコンテナに効きかせる。 wheel を外側そとがわのドキュメントへまとめて送おくるのをやめ、本当ほんとうにスクロールすべきコンテナをスクロールします。これで下したのフォーム行ぎょうがようやく視野しやに入はいり、参照さんしょうも取とれるようになります。

第三だいさんの壁かべ（もっとも硬かたい）: クロスオリジン iframe 内ないの「有効ゆうこう」な送信そうしんボタンをクリックしても反応はんのうしない。 この段階だんかいがいちばん苦くるしいところでした。なぜなら、見みた目めにはすべて正ただしいからです。

• 実際じっさいのキー入力にゅうりょくで番号ばんごうを入いれた。get value で読よむと、たしかに入はいっている。
• 「保存」ボタンは有効ゆうこうになるべきタイミングで有効ゆうこうになった（正ただしい値あたいを入いれる前まえは disabled で、入力後にゅうりょくごに現あらわれる）。
• そして click @e41——フォームは微動びどうだにしない。find text "保存"？クロスオリジンなので取とれない。フォーカスして Enter / Space を押おす？それでも反応はんのうなし。

合あっているのに、どこもかしこも合あっていない。根本こんぽん原因げんいんは、クロスオリジン iframe 内ないの Material/フレームワーク系けいボタンが、合成ごうせいクリックを受うけ付つけないことでした。さらに、fill は入力にゅうりょくフィールドの値あたいだけを変かえ、フレームワークが必要ひつようとする input/change イベントを発火はっかしていませんでした。そのためフォーム側がわは「変化へんかしていない」と思おもい、保存ボタンは無効むこうのまま、またはクリックしても何なにも起おきない状態じょうたいになります。

解決かいけつは2つに分わかれます。値あたいの入力にゅうりょくは**実際じっさいのキー入力にゅうりょくに切きり替かえる（各かく文字もじが本物ほんもののイベントを発生はっせいさせるので、フレームワークが認識にんしきする）。クリックは、iframe 内ないのコンテンツノードに対たいして、ただ click() を被かぶせるのではなく、本物ほんもののマウス/キーボード起動きどう**を一式いっしき送おくる必要ひつようがあります。

仕上しあげ: 中なかにクリックして、保存する

3つの壁かべを越こえると、全体ぜんたいの流ながれがつながります。開ひらく → 目標もくひょう行ぎょうまでスクロール → スナップショットで参照さんしょうを取得しゅとく → 実際じっさいのキー入力にゅうりょくで値あたいを入いれる → 保存を押おす。あの「読よめるのに、完了かんりょうできない」詰つみは、ここで終おわりです。

同おなじように agent ブラウザ自動化じどうかをしている人ひとへ、血ちで得えた経験けいけん

• まずアクセシビリティ参照さんしょうを使つかい、デフォルトでスクリーンショットの座標ざひょうクリックに逃にげない。スナップショットが iframe を見みられるなら、参照さんしょうはピクセル推測すいそくよりずっと安定あんていします。スクリーンショットは canvas/WebGL のように、本当に構造こうぞうがない場面ばめんに残のこします。
• クロスオリジン iframe は明確めいかくな境界きょうかいです。セレクタと eval はそこで終おわりです。ツールに a11y ツリーを貫通かんつうさせるか、そうでなければ座標ざひょうを盲目的もうもくてきにクリックするしかありません。
• 「入力にゅうりょくできるか」だけでなく、「送信そうしんできるか」を測はかる。値あたいが入はいったこと ≠ フレームワークが受うけ取とったこと、です。fill がイベントを発火はっかしないような落おとし穴あなは、実際じっさいに保存をクリックしてはじめて露呈ろていします。
• 実際じっさいにログインしたブラウザを使つかえるなら、headless は避さける。ログイン状態じょうたい、cookie、拡張機能かくちょうきのうがすべてそのままあり、自動化じどうかフィンガープリントもありません——これが chrome-use が「あなた自身じしんの Chrome を操作そうさする」道みちを選えらぶ理由りゆうでもあります。

試ためす

curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh

リポジトリは github.com/leeguooooo/chrome-use にあります。私はずっと、このような「あなた自身じしんのサブスクリプションを使つかい、agent を実際じっさいのブラウザ/端末たんまつにつなぐ」ツールを作つくっています。進捗しんちょくは X @leeguooooo に投稿とうこうしています。

関連ドキュメント（英語）：chrome-use · Forms & Clicking、インストール。