用 CLIProxyAPI 搭建个人 AI Token 池

用 CLIProxyAPI 搭建个人 AI Token 池：新手也能跑起来的 CPA 教程

如果你同时用过 Claude Code、Gemini CLI、OpenAI-compatible 客户端，可能会遇到一个问题：每个工具都有自己的认证方式、模型名称和接入地址，切换起来很麻烦。

CLIProxyAPI（简称 CPA） 可以把这些入口统一成一个本地代理服务。你只需要把自己已有的账号认证文件或 API Key 放进 CPA，再让客户端统一访问 CPA 暴露的兼容 API。

CPA 是什么

CLIProxyAPI 是一个本地代理服务。它的核心作用是把不同来源的模型访问方式统一起来，例如：

• Gemini CLI 账号认证
• Claude Code 账号认证
• OpenAI Codex 相关认证
• OpenAI-compatible Provider 的 API Key
• 多个模型服务的统一转发入口

对新手来说，可以把 CPA 理解成一个 “AI 接入网关”：客户端不再直接连接每一个上游服务，而是统一连接 CPA；CPA 再根据你的配置，把请求转发给合适的账号、Key 或 Provider。

个人 Token 池适合解决什么问题

个人 Token 池不是为了绕过平台限制，而是为了把你自己合法拥有的账号或 API Key 管起来。它适合这些场景：

不适合这些场景：

• 批量注册账号后集中调用
• 向别人售卖共享 Token 池
• 绕过平台配额、风控或使用限制
• 把管理后台直接暴露到公网

整体架构

文字版架构可以这样理解：

AI 客户端 / SDK / curl
↓
CLIProxyAPI 本地代理
↓
路由与模型映射
↓
个人 OAuth 认证文件池 / 个人 API Key 池 / OpenAI-compatible Provider
↓
Gemini / Claude / Codex 等上游模型服务

这套架构可以拆成三层：

准备工作

开始前建议准备好这些东西：

推荐目录结构

cpa/
├── docker-compose.yml
├── config.yaml
├── auths/
└── logs/

• config.yaml：负责服务端口、路由、模型别名、Provider 等配置
• auths/：用来放认证文件，路径以你的 CPA 配置为准
• logs/：保存运行日志，排错时很有用

用 Docker Compose 快速启动

新手建议优先使用 Docker Compose，因为它更容易复现，也方便后续迁移。

第一步：获取项目文件

进入 CLIProxyAPI 仓库页面：

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

下载 Release、示例配置，或把仓库克隆到本地：

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

如果没有 Git，可以直接下载 Release 包并解压使用。

第二步：准备配置文件

在 CLIProxyAPI 项目目录中，从示例配置复制一份：

cp config.example.yaml config.yaml

Windows PowerShell 用户：

Copy-Item config.example.yaml config.yaml

然后打开 config.yaml，重点检查：

• 服务监听端口
• API Key 或管理密钥
• 认证文件目录
• Provider 配置
• 模型别名配置
• 路由策略

⚠️ 安全提示：首次启动前，把示例管理密钥替换为随机强密钥；不要把真实 API Key 写入公开仓库、截图或聊天记录。

第三步：启动服务

docker compose up -d

如果你的环境没有 docker compose 命令，可以尝试兼容命令 docker-compose up -d。

启动后，CPA 会在配置文件中指定的端口监听。项目示例里常见端口是 8317，实际端口以你的配置为准。

第四步：查看容器状态

docker compose ps

如果状态是 running，说明服务已经启动。还可以查看日志：

docker compose logs -f

按 Ctrl+C 可以退出日志跟随模式，不会停止正在运行的容器。

新手启动步骤速览

配置个人 Token 池

CPA 的核心配置都在 config.yaml 里。不同版本的字段可能会变化，正式部署时请以仓库里的 config.example.yaml 和官方文档为准。

新手可以先理解四个核心概念：

入口 API Key

客户端访问 CPA 时，不应该"裸奔"。你需要设置一个足够强的入口 Key：

# 示例结构，实际字段以 config.example.yaml 为准
server:
port: 8317

api_keys:
– name: personal–client
key: <YOUR_LOCAL_CPA_ENTRY_KEY>

建议：

• 不要使用 123456、password 这类弱密钥
• 不要把这个 Key 发给别人
• 不要把包含真实 Key 的配置文件上传到公开仓库

认证资源池

个人 Token 池的资源可以来自不同地方：OAuth 认证文件、多个 API Key，或 OpenAI-compatible Provider。

# 示例结构，实际字段以 config.example.yaml 为准
auth:
dir: ./auths

providers:
– name: my–openai–compatible–provider
base_url: https://api.example.com/v1
api_keys:
– <YOUR_PROVIDER_API_KEY_1>
– <YOUR_PROVIDER_API_KEY_2>

如果使用 OAuth 认证文件，建议把文件放在专门目录，并做好权限控制。这个目录里可能包含非常敏感的凭证，不要随便同步到网盘或公开仓库。

路由策略

常见策略可以这样理解：

⚠️ 无论使用哪种策略，都应遵守上游平台的账号、套餐、速率限制和服务条款，不应把路由策略用于绕过配额或风控。

示意配置：

# 示例结构，实际字段以 config.example.yaml 为准
routing:
strategy: round–robin
retry: 2

