多账户设置：配额池化与负载均衡

学完你能做什么

添加多个 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 并回车，浏览器会自动打开 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`	首次限速立即切换

10 分钟跑起来

解锁双配额系统

搞定多账户

认证失败怎么办

彻底搞懂插件原理

版本历史速览

多账户设置：配额池化与负载均衡

学完你能做什么

你现在的困境

什么时候用这一招

核心思路

跟我做

第 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） ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

多账户设置：配额池化与负载均衡

学完你能做什么

你现在的困境

什么时候用这一招

核心思路

跟我做

第 1 步：添加第二个账户

第 2 步：验证多账户状态

第 3 步：测试账户切换

第 4 步：配置双配额系统（Gemini 专用）

第 5 步：选择账户选择策略

第 6 步：启用 PID 偏移（并行代理场景）

检查点 ✅

踩坑提醒

所有账户都被限速

账户切换过于频繁

Gemini CLI 权限错误（403）

令牌无效（invalid_grant）

本课小结

下一课预告

附录：源码参考