メインコンテンツへ移動
AIチュートリアル

Chrome Relayでコーディングエージェントからログイン済みのChromeを操作する

macOSにChrome Relayをインストールし、対応するコーディングエージェントを普段使いのChromeプロファイルに接続して、agent-browserでログイン済みのWebサイトを自動化する方法を学びます。ログイン情報とIDの管理、監査記録の確認、リレーのトラブルシューティングや更新についても説明します。

約14分で読了
Chrome Relayでコーディングエージェントからログイン済みのChromeを操作する

Chrome Relayとは？

Chrome Relayを使うと、対応するコーディングエージェントから、普段使っているGoogle Chromeのプロファイルをコマンドライン経由で利用できます。エージェントは、すでにログインしているサイトにアクセスしながら、非アクティブなバックグラウンドタブで作業できるため、現在のウィンドウからフォーカスを奪うことなく自動化を実行できます。

Chrome Relayプロジェクトの概要

このプロジェクトはClaude Code、Codex、Cursor、Paseoに対応しています。agent-browserを介して、これらのブラウザーコマンドをChromeに接続します。コマンドは通常約0.15秒で完了し、Chromeにリモートデバッグポートは必要ありません。

Chrome Relayはオプトイン方式です。拡張機能を自動インストールすることはなく、所有者がセットアップを完了したMacでのみ実行されます。

Chrome Relayの仕組み

agent-browser CLI → ローカルリレー → Chrome Relay拡張機能 → エージェントタブ

システムは主に次の3つのコンポーネントで構成されています。

  • Chrome拡張機能: エージェントに使用させる各Chromeプロファイルへ個別に読み込む、展開済みのManifest V3拡張機能です。非アクティブで折りたたまれたAgentsタブグループにエージェントタブを開き、chrome.debugger経由でDevToolsコマンドを送信します。
  • ローカルリレー: 127.0.0.1:9333で待ち受けるLaunchAgentです。エージェントごとに個別のDevToolsエンドポイントを提供し、エージェントが自ら開いたタブだけにアクセスできるよう制限します。
  • コマンドラインツール: chrome-relayコマンドが、セットアップ、接続URL、ID、更新、診断、ログ、監査記録を処理します。

リレーは、Chromeを起動したりフォーカスしたりする可能性のあるコマンドを抑止します。エージェントの作業中、ChromeにChrome Relay started debugging this browserというメッセージが表示される場合があります。

必要条件

インストール前に、次のものがあることを確認してください。

  • macOS
  • Google Chrome
  • Node.js 20以降
  • グローバルにインストールしたagent-browser

npmでagent-browserをインストールします。

npm i -g agent-browser

Chrome Relayをインストールする

1. プロジェクトをクローンして設定する

git clone https://github.com/aindeev/agent-chrome-relay
cd agent-chrome-relay
bin/chrome-relay setup

セットアップコマンドは、ローカルシークレットの作成、バックグラウンドサービスの設定、IDの記録、chrome-relayのPATHへの追加、Claude Code用Chrome Relayスキルのリンクを行います。

2. Chromeに拡張機能を読み込む

エージェントに使用させる各Chromeプロファイルで、次の手順を繰り返します。

  1. chrome://extensionsを開きます。
  2. デベロッパーモードを有効にします。
  3. パッケージ化されていない拡張機能を読み込むを選択します。
  4. リポジトリのextensionフォルダーを選択します。

Chromeプロファイルごとに拡張機能のコピーを読み込むため、明示的に選択したプロファイルだけを公開できます。

3. インストールを確認する

chrome-relay doctor

エージェントにブラウジングを依頼する前に、診断結果を使ってリレーと拡張機能が正しく設定されていることを確認してください。

コーディングエージェントにChrome Relayを認識させる

Claude Code

セットアップ処理により、skill/SKILL.mdが~/.claude/skills/chrome-relayにリンクされます。これにより、すべてのリポジトリでスキルを利用できます。明示的な指示が必要な場合でも、リポジトリレベルのCLAUDE.mdには、そのスキルへの1行の参照を追加するだけで済みます。

Codex、Cursor、その他の対応エージェント

エージェントのグローバル指示から、同じスキルファイルを参照するようにします。たとえば、~/.codex/AGENTS.mdに次のような指示を追加します。

ログイン情報が必要なブラウザー操作では、/path/to/agent-chrome-relay/skill/SKILL.md に従ってください。

例のパスを、クローンしたリポジトリの絶対パスに置き換えてください。

最初のブラウザー自動化を実行する

まずChrome Relayに認証済み接続URLを要求し、そのURLをagent-browserに渡します。

agent-browser --cdp "$(chrome-relay url you@company.com)" open https://app.example.com/
agent-browser snapshot -i
agent-browser click @e5
agent-browser close

you@company.comを設定済みの適切なIDに置き換え、例のサイトを自動化したいページに置き換えてください。

  1. chrome-relay urlは、このMacのシークレットを含む接続URLを出力します。
  2. agent-browser openは、エージェント専用の非アクティブなタブを作成し、指定したページを開きます。
  3. snapshot -iは、リンク、ボタン、入力欄などの操作可能なコントロールを一覧表示します。それぞれに@e5のような参照が割り当てられます。
  4. click @e5は、バックグラウンドタブで実際の入力エミュレーションを使い、指定された要素を操作します。
  5. closeはブラウザーセッションを終了します。

ログイン動作を理解する

