CLIProxyAPI 教程：搭建 AI 网关管理领取的免费 Token 与账号

准备

• 一台电脑（Windows、macOS 或 Linux），或具备 Docker 环境的 VPS 服务器。
• 已在各平台领取的 API Key（如百炼、硅基流动、Groq 等），或支持 OAuth 登录的账号。
• 需要使用 AI 的客户端或终端工具（如 Claude Code、Codex CLI、Cherry Studio、Cursor、OpenCode 等）。

步骤

1. 01

   选择运行方式：桌面客户端或 Docker 容器

   CLIProxyAPI 支持多种部署形态，按自己的使用习惯二选一即可：

   • 桌面快速启动（推荐新手）：下载官方图形客户端 EasyCLIProxyAPI，提供系统托盘、自动更新与可视化配置面板。
   • 服务器 / 开发者模式（Docker Compose）：适合长期在后台或 VPS 运行。创建工作目录并编写运行脚本。

   bash复制

   mkdir -p ~/cliproxyapi && cd ~/cliproxyapi
   mkdir -p auths logs plugins
   touch config.yaml

2. 02

   编写 docker-compose.yml 并拉取镜像

   若选择 Docker 部署，在 ~/cliproxyapi 下创建 docker-compose.yml。

   默认监听 8317 端口提供核心代理网关；其他端口为第三方 OAuth 登录时的回调端口（如 8085、1455 等）。

   yaml复制

   services:
     cli-proxy-api:
       image: eceasy/cli-proxy-api:latest
       container_name: cli-proxy-api
       restart: unless-stopped
       ports:
         - "8317:8317"
         - "8085:8085"
         - "1455:1455"
       volumes:
         - ./config.yaml:/CLIProxyAPI/config.yaml
         - ./auths:/root/.cli-proxy-api
         - ./logs:/CLIProxyAPI/logs
         - ./plugins:/CLIProxyAPI/plugins

3. 03

   初始化 config.yaml：配置客户端访问秘钥

   CLIProxyAPI 采用 v8 格式配置。首先设置监听地址，并在 access.api-keys 下设置供你本地工具调用的网关密钥（防止未授权盗刷）。

   请在 ~/cliproxyapi/config.yaml 中写入基础骨架：

   yaml复制

   config-version: 8
   
   server:
     host: "0.0.0.0"
     port: 8317
   
   # 客户端连接网关时使用的 API Key（自定义，由你保管）
   access:
     api-keys:
       - "sk-my-gateway-secret-token"
   
   # 路由策略：支持 round-robin（轮询）、weighted-round-robin（权重）、fill-first（优先填满）
   routing:
     strategy: "round-robin"
     session-affinity: true
     session-affinity-ttl: "1h"

4. 04

   接入免费 API 额度（百炼、硅基流动、火山方舟等）

   将从各大平台领到的免费 API Key 配置在 api-keys.openai-compatibility 列表中。

   每个提供商可指定名称、Base URL、上游 Key 列表以及允许对外暴露的模型。以下是收录常见免费平台的配置示例：

   yaml复制

   api-keys:
     openai-compatibility:
       # 1. 阿里云百炼（90天免费额度，北京地域）
       - name: "bailian"
         base-url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
         keys:
           - api-key: "sk-bailian-your-key-here"
         models:
           - name: "qwen-plus"
             alias: "qwen-plus"
           - name: "qwen-turbo"
             alias: "qwen-turbo"
   
       # 2. 硅基流动（赠金与免充值模型）
       - name: "siliconflow"
         base-url: "https://api.siliconflow.cn/v1"
         keys:
           - api-key: "sk-siliconflow-your-key-here"
         models:
           - name: "Qwen/Qwen2.5-72B-Instruct"
             alias: "sf-qwen-72b"
           - name: "deepseek-ai/DeepSeek-V3"
             alias: "sf-deepseek-v3"
   
       # 3. 火山方舟（新用户免费模型推理包）
       - name: "volces-ark"
         base-url: "https://ark.cn-beijing.volces.com/api/v3"
         keys:
           - api-key: "volces-your-key-here"
         models:
           - name: "doubao-seed-2-1-pro-260628"
             alias: "doubao-pro"

