CLIProxyAPI（二）：多账号轮询与配额策略

这是 CLIProxyAPI 系列教程的第二篇。

系列目录

1. （一）入门——把 CLI 订阅变成标准 API
2. （二）多账号轮询与配额策略（本文）
3. （三）接入主流 AI 编程工具
4. （四）生产部署——Nginx、TLS 与安全加固
5. （五）Antigravity——用 Google 订阅解锁 Claude Opus 4.8
6. （六）结合 new-api 打造多用户 API 网关
7. （七）自动化运维——配额监控与告警
8. （八）cpa_keeper 与 cpa_cost——用量追踪与成本分析工具

为什么需要多账号

单个 Claude Pro 账号的配额在高强度使用下很快见顶——每隔几小时就会触发速率限制，打断工作流。多账号策略的核心思路是：把若干个订阅账号的配额池叠加在一起，由代理层透明地分摊请求。

好处显而易见：

• 配额成倍增加，不再因为一个账号触顶就卡住
• 某个账号临时失效（Token 过期、网络故障）时自动降级到其他账号
• 不同来源（Claude、Gemini、Qwen）可以混合在同一个端点，按需路由

多账号登录操作

CLIProxyAPI 支持对同一个 Provider 多次登录，每次登录完成后对应的认证文件自动追加到 auth-dir 目录，代理会把目录下所有有效凭证纳入轮询池，无需重启服务。

操作步骤

重复执行 login 命令，每次在浏览器里切换到不同的账号：

# 第一次：账号 A
cliproxyapi --claude-login

# 浏览器登录账号 A，完成后回到终端
# 再次执行，浏览器切换到账号 B

# 第二次：账号 B
cliproxyapi --claude-login

# 第三次：账号 C
cliproxyapi --claude-login

Gemini 同理：

cliproxyapi --login    # 账号 A
cliproxyapi --login    # 账号 B（浏览器切换）

Qwen / Kimi 使用设备码登录，只需用不同账号扫码：

cliproxyapi --qwen-login    # 账号 A，扫码
cliproxyapi --qwen-login    # 账号 B，换账号扫码

查看已登录账号

登录完成后，auth-dir（默认 ~/.cliproxyapi/auth/）下会出现多个凭证文件：

也可以通过管理 API 查看（详见后文）。

routing.strategy：两种轮询策略

在 config.yaml 的 routing 节点下，通过 strategy 字段选择分发策略。

routing:
  strategy: round-robin   # 或 fill-first

round-robin（均匀轮询）

每个请求依次分配给下一个账号，像轮盘一样循环：

请求 1 → 账号 A
请求 2 → 账号 B
请求 3 → 账号 C
请求 4 → 账号 A
...

适用场景：

• 账号配额接近、不希望某个账号提前耗尽
• 并发请求多，需要均匀打散负载
• 多人共享同一个代理端点

fill-first（填满优先）

优先把请求打到第一个账号，直到它触顶或不可用，再切换到下一个：

请求 1-N → 账号 A（直到配额耗尽）
请求 N+1 起 → 账号 B
...

适用场景：

• 账号配额各不相同，想优先消耗主账号
• 副账号只作为备份，正常情况下不动
• 需要最大化利用某个账号的免费额度后再切换

策略对比

quota-exceeded：配额超限自动切换

当某个账号触发速率限制（返回 429 或配额耗尽），CLIProxyAPI 可以自动切换到下一个账号，避免请求失败。

在 config.yaml 中启用：

quota-exceeded:
  switch-project: true

启用后，代理会：

1. 检测到配额超限响应
2. 将当前账号暂时标记为不可用
3. 自动重试，将请求路由到下一个可用账号
4. 一段时间后重新探测原账号是否恢复

结合 fill-first 策略效果最好——主账号耗尽后自动切到备用，对客户端完全透明。

routing:
  strategy: fill-first

quota-exceeded:
  switch-project: true

