多帳戶設定：配額池化與負載均衡

學完你能做什麼

新增多個 Google 帳戶，提升整體配額上限
理解雙配額系統，有效利用 Antigravity 和 Gemini CLI 配額池
根據帳戶數量和使用情境選擇合適的負載均衡策略
排查多帳戶設定中的常見問題

你現在的困境

單帳戶使用時，你可能會遇到這些痛點：

頻繁遇到 429 速率限制錯誤，不得不等待配額恢復
開發/測試情境中並行請求太多，一個帳戶扛不住
Gemini 3 Pro 或 Claude Opus 模型的配額用完後，只能等待隔天
並行執行多個 OpenCode 實例或 oh-my-opencode 子代理時，帳戶間競爭激烈

什麼時候用這一招

多帳戶設定適合以下情境：

情境	建議帳戶數	原因
個人開發	2-3 個	備用帳戶，避免中斷
團隊協作	3-5 個	分攤請求，減少競爭
高頻 API 呼叫	5+ 個	負載均衡，最大化吞吐量
並行代理	3+ 個 + PID 偏移	每個 Agent 獨立帳戶

前置檢查

開始本教學前，請確保你已經完成：

✅ 安裝了 opencode-antigravity-auth 外掛
✅ 成功通過 OAuth 認證並新增了第一個帳戶
✅ 可以使用 Antigravity 模型發起請求

快速安裝教學 | 首次登入教學

核心思路

多帳戶設定的核心機制：

配額池化：每個 Google 帳戶都有獨立的配額，多個帳戶的配額疊加後形成更大的總池
負載均衡：外掛自動選擇可用帳戶，遇到速率限制時切換到下一個帳戶
雙配額系統（僅 Gemini）：每個帳戶可存取 Antigravity 和 Gemini CLI 兩個獨立的配額池
智慧恢復：速率限制去重（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 步：新增第二個帳戶

為什麼 新增第二個帳戶後，當主帳戶遇到速率限制時，外掛會自動切換到備用帳戶，避免請求失敗。

操作

執行 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 授權頁面
選擇或登入你的第二個 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 refresh tokens，等同於密碼檔案。請勿提交到版本控制系統。

第 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" 的 toast 提示

帳戶切換通知

如果啟用了 quiet_mode: false（預設），外掛會顯示帳戶切換通知。首次切換會顯示電子郵件地址，後續只顯示帳戶索引。

第 4 步：設定雙配額系統（Gemini 專用）

為什麼 啟用雙配額 fallback 後，當 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 多帳戶

雙配額：同一個帳戶的兩個獨立配額池（Antigravity + Gemini CLI）
多帳戶：多個帳戶的配額池疊加
最佳實踐：先啟用雙配額，再新增多帳戶

第 5 步：選擇帳戶選擇策略

為什麼 不同的帳戶數量和使用情境需要不同的策略，以達到最佳效能。

操作

在 antigravity.json 中設定策略：

json

{
  "account_selection_strategy": "hybrid"
}

根據你的帳戶數選擇：

帳戶數	建議策略	設定值	原因
1	sticky	`"sticky"`	保持 prompt cache
2-5	hybrid	`"hybrid"`	平衡吞吐量和快取
5+	round-robin	`"round-robin"`	最大化吞吐量

策略詳解：

sticky（預設單帳戶）：保持使用同一帳戶直到速率限制，適合單一開發工作階段
round-robin：每個請求輪換到下一個帳戶，最大化吞吐量但犧牲快取
hybrid（預設多帳戶）：基於健康評分 + Token bucket + 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 模型啟用了雙配額 fallback
[ ] 根據帳戶數量選擇了合適的帳戶選擇策略
[ ] 並行代理情境啟用了 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 帳戶的可用配額翻倍
帳戶選擇策略應根據帳戶數量和使用情境調整
PID 偏移對於並行代理情境至關重要

下一課預告

下一課我們學習 帳戶選擇策略。
你會學到：
sticky、round-robin、hybrid 三種策略的詳細運作原理
如何根據情境選擇最佳策略
健康評分和 Token bucket 的調校方法

附錄：原始碼參考

點擊展開查看原始碼位置

更新時間：2026-01-23

功能	檔案路徑	行號
AccountManager 類別	`src/plugin/accounts.ts`	174-250
負載均衡策略	`src/plugin/rotation.ts`	全文
設定 Schema	`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 雙配額 fallback
`pid_offset_enabled`	boolean	`false`	啟用 PID 偏移
`switch_on_first_rate_limit`	boolean	`true`	首次限速立即切換

多帳戶設定：配額池化與負載均衡 ​

學完你能做什麼 ​

你現在的困境 ​

什麼時候用這一招 ​

核心思路 ​

跟我做 ​

第 1 步：新增第二個帳戶 ​

第 2 步：驗證多帳戶狀態 ​

第 3 步：測試帳戶切換 ​

第 4 步：設定雙配額系統（Gemini 專用） ​

第 5 步：選擇帳戶選擇策略 ​

第 6 步：啟用 PID 偏移（並行代理情境） ​

檢查點 ✅ ​

踩坑提醒 ​

所有帳戶都被限速 ​

帳戶切換過於頻繁 ​

Gemini CLI 權限錯誤（403） ​

權杖無效（invalid_grant） ​

本課小結 ​

下一課預告 ​

附錄：原始碼參考 ​

多帳戶設定：配額池化與負載均衡

學完你能做什麼

你現在的困境

什麼時候用這一招

核心思路

跟我做

第 1 步：新增第二個帳戶

第 2 步：驗證多帳戶狀態

第 3 步：測試帳戶切換

第 4 步：設定雙配額系統（Gemini 專用）

第 5 步：選擇帳戶選擇策略

第 6 步：啟用 PID 偏移（並行代理情境）

檢查點 ✅

踩坑提醒

所有帳戶都被限速

帳戶切換過於頻繁

Gemini CLI 權限錯誤（403）

權杖無效（invalid_grant）

本課小結

下一課預告

附錄：原始碼參考