マルチアカウント設定：クォータプーリングとロードバランシング

このチュートリアルで学べること

複数の Google アカウントを追加して、総クォータ上限を引き上げる
デュアルクォータシステムを理解し、Antigravity と Gemini CLI のクォータプールを効果的に活用する
アカウント数と利用シーンに応じた最適なロードバランシング戦略を選択する
マルチアカウント設定でよくある問題をトラブルシューティングする

今あなたが直面している課題

シングルアカウントで使用していると、以下のような問題に遭遇することがあります：

429 レート制限エラーが頻発し、クォータ回復を待たなければならない
開発・テスト環境で並行リクエストが多すぎて、1 つのアカウントでは対応しきれない
Gemini 3 Pro や Claude Opus モデルのクォータを使い切ると、翌日まで待つしかない
複数の OpenCode インスタンスや oh-my-opencode サブエージェントを並列実行すると、アカウント間で競合が発生する

どんな時にこの方法を使うべきか

マルチアカウント設定は以下のシーンに適しています：

シーン	推奨アカウント数	理由
個人開発	2〜3 個	バックアップアカウントで中断を回避
チーム開発	3〜5 個	リクエストを分散し、競合を軽減
高頻度 API 呼び出し	5 個以上	ロードバランシングでスループット最大化
並列エージェント	3 個以上 + PID オフセット	各エージェントに独立したアカウント

前提条件の確認

このチュートリアルを始める前に、以下が完了していることを確認してください：

✅ opencode-antigravity-auth プラグインをインストール済み
✅ OAuth 認証に成功し、最初のアカウントを追加済み
✅ Antigravity モデルでリクエストを送信できる状態

クイックインストール | 初回ログイン

基本的な仕組み

マルチアカウント設定の核となるメカニズム：

クォータプーリング：各 Google アカウントには独立したクォータがあり、複数アカウントのクォータを合算することでより大きなプールを形成
ロードバランシング：プラグインが自動的に利用可能なアカウントを選択し、レート制限に達したら次のアカウントに切り替え
デュアルクォータシステム（Gemini のみ）：各アカウントで Antigravity と Gemini CLI の 2 つの独立したクォータプールにアクセス可能
スマートリカバリ：レート制限の重複排除（2 秒ウィンドウ）+ 指数バックオフで、無駄なリトライを回避

クォータ計算の例：

各アカウントの Claude クォータが 1000 リクエスト/分の場合：

アカウント数	理論上の総クォータ	実際に利用可能（キャッシュ考慮）
1	1000/min	1000/min
3	3000/min	約 2500/min（sticky 戦略）
5	5000/min	約 4000/min（round-robin）

💡 なぜ sticky 戦略だと利用可能クォータが少なくなるのか？
sticky 戦略はレート制限に達するまで同じアカウントを使い続けるため、他のアカウントのクォータが遊休状態になります。ただし、Anthropic のプロンプトキャッシュを維持できるため、レスポンス速度が向上するというメリットがあります。

実践手順

ステップ 1：2 つ目のアカウントを追加する

なぜ必要か 2 つ目のアカウントを追加すると、メインアカウントがレート制限に達した際に、プラグインが自動的にバックアップアカウントに切り替え、リクエストの失敗を防ぎます。

操作手順

OAuth ログインコマンドを実行します：

bash

opencode auth login

すでにアカウントがある場合、以下のプロンプトが表示されます：

1 account(s) saved:
  1. [email protected]

(a)dd new account(s) or (f)resh start? [a/f]:

a を入力して Enter を押すと、ブラウザが自動的に Google 認証ページを開きます。

期待される結果：

ブラウザで Google OAuth 認証ページが開く
2 つ目の Google アカウントを選択またはログイン
認証を許可すると、ターミナルに以下が表示される：

Account added successfully!

2 account(s) saved:
  1. [email protected]
  2. [email protected]

TIP

ブラウザが自動的に開かない場合は、ターミナルに表示された OAuth URL をコピーして、手動でブラウザに貼り付けてください。