前缀路由：把请求定向到特定账号

有时你需要强制指定某些请求只走特定账号，例如：工作项目只用公司账号、个人项目用自己账号。CLIProxyAPI 支持通过 前缀路由 实现这个需求。

在 config.yaml 的 routing.prefix 字段配置映射关系：

routing:
  prefix:
    work: claude_account_b    # 前缀 "work" 路由到账号 B
    personal: claude_account_a

客户端请求时，把模型名写成 前缀/模型名 格式：

# 走 claude_account_b
curl http://localhost:8317/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -d '{"model": "work/claude-opus-4-5", "messages": [...]}'

# 走 claude_account_a
curl http://localhost:8317/v1/chat/completions \
  -d '{"model": "personal/claude-opus-4-5", "messages": [...]}'

前缀对客户端来说是透明的标签，代理在转发时会把前缀剥离，只把真实模型名传给后端。

Session Affinity：同一对话绑定同一账号

多轮对话场景下，如果每次请求都随机路由到不同账号，模型不会有跨请求的状态保持（本身也不会有），但某些上下文（如系统提示缓存）在账号间无法共享，可能导致行为不一致。

启用 Session Affinity 后，同一个会话（基于请求头中的 Session ID）会始终绑定到同一个账号：

routing:
  session-affinity: true

CLIProxyAPI 会从请求头 X-Session-Id 读取会话标识，客户端每次请求时带上相同的值即可：

curl http://localhost:8317/v1/chat/completions \
  -H "X-Session-Id: my-project-session-001" \
  -d '{"model": "claude-opus-4-5", "messages": [...]}'

如果客户端不支持自定义请求头，也可以用前缀路由代替：把同一个项目的所有请求都打到同一个前缀。

适用场景：

• 需要跨请求利用 Prompt Cache 的场景
• 同一个 Agent 循环需要在同一账号上下文中运行
• 调试时固定账号，方便追踪日志

oauth-model-alias：统一对外暴露模型名

不同 Provider 的模型名五花八门，切换来源时客户端配置也要跟着改。oauth-model-alias 字段让你给任意模型起别名，对外统一暴露一个名字：

oauth-model-alias:
  smart: claude-opus-4-5          # "smart" 指向 Claude Opus
  fast: gemini-2.5-flash          # "fast" 指向 Gemini Flash
  code: claude-sonnet-4-5         # "code" 指向 Claude Sonnet
  cheap: qwen-max                 # "cheap" 指向 Qwen

客户端直接用别名请求：

curl http://localhost:8317/v1/chat/completions \
  -d '{"model": "smart", "messages": [...]}'

代理把 smart 解析为 claude-opus-4-5，再路由到对应的 Claude 账号池。

别名的好处：将来换模型或换 Provider，只需改 config.yaml，客户端配置零改动。

多来源混用：Claude + Gemini + Qwen 按模型路由

CLIProxyAPI 支持同时接入多个不同 Provider，根据请求的模型名自动选择正确的后端。无需额外配置，代理会根据模型名前缀识别来源：

• claude-* → Claude Code 账号池（端口 54545）
• gemini-* → Gemini CLI 账号池（端口 8085）
• qwen-* → Qwen 账号池

结合模型别名，可以把多来源完全隐藏在统一别名后面：

oauth-model-alias:
  default: claude-opus-4-5     # 默认用 Claude
  vision: gemini-2.5-pro       # 视觉任务用 Gemini
  translate: qwen-max          # 翻译任务用 Qwen（便宜）

这样客户端只需要按功能选别名，完全不用关心底层是哪个 Provider。

通过管理 API 查看账号状态

CLIProxyAPI 提供了一套管理 API，路径统一以 /v0/management/ 开头。

首先确保 config.yaml 中开启了远程管理（本地调试时默认允许）：

remote-management:
  allow-remote: true
  password: "your-strong-password"

查看所有账号状态