模型别名

模型别名可以降低客户端配置成本。比如客户端只填 gpt-4o-mini，CPA 内部再映射到你真正要调用的上游模型：

# 示例结构，实际字段以 config.example.yaml 为准
model_aliases:
gpt-4o-mini: gemini–2.5–flash
claude-sonnet: claude–sonnet–4–6

💡 不要盲目复制别人的模型名。不同上游、不同版本支持的模型并不完全一样，最好先用最小请求验证。

Token 池请求路由过程

客户端使用本地入口 Key 发起请求
→ CPA 校验入口 Key 与模型名
→ 路由策略根据模型和配置选择资源
→ 从个人 OAuth 认证文件或 API Key 中选择可用资源
→ 转发到真实上游模型服务
→ 上游返回模型响应
→ CPA 统一响应格式并返回给客户端

把客户端接入 CPA

只要客户端支持 OpenAI-compatible API，通常就可以这样填写：

如果客户端支持 Claude、Gemini 或其他协议，也可以根据 CLIProxyAPI 文档选择对应端点。新手建议先从 OpenAI-compatible 接口开始，因为客户端支持面更广。

SDK 示例（伪代码）

很多 SDK 允许自定义 baseURL 和 apiKey：

const client = createOpenAICompatibleClient({
baseURL: 'http://localhost:8317/v1',
apiKey: '<YOUR_LOCAL_CPA_ENTRY_KEY>',
});

const response = await client.chat.completions.create({
model: 'gpt-4o-mini',
messages: [{ role: 'user', content: '你好，简单介绍一下 CPA。' }],
});

⚠️ 这段代码只是说明接入方式。实际项目不要把真实入口 Key 写入前端代码或公开仓库，服务端项目优先从环境变量读取。

验证是否跑通

最直接的方式是发一个最小请求：

curl http://localhost:8317/v1/chat/completions \\
-H "Authorization: Bearer <YOUR_LOCAL_CPA_ENTRY_KEY>" \\
-H "Content-Type: application/json" \\
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "你好，用一句话介绍 CLIProxyAPI。"}
]
}'

Windows PowerShell 用户（建议使用 curl.exe 避免别名冲突）：

curl.exe http://localhost:8317/v1/chat/completions `
–H "Authorization: Bearer <YOUR_LOCAL_CPA_ENTRY_KEY>" `
–H "Content-Type: application/json" `
–d '{ "model": "gpt-4o-mini", "messages": [{ "role": "user", "content": "你好，用一句话介绍 CLIProxyAPI。" }] }'

如果返回了模型响应，说明链路已经打通：

curl / 客户端 → CPA 本地端口 → 入口 Key 校验 → 模型别名/路由 → 个人认证资源 → 上游模型响应

常见问题排查

1. 连接不上 CPA

先检查容器是否运行：

docker compose ps

再检查端口是否一致：CPA 监听的是 8317，客户端就不能填成 http://localhost:8000/v1。同时检查 docker-compose.yml 的 ports 是否已经把容器端口映射到宿主机。

2. 返回 401 或认证失败

通常是入口 API Key 不一致。检查：

• config.yaml 里的入口 Key
• 客户端填写的 API Key
• Authorization: Bearer … 是否拼写正确

3. 模型不存在

可能是模型名或别名没有配置好。检查：

• 客户端填写的 model
• CPA 的模型别名配置
• 上游服务实际支持的模型列表

4. 某个账号或 Key 不可用

查看 CPA 日志：

docker compose logs -f

常见原因：

• OAuth 认证文件过期
• API Key 填错
• 上游服务暂时不可用
• 当前账号或 Key 达到平台限制

⚠️ 如果是达到平台限制，应停止继续重试，按平台规则等待额度恢复、降低请求频率或升级正规套餐，不要通过更换账号或 Key 规避限制。

5. 请求很慢

可以检查：

• 当前上游服务是否响应慢
• 是否配置了过多重试
• 网络是否稳定
• 客户端是否启用了流式响应

安全与合规建议

个人 Token 池的方便之处，也正是它的风险点：所有账号和 Key 都集中到了一处。因此建议至少做好下面几件事。

只放本人合法授权的资源

管理端不要公网裸露

如果 CPA 提供管理 API 或控制面板，不要直接暴露到公网。更安全的做法：

• 只监听本机或内网地址
• 使用强管理密钥
• 需要远程访问时走 VPN、SSH 隧道或可信反向代理

保护配置文件和认证目录

config.yaml、认证文件目录和日志都可能包含敏感信息。建议：

• 不上传到公开仓库
• 不截图泄露真实 Key
• 不同步到不可信网盘
• 定期检查日志是否包含敏感请求内容
• 迁移机器时确认旧机器上的凭证已经清理

给客户端单独设置入口 Key

不要让客户端直接拿上游 API Key。更推荐的方式：

• 上游 Key 只放在 CPA 配置里
• 客户端只拿 CPA 的入口 Key
• 如果某个客户端不用了，只轮换 CPA 入口 Key，而不是到处改上游 Key

总结

CLIProxyAPI 适合做个人 AI 接入网关：把你本人合法授权的账号、OAuth 认证文件和 API Key 统一放在本地，通过一个兼容 API 提供给不同客户端使用。