ステップ 2：マルチアカウントの状態を確認する

なぜ必要か アカウントが正しく追加され、利用可能な状態であることを確認します。

操作手順

アカウントストレージファイルを確認します：

bash

cat ~/.config/opencode/antigravity-accounts.json

期待される結果：

json

{
  "version": 3,
  "accounts": [
    {
      "email": "[email protected]",
      "refreshToken": "1//0abc...",
      "projectId": "project-id-123",
      "addedAt": 1737609600000,
      "lastUsed": 1737609600000
    },
    {
      "email": "[email protected]",
      "refreshToken": "1//0xyz...",
      "addedAt": 1737609700000,
      "lastUsed": 1737609700000
    }
  ],
  "activeIndex": 0,
  "activeIndexByFamily": {
    "claude": 0,
    "gemini": 0
  }
}

セキュリティに関する注意

antigravity-accounts.json には OAuth リフレッシュトークンが含まれており、パスワードファイルと同等の機密性があります。バージョン管理システムにコミットしないでください。

ステップ 3：アカウント切り替えをテストする

なぜ必要か マルチアカウントのロードバランシングが正常に動作していることを確認します。

操作手順

複数の並行リクエストを送信してレート制限をトリガーします：

bash

# macOS/Linux
for i in {1..10}; do
  opencode run "Test $i" --model=google/antigravity-claude-sonnet-4-5 &
done
wait

# Windows PowerShell
1..10 | ForEach-Object {
  Start-Process -FilePath "opencode" -ArgumentList "run","Test $_","--model=google/antigravity-claude-sonnet-4-5"
}

期待される結果：

最初の N 件のリクエストはアカウント 1（[email protected]）を使用
429 エラーが発生すると、自動的にアカウント 2（[email protected]）に切り替え
通知が有効な場合、「Switched to account 2」というトースト通知が表示される

アカウント切り替え通知

quiet_mode: false（デフォルト）が設定されている場合、プラグインはアカウント切り替え通知を表示します。初回の切り替えではメールアドレスが表示され、以降はアカウントインデックスのみが表示されます。

ステップ 4：デュアルクォータシステムを設定する（Gemini 専用）

なぜ必要か デュアルクォータフォールバックを有効にすると、Antigravity のクォータが枯渇した際に、プラグインが自動的に Gemini CLI のクォータを試行します。アカウントを切り替える必要がありません。

操作手順

プラグイン設定ファイルを編集します：

bash

# macOS/Linux
nano ~/.config/opencode/antigravity.json

# Windows
notepad %APPDATA%\opencode\antigravity.json

以下の設定を追加します：

json

{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "quota_fallback": true
}

ファイルを保存し、OpenCode を再起動します。

期待される結果：

Gemini モデル使用時、プラグインは優先的に Antigravity クォータを使用
Antigravity が 429 を返すと、同じアカウントの Gemini CLI クォータに自動切り替え
両方のクォータがレート制限に達した場合、次のアカウントに切り替え

デュアルクォータ vs マルチアカウント

デュアルクォータ：同一アカウント内の 2 つの独立したクォータプール（Antigravity + Gemini CLI）
マルチアカウント：複数アカウントのクォータプールを合算
ベストプラクティス：まずデュアルクォータを有効にし、その後マルチアカウントを追加

ステップ 5：アカウント選択戦略を選ぶ

なぜ必要か アカウント数や利用シーンによって最適な戦略が異なり、適切な選択でパフォーマンスを最大化できます。

操作手順

antigravity.json で戦略を設定します：

json

{
  "account_selection_strategy": "hybrid"
}

アカウント数に応じて選択してください：

アカウント数	推奨戦略	設定値	理由
1	sticky	`"sticky"`	プロンプトキャッシュを維持
2〜5	hybrid	`"hybrid"`	スループットとキャッシュのバランス
5 以上	round-robin	`"round-robin"`	スループット最大化

戦略の詳細：