curl http://localhost:8317/v0/management/accounts \
  -H "Authorization: Bearer your-strong-password"

返回示例：

{
  "accounts": [
    {
      "id": "claude_account_a",
      "provider": "claude",
      "status": "active",
      "quota_remaining": 8420,
      "last_used": "2026-06-05T21:30:00Z"
    },
    {
      "id": "claude_account_b",
      "provider": "claude",
      "status": "quota_exceeded",
      "quota_remaining": 0,
      "last_used": "2026-06-05T20:15:00Z"
    },
    {
      "id": "gemini_account_a",
      "provider": "gemini",
      "status": "active",
      "quota_remaining": 15000,
      "last_used": "2026-06-05T21:28:00Z"
    }
  ]
}

上传凭证文件

如果你在另一台机器上完成了 OAuth 登录，可以直接上传凭证文件：

curl -X POST http://localhost:8317/v0/management/credentials \
  -H "Authorization: Bearer your-strong-password" \
  -F "file=@claude_account_d.json" \
  -F "provider=claude"

上传后无需重启，代理立即将新凭证加入轮询池。

删除凭证文件

curl -X DELETE http://localhost:8317/v0/management/credentials/claude_account_b \
  -H "Authorization: Bearer your-strong-password"

实战配置示例

以下是一个完整的 config.yaml 片段，涵盖 3 个 Claude 账号 + 2 个 Gemini 账号的典型配置：

port: 8317

api-keys:
  - "sk-your-shared-api-key-here"

auth-dir: ~/.cliproxyapi/auth/

proxy-url: "http://127.0.0.1:7890"   # 按需填写

remote-management:
  allow-remote: false        # 仅本地访问时设为 false
  password: "change-me-please"

routing:
  strategy: round-robin      # 均匀分摊请求
  session-affinity: true     # 同一会话绑定同一账号

  prefix:
    work: claude_account_a   # work/model-name 强制走账号 A
    backup: claude_account_c # backup/model-name 走账号 C（保留备用）

quota-exceeded:
  switch-project: true       # 配额超限自动切换

oauth-model-alias:
  smart: claude-opus-4-5
  fast: gemini-2.5-flash
  balanced: claude-sonnet-4-5
  vision: gemini-2.5-pro

对应的 auth-dir 目录结构：

启动服务后，用 smart 别名发请求，代理会在三个 Claude 账号间均匀轮询；触发配额限制时自动切换；work/smart 格式则强制走账号 A。

小结

多账号策略让 CLIProxyAPI 从"个人工具"升级为"团队级 API 网关"——配额翻倍、高可用、统一入口。

系列导航

• （一）入门——把 CLI 订阅变成标准 API
• （二）多账号轮询与配额策略（本文）
• （三）接入主流 AI 编程工具
• （四）生产部署——Nginx、TLS 与安全加固
• （五）Antigravity——用 Google 订阅解锁 Claude Opus 4.8
• （六）结合 new-api 打造多用户 API 网关
• （七）自动化运维——配额监控与告警
• （八）cpa_keeper 与 cpa_cost——用量追踪与成本分析工具

实操清单

• routing.strategy 设为 round-robin（已配置）
• quota-exceeded.switch-project / switch-preview-model 开启（已配置）
• Remote management API 开启（allow-remote: true，已配置）
• 登录第 2 个 Claude 账号（--claude-login），实现真正的多账号轮询
• 登录 Gemini CLI 账号（Gemini Studio 账号已登录，gemini-cli 渠道已激活）
• 验证轮询效果：通过 /v0/management/auth-files 确认 antigravity/claude/gemini-cli 三个渠道均 active
• 根据账号配额高低调整 weight 权重
• 评估是否启用 session-affinity（当前 false，多账号 session 场景才需要开启）
• 按需配置 routing.prefix 前缀路由（按模型类型分流 Claude / Gemini）
• 按需配置 model-aliases，把 gpt-4o 等名称映射到实际模型