使用 CLIProxyAPI：搭建你自己的 AI 对话 API + Codex / Claude Code「号池」与负载均衡

当你同时在用多个模型/多个提供商（Gemini / Claude / Qwen…），或者同一提供商有多组账号/Token 时，常见痛点是：

- 频繁切换 API Key / Provider，开发和运维成本高

- 某个提供商限流（429）或不稳定（5xx）时，需要手动改配置/改代码

- 想做“号池”（多账号轮换）、配额控制、熔断切换，但缺少统一入口

- 想把“聊天模型”和“代码模型（Codex / Claude Code 等）”统一成同一种 API 调用方式

CLIProxyAPI 的核心价值：

> 把多个 CLI/来源（Gemini CLI、Claude Code、Qwen Code、等）封装成兼容 OpenAI/Gemini/Claude/Codex 风格的 API 服务，并提供可视化管理、认证、统计、配额与调度能力。

项目地址：

https://github.com/router-for-me/CLIProxyAPI

快速开始文档：

https://help.router-for.me/introduction/quick-start.html

> 合规提示：不同模型/CLI/平台的授权与使用条款不同。请确保你的账号登录、调用方式、转发方式符合对应平台的政策与法律要求。

---

1. 它是什么？

CLIProxyAPI 相当于你自建的“AI API 网关 / 聚合器”：

- 前端（你的应用）：只对接一次（例如 OpenAI /v1）

- 后端（CLIProxyAPI）：负责把请求分发到不同 provider / 不同账号，并做失败重试、轮换、统计与配额

---

2. 适用场景

2.1 统一入口：一个 /v1 接所有

配置好后http://你的域名:8317/v1 就是标准 API Base URL。

你可以用 OpenAI SDK/兼容客户端直接接入（如 NextChat / Open WebUI / Cherry Studio / 自建后端等）。

2.2 负载均衡 + 号池轮换

把多组账号放进来做“池子”，常见策略：

- 轮询：每次请求换一个账号（均衡消耗）

- 加权：高配额/更稳定账号权重更高

- 失败切换：某账号 429/5xx 时自动换下一个

- 按模型分流：聊天走 A，代码走 B，长上下文走 C

2.3 可视化可观测

你能快速定位：

- 哪个 provider/模型最常报错

- 哪个时段限流最严重

- 哪个账号消耗异常（便于风控和管理）

---

3. Docker 部署

docker run --rm \
​
  -p 8317:8317 \
​
  -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml \
​
  -v /path/to/your/auth-dir:/root/.cli-proxy-api \
​
  eceasy/cli-proxy-api:latest

3.1 两个 -v 分别干什么

- config.yaml：宿主机配置文件 → 容器内 /CLIProxyAPI/config.yaml

- auth-dir：宿主机认证目录 → 容器内 /root/.cli-proxy-api（用于保存 OAuth 登录后的凭据等）

3.2 docker compose

services:
​
  cliproxyapi:
​
    image: eceasy/cli-proxy-api:latest
​
    container_name: cliproxyapi
​
    ports:
​
     \- "8317:8317"
​
    volumes:
​
      \- ./config.yaml:/CLIProxyAPI/config.yaml
​
      \- ./auth-dir:/root/.cli-proxy-api
​
    restart: unless-stopped

启动：

docker compose up -d

4. 管理面板入口与功能说明

面板地址：

- http://IP或域名:8317/management.html

4.1 仪表盘（Dashboard）

用于总览服务状态、调用量、错误等。

4.2 配置面板（Config）

对应你启动用的 config.yaml，提供可视化参数管理。

4.3 AI 提供商（Providers）

集中管理 provider/模型来源。

4.4 认证文件（Auth）+ OAuth 登录

OAuth 登录按页面指引操作，会生成认证文件并回填。

4.5 使用统计（Usage/Stats）

非常实用：能直观看到哪个模型/提供商在报错，便于调度策略优化与故障排查。

5. 应用如何对接（标准 /v1）

配置完成后，你的标准 API Base URL 是：

- http://IP或域名:8317/v1

5.1 curl 调用示例（Chat Completions）

> 路径与参数会随你的配置略有差异，这里演示“OpenAI 兼容”调用方式。

curl http://你的域名:8317/v1/chat/completions \
​
  -H "Content-Type: application/json" \
​
  -H "Authorization: Bearer 你的代理APIKey" \
​
  -d '{
​
    "model": "your-model-name",
​
    "messages": [
​
      {"role":"system","content":"你是严谨的助手。"},
​
      {"role":"user","content":"用三点解释 CLIProxyAPI 的作用。"}
​
    ]
​
  }'

5.2 OpenAI SDK（把 baseURL 指向你的 CLIProxyAPI）

Node.js 示例：

import OpenAI from "openai";
​
const client = new OpenAI({
​
  apiKey: process.env.PROXY_KEY,
​
  baseURL: "http://你的域名:8317/v1",
​
});
​
const r = await client.chat.completions.create({
​
  model: "your-model-name",
​
  messages: [{ role: "user", content: "写一个 Python 快排并解释复杂度" }],
​
});
​
console.log(r.choices[0].message.content);

6.号池/调度策略及安全

其余的号池调度什么的 自用的话可以写粗点 或者用默认的轮询 安全方面的话最好不要暴露太多信息