sticky（シングルアカウントのデフォルト）：レート制限に達するまで同じアカウントを使い続ける。単一の開発セッションに最適
round-robin：リクエストごとに次のアカウントにローテーション。スループット最大化だがキャッシュは犠牲に
hybrid（マルチアカウントのデフォルト）：ヘルススコア + トークンバケット + LRU に基づく総合的な判断

期待される結果：

hybrid 戦略使用時、プラグインは自動的に最適なアカウントを選択
round-robin 戦略使用時、リクエストは全アカウントに均等に分散
sticky 戦略使用時、同一セッション内では常に同じアカウントを使用

ステップ 6：PID オフセットを有効にする（並列エージェント向け）

なぜ必要か 複数の OpenCode インスタンスや oh-my-opencode 並列エージェントを実行する際、異なるプロセスが同じアカウントを選択して競合が発生する可能性があります。

操作手順

antigravity.json に以下を追加します：

json

{
  "pid_offset_enabled": true
}

保存して OpenCode を再起動します。

期待される結果：

異なるプロセス（異なる PID）は異なるアカウントインデックスから開始
並列エージェント間のアカウント競合が軽減
全体的なスループットが向上

PID オフセットの仕組み

PID オフセットはプロセス ID をアカウントオフセットにマッピングします。例：

PID 100 → オフセット 0 → アカウント 0 から開始
PID 101 → オフセット 1 → アカウント 1 から開始
PID 102 → オフセット 2 → アカウント 2 から開始

チェックポイント ✅

上記のステップを完了すると、以下ができるようになります：

[ ] opencode auth login で複数の Google アカウントを追加
[ ] antigravity-accounts.json で複数のアカウントレコードを確認
[ ] レート制限に達すると、プラグインが自動的に次のアカウントに切り替え
[ ] Gemini モデルでデュアルクォータフォールバックを有効化
[ ] アカウント数に応じた適切なアカウント選択戦略を選択
[ ] 並列エージェントシーンで PID オフセットを有効化

よくあるトラブルと解決策

すべてのアカウントがレート制限に達した

症状：すべてのアカウントで 429 エラーが表示され、リクエストを続行できない

原因：クォータ枯渇または並行リクエストが多すぎる

解決策：

レート制限が自動的にリセットされるまで待つ（通常 1〜5 分）
長期的に問題が発生する場合は、アカウントを追加
設定の max_rate_limit_wait_seconds を確認し、適切な待機上限を設定

アカウント切り替えが頻繁すぎる

症状：リクエストごとにアカウントが切り替わり、同じアカウントが使用されない

原因：戦略の選択が不適切、またはヘルススコアの異常

解決策：

戦略を sticky に変更
health_score 設定を確認し、min_usable と rate_limit_penalty を調整
頻繁な 429 エラーによりアカウントが不健全とマークされていないか確認

Gemini CLI 権限エラー（403）

症状：Gemini CLI モデル使用時に Permission denied エラーが返される

原因：アカウントに有効な Project ID がない

解決策：

各アカウントに projectId を手動で追加：

json

{
  "accounts": [
    {
      "email": "[email protected]",
      "refreshToken": "...",
      "projectId": "your-project-id"
    }
  ]
}

Google Cloud Console で Gemini for Google Cloud API が有効になっていることを確認

トークン無効（invalid_grant）

症状：アカウントが自動的に削除され、invalid_grant エラーが表示される

原因：Google アカウントのパスワード変更、セキュリティイベント、またはトークンの期限切れ

解決策：

無効なアカウントを削除して再認証：

bash

rm ~/.config/opencode/antigravity-accounts.json
opencode auth login

頻繁に発生する場合は、より安定した Google アカウントの使用を検討

このチュートリアルのまとめ

マルチアカウント設定により、総クォータ上限とシステムの安定性が向上
アカウントの追加は簡単で、opencode auth login を繰り返し実行するだけ
デュアルクォータシステムにより、各 Gemini アカウントの利用可能クォータが 2 倍に
アカウント選択戦略はアカウント数と利用シーンに応じて調整すべき
PID オフセットは並列エージェントシーンで非常に重要

