CLIProxyAPI 部署教程：一个代理地址搞定所有 AI 编程工具

手头有几个 AI 订阅，但每个工具只能用自己的模型，想混着用得来回切账号。CLIProxyAPI 干的就是这件事——一个代理地址，把 Claude Code、Gemini CLI、Codex、Cursor 全串起来，多账户自动轮询，格式转换全自动。

程序本体 10MB 左右，内存占用也不到 10MB。改完配置不用重启，热重载。开源，MIT 协议。

GitHub 仓库：https://github.com/router-for-me/CLIProxyAPI

先跑通再说：Qwen 免费方案

不花钱也能试。Qwen（通义千问）免费注册就行，不需要任何付费订阅，拿它跑通整个流程最快。

下载

GitHub Releases 页面有各平台二进制文件：

• macOS Apple Silicon → darwin_arm64
• macOS Intel → darwin_amd64
• Linux → linux_amd64
• Windows → windows_amd64.zip

macOS 用户也能 brew install cliproxyapi，Arch Linux yay -S cli-proxy-api-bin。

下载后解压到一个干净目录，比如 ~/CLIProxyAPI/。Windows 解压到 D:\CLIProxyAPI\。

写配置

把 config.example.yaml 复制一份改名 config.yaml，内容清空换成这几行：

port: 8317
auth-dir: "~/.cli-proxy-api"
request-retry: 3
quota-exceeded:
  switch-project: true
  switch-preview-model: true
api-keys:
  - "ABC-123456"

api-keys 是你给代理设的密码，客户端连上来时要带这个——跟 OpenAI 官方给的 API Key 没半毛钱关系，自己随便写就行。auth-dir 是 OAuth 认证文件的存放位置。Windows 建议改绝对路径：auth-dir: "D:\\CLIProxyAPI\\auths"。

登录 Qwen

cd ~/CLIProxyAPI
./CLIProxyAPI -qwen-login

Windows 下在 PowerShell 里 .\CLIProxyAPI.exe -qwen-login，CMD 里 CLIProxyAPI.exe -qwen-login。

浏览器弹出通义千问登录页，授权完成后终端让你给账户起个名字，随便填。想加多个账户就重复执行这条命令，CLIProxyAPI 会自动轮询所有账户。

启动、验证

./CLIProxyAPI

终端打出 API server started successfully on: :8317 就说明启动成功。另开一个终端验证：

curl http://127.0.0.1:8317/v1/models -H "Authorization: Bearer ABC-123456"

Windows PowerShell 要写 curl.exe，直接写 curl 会调到 Invoke-WebRequest，参数完全不一样。

返回的 JSON 里有 qwen3-coder-plus、qwen3-coder-flash 之类的模型名就对了。

接入 Claude Code 试试

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=ABC-123456
export ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder-plus
claude

Windows PowerShell：

$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8317"
$env:ANTHROPIC_AUTH_TOKEN = "ABC-123456"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "qwen3-coder-plus"
claude

到这里就已经在免费用了。Cursor、Cline、Roo Code 这些工具也一样，只要支持自定义 OpenAI Base URL 的都能接。

把所有订阅塞进一个代理

Qwen 免费号能跑通，但真正用起来得把付费订阅也接进来。一条命令登录一个提供商，所有模型自动出现在同一个列表里。

提供商总览

提供商	登录命令	前置条件
Qwen	-qwen-login	免费注册通义千问
Gemini	-login -project_id "项目ID"	需要 GCP 项目
Claude	-claude-login	Claude 付费订阅
Codex	-codex-login	ChatGPT Plus/Pro/Team
iFlow（智谱 GLM）	-iflow-login	注册即可
Kimi（月之暗面）	-kimi-login	注册即可
Antigravity	-antigravity-login	注册即可
Vertex AI	-vertex-import key.json	GCP 服务账号

除了 Gemini 要多走一步建 GCP 项目，其他的都是一条命令搞定。所有登录命令支持 -no-browser（不自动开浏览器，终端输出 URL 手动复制）和 -oauth-callback-port 9999（改回调端口）。

Gemini 那一步：打开 Google Cloud Console，建个项目（名字随便），搜 cloudaicompanion.googleapis.com 启用它，记下项目 ID，然后执行：

