アカウント追加：OAuth/Refresh Token デュアルチャンネルとベストプラクティス
Antigravity Tools では、「アカウント追加」は Google アカウントの refresh_token をローカルアカウントプールに書き込み、後続のリバースプロキシリクエストをローテーションして使用できるようにすることです。OAuth ワンクリック認証を使用するか、refresh_token を直接貼り付けて手動追加できます。
学習後にできること
- OAuth または Refresh Token を使用して、Google アカウントを Antigravity Tools のアカウントプールに追加する
- 認証リンクをコピー/手動で開き、コールバック成功後に自動的に追加を完了する
refresh_tokenの取得、コールバックがlocalhostに接続できないなどの問題に遭遇した場合の対処方法を知る
現在の課題
- 「OAuth認証」をクリックしてもずっと読み込み中のまま、またはブラウザが
localhost refused to connectと表示される - 認証は成功したが、「Refresh Tokenが取得できません」と表示される
- 手元に
refresh_tokenしかなく、一度に一括インポートする方法がわからない
いつこの方法を使用するか
- 最も安定した方法でアカウントを追加したい場合（OAuth優先）
- 移行/バックアップを重視したい場合（Refresh Tokenは「アカウントプール資産」に適している）
- 多くのアカウントを追加し、
refresh_tokenを一括インポートしたい場合（テキスト/JSONからの抽出をサポート）
🎒 開始前の準備
- Antigravity Tools デスクトップ版をインストールし、開くことができる
- 入口を知っている：左側のナビゲーションから
Accountsページに入る（ルートはsource/lbjlaq/Antigravity-Manager/src/App.tsx）
このレッスンの2つのキーワード
OAuth：「ブラウザでログインして認証」するフロー。Antigravity Tools はローカルで一時的にコールバックアドレスを起動し（http://localhost/127.0.0.1/[::1]:<port>/oauth-callback、システムの IPv4/IPv6 監視状況に応じて自動選択）、ブラウザが code を持って戻ってきた後にトークンと交換します。（実装は source/lbjlaq/Antigravity-Manager/src-tauri/src/modules/oauth_server.rs）
refresh_token：「access_token を長期間更新できる認証情報」。プロジェクトでアカウントを追加する際、これを使用して最初に access_token を取得し、Google から実際のメールアドレスを取得し、フロントエンドで入力した email を無視します。（実装は source/lbjlaq/Antigravity-Manager/src-tauri/src/commands/mod.rs）
コアアイデア
Antigravity Tools の「アカウント追加」は、最終的に使用可能な refresh_token を取得し、アカウント情報をローカルアカウントプールに書き込むことを目的としています。
- OAuth チャンネル：アプリケーションが認証リンクを生成し、ローカルコールバックを監視します。認証完了後、自動的にトークンを交換してアカウントを保存します（
prepare_oauth_url、start_oauth_login、complete_oauth_loginを参照） - Refresh Token チャンネル：
refresh_tokenを直接貼り付け、アプリケーションがそれを使用して access_token を更新し、Google から実際のメールアドレスを取得して保存します（add_accountを参照）
手順に従って進める
ステップ 1：「アカウント追加」ダイアログを開く
なぜ すべての追加入口は Accounts ページで統一されています。
操作：Accounts ページに入り、右側の Add Account ボタンをクリックします（コンポーネント：AddAccountDialog）。
次のように表示されます：3つのタブページを含むダイアログが表示されます：OAuth / Refresh Token / Import（source/lbjlaq/Antigravity-Manager/src/components/accounts/AddAccountDialog.tsx を参照）
ステップ 2：優先して OAuth ワンクリック認証を使用する（推奨）
なぜ これが製品のデフォルト推奨パスです。アプリケーションが認証リンクを生成し、デフォルトブラウザを自動的に開き、コールバックが戻ってきたら自動的に保存を完了します。
OAuthタブに切り替えます。- 最初に認証リンクをコピーします。ダイアログが開くと、自動的に
prepare_oauth_urlを呼び出して URL を事前生成します（フロントエンド呼び出しはAddAccountDialog.tsx:111-125、バックエンド生成と監視はoauth_server.rs）。 - Start OAuth をクリックします（フロントエンド
startOAuthLogin()/ バックエンドstart_oauth_loginに対応）、アプリケーションにデフォルトブラウザを開かせ、コールバックを待機させます。
次のように表示されます：
- ダイアログにコピー可能な認証リンクが表示されます（イベント名：
oauth-url-generated） - ブラウザが Google 認証ページを開きます。認証後にローカルアドレスにリダイレクトし、「Authorization Successful!」と表示されます（
oauth_success_html()）
ステップ 3：OAuth が自動的に完了しない場合、「OAuth 完了」で手動で終了する
なぜ OAuth フローは2つのパートに分かれます：ブラウザ認証で code を取得し、その後アプリケーションが code でトークンと交換します。「Start OAuth」をクリックしなくても、認証リンクを手動で開いてコールバックを完了すれば、ダイアログは自動的に終了しようとします。終了に失敗した場合、手動で一度クリックできます。
- 「リンクをコピーして自分のブラウザで開く」場合（デフォルトブラウザではない）、認証コールバックが戻ってくると、アプリケーションは
oauth-callback-receivedイベントを受け取り、自動的にcompleteOAuthLogin()を呼び出します（source/lbjlaq/Antigravity-Manager/src/components/accounts/AddAccountDialog.tsx:67-109を参照）。 - 自動完了が表示されない場合、ダイアログ内の Finish OAuth をクリックします（バックエンド
complete_oauth_loginに対応）。
次のように表示されます：ダイアログが成功を通知し、自動的に閉じます。Accounts リストに新しいアカウントが表示されます。
小技：コールバックが接続できない場合はリンクをコピー優先
バックエンドは可能な限り同時に IPv6 ::1 と IPv4 127.0.0.1 を監視し、監視状況に応じて localhost/127.0.0.1/[::1] をコールバックアドレスとして選択します。これは主に「ブラウザが localhost を IPv6 に解釈する」ことによる接続失敗を回避するためです。（source/lbjlaq/Antigravity-Manager/src-tauri/src/modules/oauth_server.rs:53-113 を参照）
ステップ 4：Refresh Token で手動追加（一括対応）
なぜrefresh_token が取得できない場合（または「移行可能資産」を重視する場合）、Refresh Token で直接追加する方が制御しやすいです。
Refresh Tokenタブに切り替えます。refresh_tokenをテキストボックスに貼り付けます。
サポートされる入力形式（フロントエンドが解析して一括追加）：
| 入力タイプ | 例 | 解析ロジック |
|---|---|---|
| 純粋なトークンテキスト | 1//abc... | 正規表現抽出：/1\/\/[a-zA-Z0-9_\-]+/g（AddAccountDialog.tsx:213-220 を参照） |
| 大きなテキストに含まれる | ログ/エクスポートテキストに複数の 1//... が含まれる | 正規表現一括抽出と重複排除（AddAccountDialog.tsx:213-224 を参照） |
| JSON 配列 | [{"refresh_token":"1//..."}] | 配列を解析して item.refresh_token を取得（AddAccountDialog.tsx:198-207 を参照） |
Confirm をクリックすると、ダイアログはトークン数に応じて個別に onAdd("", token) を呼び出します（AddAccountDialog.tsx:231-248 を参照）、最終的にバックエンド add_account に到達します。
次のように表示されます：
- ダイアログが一括進行状況を表示します（例：
1/5） - 成功後、
Accountsリストに新しいアカウントが表示されます
ステップ 5：「アカウントプールが使用可能」を確認する
なぜ 追加成功は「すぐに安定して使用できる」という意味ではありません。バックエンドは追加後に自動的に「クォータ更新」を1回トリガーし、Proxy が実行中にトークンプールのリロードを試み、変更を即座に有効にします。
次の 2 つのシグナルで確認できます：
- アカウントがリストに表示され、メールアドレスが表示されます（メールアドレスはバックエンド
get_user_infoから取得、入力した email ではありません）。 - アカウントクォータ/サブスクリプション情報の更新が開始されます（バックエンドは自動的に
internal_refresh_account_quotaを呼び出します）。
次のように表示されます：追加後、手動で更新をクリックする必要はありません。アカウントがクォータ情報を表示し始めます（成功かどうかは実際のインターフェース表示に基づきます）。
チェックポイント ✅
- アカウントリストに追加されたアカウントのメールアドレスが表示される
- 受け入れられる時間より長く「loading」状態にとどまっていない（OAuth コールバック完了後はすぐに終了するはず）
- Proxy を実行している場合、追加されたアカウントがすぐにスケジュールに参加できる（バックエンドはリロードを試みます）
トラブルシューティング
1) OAuth が「Refresh Tokenが取得できません」と表示する場合
バックエンドは start_oauth_login/complete_oauth_login で refresh_token が存在するか明示的にチェックします。存在しない場合、解決策を含むエラー情報が返されます（source/lbjlaq/Antigravity-Manager/src-tauri/src/commands/mod.rs:45-56 を参照）。
ソースコードの指示に従って処理します：
https://myaccount.google.com/permissionsを開きます。- Antigravity Tools のアクセス権限を取り消します。
- アプリケーションに戻って OAuth を再試行します。
このレッスンの Refresh Token チャンネルに直接切り替えることもできます。
2) ブラウザが localhost refused to connect と表示する場合
OAuth コールバックにはブラウザがローカルコールバックアドレスをリクエストする必要があります。失敗率を下げるため、バックエンドは：
127.0.0.1と::1の両方を同時に監視しようとします- 両方が使用可能な場合のみ
localhostを使用し、そうでない場合は127.0.0.1または[::1]を強制的に使用します
対応する実装は source/lbjlaq/Antigravity-Manager/src-tauri/src/modules/oauth_server.rs:53-113 を参照してください。
3) 他のタブに切り替えると OAuth 準備がキャンセルされる
ダイアログが OAuth から他のタブに切り替わると、フロントエンドは cancelOAuthLogin() を呼び出し、URL をクリアします（AddAccountDialog.tsx:127-136 を参照）。
認証プロセス中の場合、タブを急いで切り替えないでください。
4) Refresh Token の正しい/間違った例
| 例 | 識別されるか | 理由 |
|---|---|---|
1//0gAbC... | ✓ | 1// 接頭辞ルールに適合（AddAccountDialog.tsx:215-219 を参照） |
ya29.a0... | ✗ | フロントエンド抽出ルールに適合せず、無効な入力とみなされます |
このレッスンのまとめ
- OAuth：「速さ」に適しており、リンクをコピーして常用ブラウザで開き、自動/手動で終了することも可能
- Refresh Token：「安定」と「移行性」に適しており、テキスト/JSON から
1//...を一括抽出をサポート refresh_tokenが取得できない場合、エラー指示に従って認証を取り消して再試行するか、直接 Refresh Token に切り替える
次のレッスン予告
次のレッスンでは、より確実なことを行います：アカウントプールを「移行可能資産」にします。
付録：ソースコード参照
クリックしてソースコードの場所を表示
更新日時：2026-01-23
| 機能 | ファイルパス | 行番号 |
|---|---|---|
| Accounts ページに追加ダイアログをマウント | src/pages/Accounts.tsx | 267-731 |
| OAuth URL 事前生成 + コールバックイベント自動終了 | src/components/accounts/AddAccountDialog.tsx | 49-125 |
OAuth コールバックイベントが completeOAuthLogin() をトリガー | src/components/accounts/AddAccountDialog.tsx | 67-109 |
| Refresh Token 一括解析と重複排除 | src/components/accounts/AddAccountDialog.tsx | 185-268 |
| フロントエンドが Tauri コマンドを呼び出す（add/OAuth/cancel） | src/services/accountService.ts | 5-91 |
| バックエンド add_account：email を無視、refresh_token を使用して実際のメールアドレスを取得し保存 | src-tauri/src/commands/mod.rs | 19-60 |
| バックエンド OAuth：refresh_token 欠如をチェックし、認証取り消しソリューションを提供 | src-tauri/src/commands/mod.rs | 38-79 |
| OAuth コールバック server：IPv4/IPv6 を同時に監視し redirect_uri を選択 | src-tauri/src/modules/oauth_server.rs | 43-113 |
| --- | --- | --- |
重要イベント名：
oauth-url-generated：バックエンドが OAuth URL を生成した後、フロントエンドに送信（oauth_server.rs:250-252を参照）oauth-callback-received：バックエンドがコールバックを受け取り、code を解析した後、フロントエンドに通知（oauth_server.rs:177-180/oauth_server.rs:232-235を参照）
重要コマンド：
prepare_oauth_url：認証リンクを事前生成し、コールバック監視を開始（src-tauri/src/commands/mod.rs:469-473を参照）start_oauth_login：デフォルトブラウザを開き、コールバックを待機（src-tauri/src/commands/mod.rs:339-401を参照）complete_oauth_login：ブラウザを開かず、コールバックのみを待機し、トークン交換を完了（src-tauri/src/commands/mod.rs:405-467を参照）add_account：refresh_token を使用してアカウントを保存（src-tauri/src/commands/mod.rs:19-60を参照）