次のチュートリアル

次は アカウント選択戦略 を学びます。
学べる内容：
sticky、round-robin、hybrid の 3 つの戦略の詳細な動作原理
シーンに応じた最適な戦略の選び方
ヘルススコアとトークンバケットのチューニング方法

付録：ソースコード参照

クリックしてソースコードの場所を表示

更新日：2026-01-23

機能	ファイルパス	行番号
AccountManager クラス	`src/plugin/accounts.ts`	174-250
ロードバランシング戦略	`src/plugin/rotation.ts`	全体
設定スキーマ	`src/plugin/config/schema.ts`	全体
アカウントストレージ	`src/plugin/storage.ts`	全体

主要な定数：

定数名	値	説明
`QUOTA_EXHAUSTED_BACKOFFS`	`[60000, 300000, 1800000, 7200000]`	クォータ枯渇時のバックオフ時間（1分→5分→30分→2時間）
`RATE_LIMIT_EXCEEDED_BACKOFF`	`30000`	レート制限時のバックオフ時間（30秒）
`MIN_BACKOFF_MS`	`2000`	最小バックオフ時間（2秒）

主要な関数：

calculateBackoffMs(reason, consecutiveFailures, retryAfterMs)：バックオフ遅延を計算
getQuotaKey(family, headerStyle, model)：クォータキーを生成（モデルレベルのレート制限をサポート）
isRateLimitedForQuotaKey(account, key)：特定のクォータキーがレート制限されているかチェック
selectHybridAccount(accounts, family)：hybrid 戦略のアカウント選択ロジック

設定項目（schema.ts より）：

設定項目	型	デフォルト値	説明
`account_selection_strategy`	enum	`"hybrid"`	アカウント選択戦略
`quota_fallback`	boolean	`false`	Gemini デュアルクォータフォールバックを有効化
`pid_offset_enabled`	boolean	`false`	PID オフセットを有効化
`switch_on_first_rate_limit`	boolean	`true`	初回レート制限で即座に切り替え

マルチアカウント設定：クォータプーリングとロードバランシング ​

このチュートリアルで学べること ​

今あなたが直面している課題 ​

どんな時にこの方法を使うべきか ​

基本的な仕組み ​

実践手順 ​

ステップ 1：2 つ目のアカウントを追加する ​

ステップ 2：マルチアカウントの状態を確認する ​

ステップ 3：アカウント切り替えをテストする ​

ステップ 4：デュアルクォータシステムを設定する（Gemini 専用） ​

ステップ 5：アカウント選択戦略を選ぶ ​

ステップ 6：PID オフセットを有効にする（並列エージェント向け） ​

チェックポイント ✅ ​

よくあるトラブルと解決策 ​

すべてのアカウントがレート制限に達した ​

アカウント切り替えが頻繁すぎる ​

Gemini CLI 権限エラー（403） ​

トークン無効（invalid_grant） ​

このチュートリアルのまとめ ​

次のチュートリアル ​

付録：ソースコード参照 ​

マルチアカウント設定：クォータプーリングとロードバランシング

このチュートリアルで学べること

今あなたが直面している課題

どんな時にこの方法を使うべきか

基本的な仕組み

実践手順

ステップ 1：2 つ目のアカウントを追加する

ステップ 2：マルチアカウントの状態を確認する

ステップ 3：アカウント切り替えをテストする

ステップ 4：デュアルクォータシステムを設定する（Gemini 専用）

ステップ 5：アカウント選択戦略を選ぶ

ステップ 6：PID オフセットを有効にする（並列エージェント向け）

チェックポイント ✅

よくあるトラブルと解決策

すべてのアカウントがレート制限に達した

アカウント切り替えが頻繁すぎる

Gemini CLI 権限エラー（403）

トークン無効（invalid_grant）

このチュートリアルのまとめ

次のチュートリアル

付録：ソースコード参照