./CLIProxyAPI -login -project_id "你的项目ID"

project_id 不是必须的，但指定了配额管理会好一些。多个 Google 账号就重复执行，每个号建自己的项目。

混搭模型

全登录完，所有模型混在一个池子里。你可以在 Claude Code 里按任务分配：

# 重活丢给 Claude，日常用 Gemini，轻量任务走 Codex
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6
export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5-codex-mini

请求哪个模型，CLIProxyAPI 自动路由到对应提供商。格式转换、认证方式全不用管。

路由策略

多账户场景下，config.yaml 里这两组参数配合着用：

routing:
  strategy: "round-robin"   # 每次请求换一个账户，均匀分配
  # strategy: "fill-first"  # 优先压一个号，主力号用完再切

request-retry: 3             # 失败重试次数
max-retry-credentials: 2     # 最多试几个不同账户
max-retry-interval: 30       # 冷却等待上限（秒）
quota-exceeded:
  switch-project: true       # 配额满了自动换账户
  switch-preview-model: true # 全满了切预览版模型

round-robin 适合多号均摊配额，fill-first 适合主力号 + 备用号的组合。

Docker 部署，多设备共享

本地跑通之后，下一步是扔到服务器上，家里 NAS、笔记本、公司电脑共用一个代理。

写 docker-compose.yml

建个目录，放好 config.yaml：

mkdir -p ~/cliproxyapi && cd ~/cliproxyapi
mkdir -p auths logs

docker-compose.yml：

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    pull_policy: always
    container_name: cli-proxy-api
    ports:
      - "8317:8317"      # 主 API 端口
      - "8085:8085"      # Gemini OAuth 回调
      - "1455:1455"      # Codex OAuth 回调
      - "54545:54545"    # Claude OAuth 回调
      - "51121:51121"    # Antigravity OAuth 回调
      - "11451:11451"    # iFlow OAuth 回调
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs
    restart: unless-stopped

docker compose up -d

容器里怎么 OAuth？SSH 隧道

容器里没有浏览器，OAuth 回调地址又限制了 localhost。解决办法是在你本地电脑和服务器之间拉一条 SSH 隧道，把回调从本地转到服务器上。

以 Gemini 为例：

# 服务器上执行（-no-browser 让它打印 URL 而不是开浏览器）
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser -login

# 本地电脑另开一个终端，建隧道
ssh -L 8085:localhost:8085 user@你的服务器IP

# 然后在本地浏览器打开服务器输出的那个链接，完成授权

各提供商回调端口不一样，记一下：

提供商	登录命令	隧道端口
Gemini	-login	8085
Codex	-codex-login	1455
Claude	-claude-login	54545
Antigravity	-antigravity-login	51121
iFlow	-iflow-login	11451
Qwen	-qwen-login	不需要
Kimi	-kimi-login	不需要

Qwen 和 Kimi 走的是设备代码流，不依赖本地回调端口——直接在容器里跑登录命令，然后随便拿个设备打开输出的链接就行。

登录搞完，客户端把 Base URL 指向 http://你的服务器IP:8317，其他配置跟本地一模一样。

管理面板

config.yaml 里加上这段：

remote-management:
  secret-key: "你的管理密码"
  allow-remote: true
  disable-control-panel: false

浏览器打开 http://你的服务器IP:8317/management.html，输密码进去，能看使用统计、管理认证文件、查日志。面板里的 OAuth 登录按钮只能在本机用，远程还是得走 SSH 隧道。

客户端配置

下面统一用 指代你 config.yaml 里 api-keys 的值。

Claude Code

编辑 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_API_KEY": "<your-api-key>",
    "ANTHROPIC_BASE_URL": "http://<server-ip>:8317"
  }
}

如果之前用过订阅登录（/login 或 OAuth），Claude Code 会优先用缓存的 OAuth token，不理你配的 API key。表现为界面上出现 sk-ant-... 开头的 key。

清除旧凭证：

# macOS
security delete-generic-password -s "Claude Code-credentials"

# Linux
rm ~/.claude/.credentials.json