5. 05

   配置模型别名池（多渠道自动容灾降级）

   CLIProxyAPI 最强大的特性之一是模型别名池（Model Alias Pool）：你可以把不同厂商的同类免费模型映射为相同的别名。

   当上游某个平台额度耗尽、限流（429）或报 500 故障时，网关会自动无缝重试下一个上游，下游的 Agent 和客户端无需做任何更改：

   yaml复制

   # 在 openai-compatibility 中配置相同的 alias 实现自动故障转移：
   models:
     # 首选用百炼的免费 qwen-plus
     - name: "qwen-plus"
       alias: "coding-model"
     # 若百炼限流或报错，网关自动降级切换至硅基流动的模型
     - name: "Qwen/Qwen2.5-72B-Instruct"
       alias: "coding-model"

6. 06

   启动网关服务并验证连通性

   在终端中启动容器：

   ```bash
   docker compose up -d
   ```

   查看日志 docker compose logs -f，确认服务监听在 8317 端口。

   使用 curl 发送一条测试请求，验证网关鉴权与模型路由是否正常：

   bash复制

   curl http://127.0.0.1:8317/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-my-gateway-secret-token" \
     -d '{
       "model": "qwen-plus",
       "messages": [{"role": "user", "content": "你好，测试网关连通性"}]
     }'

7. 07

   给 Claude Code、Codex CLI 与聊天客户端统一配置

   网关启动后，所有日常工具只需连接这个本地/私有端口即可：

   • OpenAI 兼容客户端（Cherry Studio / Cursor / NextChat）：
   • Base URL：http://127.0.0.1:8317/v1
   • API Key：填入你在 access.api-keys 设置的秘钥。
   • 终端工具与 Coding Agent：
   • 配置环境变量将请求转发给网关即可使用：

   bash复制

   # 终端环境变量配置示例
   export OPENAI_BASE_URL="http://127.0.0.1:8317/v1"
   export OPENAI_API_KEY="sk-my-gateway-secret-token"
   
   # Anthropic Messages 协议端点（Claude Code 兼容）
   export ANTHROPIC_BASE_URL="http://127.0.0.1:8317"
   export ANTHROPIC_API_KEY="sk-my-gateway-secret-token"

注意事项

• access.api-keys 是供客户端调用网关的密码；api-keys.openai-compatibility 下面填的才是向各平台申请的上游实际 Key，两者切勿混淆。
• 如果部署在公网 VPS，务必保管好 access.api-keys，不要泄露或设置弱密码。
• 各个上游平台的免费额度、有效期与 RPM 限制仍然独立计算，网关负责调度、故障转移与协议转换。

常见问题

相关优惠

• 额度 · 谷歌Google AI Pro / Ultra 每月赠送 $10–$100 Google Cloud 开发者额度AI Pro 每月 $10；AI Ultra 每月 $40（20TB）或 $100（30TB）
• 模型 · 硅基流动硅基流动 SiliconFlow 免费 API：翻译、OCR、向量与生图模型价格页标注「免费」的模型调用费用为 0（无总量额度，限速以模型广场为准）
• 新人 · 火山引擎火山方舟新人额度：每模型 50 万 Tokens，支持豆包 API每个模型 50 万 Tokens 免费推理额度（以控制台「开通管理」显示为准）
• 新人 · 阿里云阿里云百炼新人额度：每模型通常 100 万 Tokens，90 天有效每个参与模型通常 100 万 Tokens（输入输出共用），90 天有效；仅北京地域
• 模型 · OpenRouterOpenRouter 免费模型 API：每天 50 次，充值后最高 1,000 次每分钟 20 次；累计充值不足 $10 每天 50 次，累计充值满 $10 每天 1,000 次（每天 00:00 UTC 重置）
• 模型 · GroqGroq 免费模型 API：GPT-OSS 等每天 1,000 次，免绑卡GPT-OSS 120B/20B、Qwen 3.8 27B：每分钟 30 次、每天 1,000 次、每分钟 8K Tokens、每天 20 万 Tokens；Whisper 语音转文字每天 2,000 次

信息来源

• CLIProxyAPI 官方 GitHub 仓库github.com/router-for-me/CLIProxyAPI
• CLIProxyAPI 官方中文使用手册help.router-for.me/cn/
• EasyCLIProxyAPI 桌面客户端仓库github.com/router-for-me/EasyCLIProxyAPI
• CPA-Manager-Plus 自托管管理面板github.com/seakee/CPA-Manager-Plus

最后核实日期：2026-10-11 · 政策可能随时调整，请以官方页面为准