---
title: "CLIProxyAPI 的多账号路由如何工作"
published_at: "2026-08-27"
language: "zh"
---
# CLIProxyAPI 的多账号路由如何工作
CLIProxyAPI 可以同时保存多个 OAuth 账号和上游 API Key。客户端仍然只连接一个地址，使用一枚客户端密钥并提交一个模型名称；CLIProxyAPI 会从能够处理这次请求的凭据中选择一个访问上游模型。
这里的多账号管理，指的是上游凭据的筛选、轮询、会话绑定、重试和冷却，不是为多个下游用户开户、设置余额或生成持久化账单。
如果还没有完成安装、模型接入和本机请求验证，先参照 [CLIProxyAPI 简明部署指南](https://kn.dingzhihao.org/view/writings/cliproxyapi-linux-codex-gpt-guide?lang=default&mode=rendered)。单个账号能够完成真实请求后，再增加其他账号，更容易判断问题出在凭据、路由还是客户端配置。
## 一个客户端入口，多个上游凭据
多个账号接入后，请求链路仍然只有一个客户端入口：
```text
AI 客户端
→ CLIProxyAPI
→ 筛选能够处理目标模型的凭据
→ 选择或复用一个可用凭据
→ 上游模型服务
```
OAuth 账号和上游 API Key 都属于上游凭据。客户端使用的则是 `config.yaml` 顶层 `api-keys` 中的客户端密钥，两者不能混用。
CLIProxyAPI 不会在所有账号中盲目轮询。它会先根据模型、模型来源和前缀确定候选凭据，再从中选择一个，或者复用会话已经绑定的凭据。客户端通常不需要知道最终使用了哪个实际账号；只有通过前缀划分账号组时，客户端才会主动缩小候选范围。
## 一次请求如何选择账号
一次请求从进入 CLIProxyAPI 到访问上游，主要经过以下阶段：
| 阶段 | CLIProxyAPI 的行为 | 相关配置 |
| --- | --- | --- |
| 筛选候选凭据 | 找出能够处理目标模型并符合前缀要求的凭据 | 模型来源、模型和 `prefix` |
| 选择或复用凭据 | 按路由策略选择凭据，或者继续使用会话已经绑定的凭据 | `routing.strategy`、凭据权重、`session-affinity` |
| 处理失败 | 尝试其他候选凭据，并冷却暂时不可用的凭据 | `request-retry`、`max-retry-credentials`、冷却设置 |
| 返回结果 | 将成功响应或最终失败返回客户端 | 客户端使用的协议接口 |
### 轮询、加权和优先使用
全局路由策略由 `routing.strategy` 设置：
```yaml
routing:
strategy: "round-robin"
```
当前配置模板提供三种策略：
| 策略 | 选择方式 | 表达的分配意图 |
| --- | --- | --- |
| `round-robin` | 在可用凭据之间依次轮询 | 条件接近的账号均匀承担请求 |
| `weighted-round-robin` | 按凭据权重分配请求 | 不同账号具有稳定的容量或优先级差异 |
| `fill-first` | 优先使用排在前面的凭据 | 先使用主账号，再使用后续账号 |
使用加权轮询时，API Key 凭据在对应配置项中设置整数 `weight`；OAuth 和其他文件凭据则在认证 JSON 顶层设置数值 `weight`。省略时权重为 `1`，最大值为 `1,000,000`；非正数会在加权轮询启用时排除该凭据。
权重较高的凭据会承担更大比例的请求，但权重表达的是预期分配比例，不会实时测量账号的剩余额度，也不能代替限流和可用性判断。
### 让同一会话继续使用同一凭据
普通轮询可能让同一段会话的连续请求落到不同凭据。需要保持会话与凭据的对应关系时，可以开启会话亲和：
```yaml
routing:
strategy: "round-robin"
session-affinity: true
session-affinity-ttl: "1h"
```
CLIProxyAPI 会优先使用 Claude Code、Codex、OpenCode 和 pi 等客户端发送的会话标识，也会识别 `prompt_cache_key`、Responses 对话 ID 等信息。绑定建立后，同一会话会继续使用原凭据；原凭据不可用时仍会自动切换，并为后续请求建立新的绑定。
会话亲和与路由策略不是两种互斥模式。路由策略负责首次绑定、没有会话标识的请求以及故障切换后的重新绑定；已有且可用的会话绑定优先于凭据顺序。
## 用前缀划分账号组
自动轮询适合一组可以互换的凭据。如果工作账号、个人账号、不同供应来源或不同网络出口不能混用，可以为凭据设置 `prefix`：
```yaml
prefix: "work"
```
客户端通过带前缀的模型名称请求这一组凭据：
```text
work/gpt-5-codex
```
开启：
```yaml
force-model-prefix: true
```
开启后，未带前缀的模型请求只会使用没有前缀的凭据；官方模板注明，凭据前缀与模型名称完全相同时例外。这样可以同时保留自动路由和显式分组：组内仍然可以按照轮询策略选择账号，组与组之间则由客户端使用的前缀区分。
模型别名解决的是客户端看到什么模型名称，不参与凭据选择。需要稳定客户端模型名时可以另外配置别名，不必把它与账号分组混在一起。
## 账号失败后如何继续
多账号路由不仅可以分摊请求，也可以在某个凭据暂时不可用时尝试其他候选凭据。相关全局配置包括：
```yaml
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 可以继续尝试其他可用凭据，并对故障凭据执行冷却调度。单个凭据也可以覆盖全局重试和冷却设置。
配额耗尽时，还可以控制是否切换项目或预览模型：
```yaml
quota-exceeded:
switch-project: true
switch-preview-model: true
```
这套机制提高的是单个 CLIProxyAPI 实例内部的上游凭据可用性。它不能处理 CLIProxyAPI 进程退出、服务器断电或网络入口故障，也不等于多实例高可用。
## 不同账号可以使用不同网络出口
CLIProxyAPI 支持全局 HTTP、HTTPS 或 SOCKS5 代理：
```yaml
proxy-url: "socks5://user:pass@proxy.example.com:1080"
```
单个凭据可以设置自己的 `proxy-url`，也可以使用：
```yaml
proxy-url: "direct"
```
显式绕过全局代理和环境代理；当前模板也接受同义值 `none`。这样可以让不同模型来源或账号使用不同网络出口。网络出口属于凭据配置的一部分，应该和前缀、权重及冷却策略一起设计，与 CLIProxyAPI 直接运行还是运行在容器中没有必然关系。
## 多账号调度不等于多用户管理
CLIProxyAPI 管理的是上游凭据和模型请求，不是完整的用户与账务系统：
| CLIProxyAPI 可以处理 | 不属于多账号路由 |
| --- | --- |
| 保存多个 OAuth 账号和上游 API Key | 为大量下游用户开户 |
| 轮询、加权、会话亲和与优先选择凭据 | 用户余额、充值和支付 |
| 失败重试和凭据冷却 | 持久化计费账单 |
| 用前缀划分凭据组 | 完整的租户和权限系统 |
| 为不同凭据设置网络出口 | CLIProxyAPI 服务本身的多节点高可用 |
如果需要把订阅账号池分给多个用户，或者统一管理渠道、令牌、额度和费用，可以参照 [CLIProxyAPI、Sub2API 和 New API 应该怎么选](https://kn.dingzhihao.org/view/writings/cliproxyapi-sub2api-newapi-selection?lang=default&mode=rendered)。
## 直接运行与 Docker 运行有什么区别
多账号路由由 CLIProxyAPI 自身完成。直接运行和 Docker Compose 运行的是同一个程序，拥有相同的账号池、路由、重试和协议转换能力；区别只在程序如何落到服务器上：
| 项目 | 直接运行 | Docker Compose |
| --- | --- | --- |
| 进程管理 | systemd | Docker Compose |
| 配置和凭据 | 直接保存在主机目录 | 通过挂载保存在主机目录 |
| 日志 | journald 或程序日志 | Docker 日志或挂载目录 |
| 升级 | 更新程序文件或重新运行安装器 | 拉取新镜像并重建容器 |
| 网络 | 程序直接监听主机地址 | 经过容器网络和端口映射 |
| 多账号能力 | 由 CLIProxyAPI 提供 | 与直接运行相同 |
容器可以删除和重建，因此 `config.yaml` 和认证凭据目录必须挂载到宿主机。挂载决定数据是否保留，不会改变账号如何选择。
两种形式还有一个容易混淆的网络差异。直接运行时，配置中的 `127.0.0.1` 是宿主机环回地址；在 Docker 中，`127.0.0.1` 指向容器自身。如果仍然只允许宿主机上的 Caddy 访问 CLIProxyAPI，可以让程序监听容器网络接口，再由 Docker 把宿主机端口限制在环回地址：
```yaml
# config.yaml
host: ""
port: 8317
```
```yaml
# docker-compose.yml
ports:
- "127.0.0.1:8317:8317"
```
这条端口映射把容器服务发布到宿主机的环回地址。宿主机上的 Caddy 可以访问它，其他设备不能绕过 Caddy 直接连接 8317 端口。
CLIProxyAPI 对多个账号的管理发生在程序内部：模型和前缀决定候选范围，路由策略和会话绑定决定请求使用哪个凭据，重试与冷却负责处理暂时不可用的账号。直接运行和 Docker Compose 只是承载同一套机制的两种形式，不会改变账号池的行为。
## 参考资料
- [CLIProxyAPI 中文说明](https://github.com/router-for-me/CLIProxyAPI/blob/main/README_CN.md)
- [CLIProxyAPI 完整配置模板](https://github.com/router-for-me/CLIProxyAPI/blob/main/config.example.yaml)
- [官方 Docker 文档](https://github.com/router-for-me/CLIProxyAPIDocs/blob/main/docs/cn/docker/docker.md)
- [官方 Docker Compose 文档](https://github.com/router-for-me/CLIProxyAPIDocs/blob/main/docs/cn/docker/docker-compose.md)
- [官方 Docker Compose 文件](https://github.com/router-for-me/CLIProxyAPI/blob/main/docker-compose.yml)