Windows 要清两个地方：控制面板 → 凭据管理器 → 删除 Claude Code 条目，同时删掉 %USERPROFILE%\.claude\.credentials.json。

最省事的方式是在 Claude Code 里执行 /logout，然后重启。

Codex CLI

~/.codex/config.toml：

model_provider = "cliproxyapi"

[model_providers.cliproxyapi]
name = "CLIProxyAPI"
base_url = "http://<server-ip>:8317/v1"
wire_api = "responses"

~/.codex/auth.json：

{
  "OPENAI_API_KEY": "<your-api-key>"
}

注意 base_url 末尾带 /v1，wire_api = "responses" 不能少。Codex 走的是 OpenAI Responses API 格式。

Gemini CLI

没有配置文件，全靠环境变量：

export GEMINI_API_KEY="<your-api-key>"
export GOOGLE_GEMINI_BASE_URL="http://<server-ip>:8317"

写到 ~/.bashrc 或 ~/.zshrc 里。Windows 用 PowerShell 设用户级环境变量。

Cursor

打开 Cursor → Settings → Models：

1. OpenAI API Key 填你的 key
2. 开启 Override OpenAI Base URL，填 http://:8317/v1
3. 手动添加模型名（claude-opus-4-6、gpt-5.3-codex 之类的），加完打开开关

Anthropic API Key、Google API Key 那些框不用填，全走 OpenAI Override。CLIProxyAPI 内部自动做格式转换。

代理环境别忘了 NO_PROXY

如果你的网络需要走代理才能访问外网，记得把 CLIProxyAPI 服务器地址加到直连列表里。这不只是"省一次转发"的事——

有些大请求（比如 Claude Code 压缩上百万 token 的上下文）在 API 端的 prefill 阶段要跑超过 60 秒才开始返回数据。如果中间经过代理链路，链路可能因为空闲超时主动断开连接，导致请求反复失败，每次重试又等 60 秒，一个请求折腾几十分钟。

配置方法：

# macOS / Linux
export NO_PROXY="localhost,127.0.0.1,<server-ip>"

Windows：

[System.Environment]::SetEnvironmentVariable('NO_PROXY', 'localhost,127.0.0.1,<server-ip>', 'User')

光设环境变量可能不够——有些代理客户端走系统代理或 TUN 模式接管流量，不听环境变量的。在代理客户端的路由规则里也把服务器 IP 加进直连列表。

API Key 接入

不想走 OAuth 借订阅，直接拿 API Key 接也行。

Claude API

claude-api-key:
  - api-key: "sk-ant-..."
  # 中转商要加 base-url
  # - api-key: "sk-xxx..."
  #   base-url: "https://中转商地址/api"

Gemini API（AIStudio）

gemini-api-key:
  - api-key: "AIzaSy..."
  models:
    - name: "gemini-2.5-flash"
      alias: "flash"

OpenAI 兼容服务（OpenRouter 之类）

openai-compatibility:
  - name: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: "sk-or-v1-..."
    models:
      - name: "moonshotai/kimi-k2:free"
        alias: "kimi-k2"

常见问题

改了配置要重启吗？

不用，热重载。唯一例外是 remote-management 相关字段改了要重启。

怎么看有哪些模型？

curl http://127.0.0.1:8317/v1/models -H "Authorization: Bearer 你的key"

Token 过期了怎么办？

CLIProxyAPI 会自动刷新。刷新失败就重新跑一次对应的 -login 命令。

api-keys 和提供商的 api-key 是一回事吗？

不是。前者是你给代理设的访问密码，后者是 AI 服务商给你的密钥。两个完全独立。

Claude Code 连不上怎么排查？

先 curl 试试能不能拿到模型列表，再检查 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 有没有配对，都对的话开 debug: true 看日志。

Codex 登录失败？

需要 ChatGPT 付费会员（Plus、Pro 或 Team），免费账号不行。

Docker 容器里怎么 OAuth？

SSH 隧道，上面"远程访问"那节有写。

相关链接

项目仓库：https://github.com/router-for-me/CLIProxyAPI

官方文档：https://help.router-for.me/

QQ 群：1081218164

Telegram 群：https://t.me/CLIProxyAPI