エージェントが認証情報を入力することはありません。サイトがGoogleを経由してリダイレクトし、正しいアカウントにすでにログインしている場合、拡張機能がそのアカウントを選択し、続行または許可をクリックできます。これはページスクリプトを使用するため、1Passwordがページ上にフレームを配置している場合でも動作します。

フローがパスワード、パスキー、2段階認証、またはログアウト済みアカウントの画面に到達すると、自動化は停止します。エージェントにはSIGN-IN NEEDEDメッセージが表示され、自分のウィンドウでログインを完了するよう求められます。

プロファイルとサイトのIDを管理する

IDの設定は~/.chrome-relay/identities.jsonに保存されます。次のコマンドで確認または管理できます。

chrome-relay identities

この設定には、セットアップ中に検出されたChromeプロファイル、任意で手動設定したsites.rules、およびサインインの切り替えに成功した後に記録されたsites.learnedのエントリが含まれます。デフォルトでは、サイトは選択したChromeプロファイルに属するアカウントを使用します。

セキュリティモデル

すべてのエージェント接続は、次の2つのチェックを通過する必要があります。

  1. ローカルシークレット: セットアップ時に、ファイルモード600のトークンが~/.chrome-relay/tokenに生成されます。このトークンは、chrome-relay urlが表示するURLに埋め込まれます。
  2. 許可されたエージェントアプリケーション: 接続プロセスは、Claude Code、Codex、Cursor、またはPaseoに関連付けられている必要があります。リレーはプロセスと、これらのアプリケーションが子プロセスに設定するマーカーを調べます。

ブラウザーのOriginヘッダーを含む接続は、シークレットを持っていても拒否されます。拡張機能についても、Chromeから導出された拡張機能ID、chrome-extension://オリジン、そして接続プロセスがChromeであることが確認されます。

これらの制御により、無関係なローカルツール、Webページ、偶発的な接続を排除できます。ただし、すでにユーザーとして実行されているマルウェアに対するセキュリティ境界ではありません。そのようなソフトウェアはシークレットを読み取り、プロセスマーカーを偽装できるためです。

監査証跡の確認

Chrome Relayは、エージェントのアクティビティを~/.chrome-relay/audit/YYYY-MM-DD.jsonl配下の日次JSON Linesファイルに記録します。次のコマンドで記録を読み取れます。

chrome-relay audit

監査証跡には、接続の詳細、作業フォルダー、セッション識別子、訪問したページ、クリック位置、特殊キー、エージェントスクリプト、スクリーンショット、アップロード、ポップアップ、サインインのクリック、ブロックされたページが含まれます。プライバシー保護のため、入力したテキストは文字数のみで表され、URLのクエリ文字列は削除されます。

高度な動作とヒント

ポップアップと新しいタブ

target=_blankを使用するリンクとポップアップは、同じエージェントが所有する非表示のタブとして開きます。ポップアップによる認証フローでは、オープナーにメッセージを返して自ら閉じることもできます。リレーは、ページの申告を信頼するのではなく、観測されたメッセージのオリジンとtargetOriginを強制します。

1Passwordのページ

ログインフォーム上の1Passwordメニューなど、ページに別の拡張機能のフレームが含まれていると、Chromeが拡張機能デバッガーを切断することがあります。Chrome Relayは待機してから再接続し、その後エージェントのコマンドを続行します。

自動クリーンアップ

エージェントのタブは、30分間操作がないと閉じられます。リレーの再起動時には、拡張機能も以前に開いたタブを閉じます。クリーンアップはタブIDに基づくため、ユーザー自身のタブグループは変更されません。

バックグラウンド入力

エージェントのタブではフォーカスエミュレーションが有効なままになります。これにより、現在のChromeタブをそのままにして、非アクティブなタブにもクリックや入力を送れます。

Chrome Relayの更新、診断、削除

リポジトリの変更を取得した後、リレーを再起動し、設定済みの各プロファイルで拡張機能を再読み込みします。

git pull
chrome-relay update

次のコマンドでリレーのログを確認できます。

chrome-relay logs

ログファイルは~/.chrome-relay/relay.logに保存されます。ローカルサービスとコマンドライン設定をアンインストールするには、次を実行します。

chrome-relay uninstall

その後、各Chromeプロファイルから展開した拡張機能を手動で削除します。

開発とテスト

リレーの依存関係をインストールしてテストスイートを実行するには、次のコマンドを使用します。

cd relay && npm install && npm test

テストでは、シークレット、許可されたアプリケーション、Chrome専用の拡張機能接続、監査動作など、接続認証を検証します。extension/配下のファイルを編集した後は、次のコマンドで拡張機能を再読み込みします。

chrome-relay update

カスタム環境では、CHROME_RELAY_HOMEでデータディレクトリを、CHROME_RELAY_PORTでリレーポートを上書きできます。

まとめ

Chrome Relayを使うと、リモートデバッグポートを必要としたり、アクティブなウィンドウを奪ったりせずに、対応するコーディングエージェントから既存のChromeセッションへ制御されたアクセスを提供できます。ローカルリレーと展開した拡張機能を設定すれば、agent-browserで認証済みブラウザータスクを自動化し、プロファイルまたはサイトごとにIDを選択し、プライバシーに配慮した詳細な監査記録を確認し、放置されたセッションを自動クリーンアップに任せることができます。

ソースコード、更新情報、問題の報告については、Chrome RelayのGitHubリポジトリをご覧ください。本プロジェクトはMITライセンスで提供されています。