CLIProxyAPI 的多账号路由如何工作

CLIProxyAPI 可以同时保存多个 OAuth 账号和上游 API Key。客户端仍然只连接一个地址，使用一枚客户端密钥并提交一个模型名称；CLIProxyAPI 会从能够处理这次请求的凭据中选择一个访问上游模型。

这里的多账号管理，指的是上游凭据的筛选、轮询、会话绑定、重试和冷却，不是为多个下游用户开户、设置余额或生成持久化账单。

如果还没有完成安装、模型接入和本机请求验证，先参照 CLIProxyAPI 简明部署指南。单个账号能够完成真实请求后，再增加其他账号，更容易判断问题出在凭据、路由还是客户端配置。

一个客户端入口，多个上游凭据

多个账号接入后，请求链路仍然只有一个客户端入口：

AI 客户端
→ CLIProxyAPI
→ 筛选能够处理目标模型的凭据
→ 选择或复用一个可用凭据
→ 上游模型服务

OAuth 账号和上游 API Key 都属于上游凭据。客户端使用的则是 config.yaml 顶层 api-keys 中的客户端密钥，两者不能混用。

CLIProxyAPI 不会在所有账号中盲目轮询。它会先根据模型、模型来源和前缀确定候选凭据，再从中选择一个，或者复用会话已经绑定的凭据。客户端通常不需要知道最终使用了哪个实际账号；只有通过前缀划分账号组时，客户端才会主动缩小候选范围。

一次请求如何选择账号

一次请求从进入 CLIProxyAPI 到访问上游，主要经过以下阶段：

轮询、加权和优先使用

全局路由策略由 routing.strategy 设置：

routing:
  strategy: "round-robin"

当前配置模板提供三种策略：

使用加权轮询时，API Key 凭据在对应配置项中设置整数 weight；OAuth 和其他文件凭据则在认证 JSON 顶层设置数值 weight。省略时权重为 1，最大值为 1,000,000；非正数会在加权轮询启用时排除该凭据。

权重较高的凭据会承担更大比例的请求，但权重表达的是预期分配比例，不会实时测量账号的剩余额度，也不能代替限流和可用性判断。

让同一会话继续使用同一凭据

普通轮询可能让同一段会话的连续请求落到不同凭据。需要保持会话与凭据的对应关系时，可以开启会话亲和：

routing:
  strategy: "round-robin"
  session-affinity: true
  session-affinity-ttl: "1h"

CLIProxyAPI 会优先使用 Claude Code、Codex、OpenCode 和 pi 等客户端发送的会话标识，也会识别 prompt_cache_key、Responses 对话 ID 等信息。绑定建立后，同一会话会继续使用原凭据；原凭据不可用时仍会自动切换，并为后续请求建立新的绑定。

会话亲和与路由策略不是两种互斥模式。路由策略负责首次绑定、没有会话标识的请求以及故障切换后的重新绑定；已有且可用的会话绑定优先于凭据顺序。

用前缀划分账号组

自动轮询适合一组可以互换的凭据。如果工作账号、个人账号、不同供应来源或不同网络出口不能混用，可以为凭据设置 prefix：

prefix: "work"

客户端通过带前缀的模型名称请求这一组凭据：

work/gpt-5-codex

开启：

force-model-prefix: true

开启后，未带前缀的模型请求只会使用没有前缀的凭据；官方模板注明，凭据前缀与模型名称完全相同时例外。这样可以同时保留自动路由和显式分组：组内仍然可以按照轮询策略选择账号，组与组之间则由客户端使用的前缀区分。

模型别名解决的是客户端看到什么模型名称，不参与凭据选择。需要稳定客户端模型名时可以另外配置别名，不必把它与账号分组混在一起。

账号失败后如何继续

多账号路由不仅可以分摊请求，也可以在某个凭据暂时不可用时尝试其他候选凭据。相关全局配置包括：

request-retry: 3
max-retry-credentials: 0
max-retry-interval: 30
disable-cooling: false

request-retry 控制首轮候选凭据耗尽后的附加重试轮次；max-retry-credentials 限制每轮最多尝试多少个不同凭据，设为 0 表示尝试全部符合条件的凭据；max-retry-interval 限制等待凭据冷却的最长时间。

对于配置模板列出的 403、408、429、500、502、503 和 504 等失败，CLIProxyAPI 可以继续尝试其他可用凭据，并对故障凭据执行冷却调度。单个凭据也可以覆盖全局重试和冷却设置。

配额耗尽时，还可以控制是否切换项目或预览模型：

quota-exceeded:
  switch-project: true
  switch-preview-model: true

这套机制提高的是单个 CLIProxyAPI 实例内部的上游凭据可用性。它不能处理 CLIProxyAPI 进程退出、服务器断电或网络入口故障，也不等于多实例高可用。

不同账号可以使用不同网络出口

CLIProxyAPI 支持全局 HTTP、HTTPS 或 SOCKS5 代理：

proxy-url: "socks5://user:pass@proxy.example.com:1080"

单个凭据可以设置自己的 proxy-url，也可以使用：

proxy-url: "direct"

显式绕过全局代理和环境代理；当前模板也接受同义值 none。这样可以让不同模型来源或账号使用不同网络出口。网络出口属于凭据配置的一部分，应该和前缀、权重及冷却策略一起设计，与 CLIProxyAPI 直接运行还是运行在容器中没有必然关系。

多账号调度不等于多用户管理

CLIProxyAPI 管理的是上游凭据和模型请求，不是完整的用户与账务系统：

如果需要把订阅账号池分给多个用户，或者统一管理渠道、令牌、额度和费用，可以参照 CLIProxyAPI、Sub2API 和 New API 应该怎么选。

直接运行与 Docker 运行有什么区别

多账号路由由 CLIProxyAPI 自身完成。直接运行和 Docker Compose 运行的是同一个程序，拥有相同的账号池、路由、重试和协议转换能力；区别只在程序如何落到服务器上：

容器可以删除和重建，因此 config.yaml 和认证凭据目录必须挂载到宿主机。挂载决定数据是否保留，不会改变账号如何选择。

两种形式还有一个容易混淆的网络差异。直接运行时，配置中的 127.0.0.1 是宿主机环回地址；在 Docker 中，127.0.0.1 指向容器自身。如果仍然只允许宿主机上的 Caddy 访问 CLIProxyAPI，可以让程序监听容器网络接口，再由 Docker 把宿主机端口限制在环回地址：

# config.yaml
host: ""
port: 8317

# docker-compose.yml
ports:
  - "127.0.0.1:8317:8317"

这条端口映射把容器服务发布到宿主机的环回地址。宿主机上的 Caddy 可以访问它，其他设备不能绕过 Caddy 直接连接 8317 端口。

CLIProxyAPI 对多个账号的管理发生在程序内部：模型和前缀决定候选范围，路由策略和会话绑定决定请求使用哪个凭据，重试与冷却负责处理暂时不可用的账号。直接运行和 Docker Compose 只是承载同一套机制的两种形式，不会改变账号池的行为。

参考资料

• CLIProxyAPI 中文说明
• CLIProxyAPI 完整配置模板
• 官方 Docker 文档
• 官方 Docker Compose 文档
• 官方 Docker Compose 文件