CLIProxyAPI：将 AI CLI 工具统一转换为标准 API 服务

CLIProxyAPI 是一个将 Gemini CLI、Claude Code、ChatGPT Codex、Grok Build、Antigravity 等 AI CLI 工具包装成 OpenAI / Gemini / Claude / Codex 兼容 API 服务的代理层，让你通过统一的标准 API 接口免费调用这些模型。

核心概念#

CLIProxyAPI 本质上是一个中间层代理：

1
你的客户端 (Cursor / NextChat / Python SDK / curl)
2
        ↓  标准 API 请求 (OpenAI / Claude / Gemini 格式)
3
   CLIProxyAPI  (8317 端口)
4
        ↓  调用本地/远程 CLI 工具
5
Gemini CLI / Claude Code / Codex / Grok Build
6
        ↓  OAuth 免费额度
7
     云端 AI 模型

支持的 CLI 后端：

CLI 工具	对应模型	免费额度
Gemini CLI	Gemini 2.5 Pro / Flash	每日大量免费请求
Claude Code	Claude Sonnet / Opus	按月计费账户
ChatGPT Codex	GPT-4o / o3	Plus 会员额度
Grok Build	Grok 3 / 4	xAI 免费额度
Antigravity	多模型	自定义

支持的 API 协议：

OpenAI Chat Completions (/v1/chat/completions)
OpenAI Responses API (/v1/responses)
Anthropic Messages (/v1/messages)
Google Gemini (/v1beta/models/:model/generateContent)

核心价值
通过一个本地/服务器服务，用标准 API 接口调用多个免费 AI 额度，Cursor、NextChat、OpenClaw 等工具无缝接入。

安装#

方式一：二进制文件（推荐新手）#

前往 Releases 页面下载对应系统的压缩包，解压后直接运行。

Linux / macOS：

1
# 下载（以 Linux amd64 为例，请替换为最新版本号）
2
wget https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/CLIProxyAPI-linux-amd64.tar.gz
3
tar -xzf CLIProxyAPI-linux-amd64.tar.gz
4
chmod +x cliproxyapi
5

6
# 初始化默认配置
7
./cliproxyapi init
8

9
# 启动服务
10
./cliproxyapi start

macOS（Homebrew）：

1
brew tap router-for-me/tap
2
brew install cliproxyapi
3
cliproxyapi init && cliproxyapi start

Windows（PowerShell）：

1
# 下载 windows-amd64.zip 后解压，在目录内执行
2
.\cliproxyapi.exe init
3
.\cliproxyapi.exe start

方式二：Docker（推荐服务器部署）#

1
# 创建工作目录
2
mkdir -p ~/cliproxyapi/{auths,logs}
3
cd ~/cliproxyapi
4

5
# 下载示例配置
6
curl -O https://raw.githubusercontent.com/router-for-me/CLIProxyAPI/main/config.example.yaml
7
cp config.example.yaml config.yaml
8

9
# 拉取并启动
10
docker run -d \
11
  --name cliproxyapi \
12
  --restart unless-stopped \
13
  -p 8317:8317 \
14
  -v $(pwd)/config.yaml:/app/config.yaml \
15
  -v $(pwd)/auths:/app/auths \
16
  -v $(pwd)/logs:/app/logs \
17
  ghcr.io/router-for-me/cliproxyapi:latest

方式三：Docker Compose（推荐生产环境）#

1
services:
2
  cliproxyapi:
3
    image: ghcr.io/router-for-me/cliproxyapi:latest
4
    container_name: cliproxyapi
5
    restart: unless-stopped
6
    ports:
7
      - "8317:8317"
8
    volumes:
9
      - ./config.yaml:/app/config.yaml
10
      - ./auths:/app/auths
11
      - ./logs:/app/logs
12
    environment:
13
      - TZ=Asia/Shanghai

1
docker compose up -d

配置文件详解#

CLIProxyAPI 通过 config.yaml 管理所有配置，支持热重载，修改后即时生效无需重启。

1
# ── 服务器基础配置 ──────────────────────────────
2
server:
3
  host: ""          # 留空表示监听所有网卡（0.0.0.0）
4
  port: 8317        # 服务端口，默认 8317
5
  # tls:            # 可选：开启 HTTPS
6
  #   cert: /path/to/cert.pem
7
  #   key: /path/to/key.pem
8

9
# ── 远程管理 / WebUI ──────────────────────────────
10
remote-management:
11
  allow-remote: true      # 是否允许远程访问管理接口
12
  secret-key: "your-strong-password"  # WebUI 登录密码，务必修改！
13

14
# ── 认证文件目录 ──────────────────────────────────
15
auth-dir: "./auths"       # 存放 OAuth 认证文件的目录
16

17
# ── 各 CLI 后端配置 ───────────────────────────────
18
providers:
19

20
  # Gemini CLI
21
  gemini:
22
    enabled: true
23
    api-keys:             # 客户端调用时使用的 API Key（自定义，随意填写）
24
      - "sk-gemini-your-key-1"
25
      - "sk-gemini-your-key-2"
26
    load-balance: round-robin   # round-robin | fill-first
27

28
  # Claude Code
29
  claude:
30
    enabled: true
31
    api-keys:
32
      - "sk-claude-your-key-1"
33
    load-balance: round-robin
34

35
  # ChatGPT Codex
36
  codex:
37
    enabled: false
38
    api-keys:
39
      - "sk-codex-your-key-1"
40

41
  # Grok Build
42
  grok:
43
    enabled: false
44
    api-keys:
45
      - "sk-grok-your-key-1"
46

47
# ── 全局 API Key（可同时访问所有后端）────────────
48
global-api-keys:
49
  - "sk-global-master-key"
50

51
# ── 日志配置 ──────────────────────────────────────
52
log:
53
  level: info             # debug | info | warn | error
54
  dir: "./logs"

安全提示
secret-key 是 WebUI 的登录密码，生产环境务必设置强密码。api-keys 是自定义的认证凭据，客户端连接时填写这里配置的值。

负载均衡策略#

策略	说明	适用场景
`round-robin`	轮询均匀分配到所有账号	多号薅配额，最大化吞吐
`fill-first`	优先压满第一个账号，满了才切换	主力号 + 备用号组合

CLI 认证授权#

Gemini CLI 授权#

1
# 本地安装 Gemini CLI（需要 Node.js 18+）
2
npm install -g @google/gemini-cli
3

4
# 触发 OAuth 授权（会打开浏览器）
5
gemini auth login
6

7
# 授权成功后，将认证文件复制到 auths 目录
8
# CLIProxyAPI 会自动读取该目录下的认证信息

NOTE
Gemini 个人 Google 账号每天有大量免费请求额度（Gemini 2.5 Pro 约 1000 次/天），特别适合轻量使用场景。

Claude Code 授权#

1
# 安装 Claude Code（需要 Node.js 18+）
2
npm install -g @anthropic-ai/claude-code
3

4
# 触发 OAuth 授权
5
claude auth login
6

7
# 会在浏览器中完成 Anthropic 账号授权
8
# 授权后认证文件默认在 ~/.claude/ 目录

TIP
Claude Code 使用 Claude Max 订阅的额度，适合需要更高质量代码生成的场景。

ChatGPT Codex 授权#

1
# 安装 Codex CLI
2
npm install -g @openai/codex
3

4
# 登录 OpenAI 账号
5
codex auth login

Grok Build 授权#

1
# 安装 Grok Build
2
npm install -g @xai/grok-build
3

4
# 使用 xAI 账号授权
5
grok auth login

多账号管理#

CLIProxyAPI 支持同一个后端绑定多个账号（认证文件），实现轮询负载均衡：

1
auths/
2
├── gemini-account1.json
3
├── gemini-account2.json
4
├── gemini-account3.json
5
├── claude-account1.json
6
└── codex-account1.json

每个认证文件对应一个账号，CLIProxyAPI 按配置的策略自动分配请求。

WebUI 管理界面#

启动服务后，访问 http://服务器IP:8317/management.html 进入后台管理：

账号状态：实时查看各 CLI 账号的认证状态和剩余配额
配置管理：在线修改 config.yaml，热重载即时生效
日志查看：实时查看请求日志和错误信息
上传认证：直接上传 OAuth 认证文件，无需手动拷贝

1
管理页面地址: http://YOUR_SERVER:8317/management.html
2
密码: config.yaml 中的 secret-key

API 调用示例#

CLIProxyAPI 服务默认在 http://localhost:8317 监听。

cURL 调用#

OpenAI 格式（Chat Completions）：

1
curl http://localhost:8317/v1/chat/completions \
2
  -H "Content-Type: application/json" \
3
  -H "Authorization: Bearer sk-gemini-your-key-1" \
4
  -d '{
5
    "model": "gemini-2.5-pro",
6
    "messages": [
7
      {"role": "user", "content": "你好，介绍一下你自己"}
8
    ]
9
  }'

Anthropic 格式（Messages）：

1
curl http://localhost:8317/v1/messages \
2
  -H "Content-Type: application/json" \
3
  -H "x-api-key: sk-claude-your-key-1" \
4
  -H "anthropic-version: 2023-06-01" \
5
  -d '{
6
    "model": "claude-sonnet-4-5",
7
    "max_tokens": 1024,
8
    "messages": [
9
      {"role": "user", "content": "写一个快速排序算法"}
10
    ]
11
  }'

流式输出（Streaming）：

1
curl http://localhost:8317/v1/chat/completions \
2
  -H "Content-Type: application/json" \
3
  -H "Authorization: Bearer sk-gemini-your-key-1" \
4
  -d '{
5
    "model": "gemini-2.5-pro",
6
    "stream": true,
7
    "messages": [
8
      {"role": "user", "content": "写一篇关于量子计算的科普文章"}
9
    ]
10
  }'

Python SDK 调用#

1
from openai import OpenAI
2

3
# 指向本地 CLIProxyAPI 服务
4
client = OpenAI(
5
    base_url="http://localhost:8317/v1",
6
    api_key="sk-gemini-your-key-1"
7
)
8

9
# 普通调用
10
response = client.chat.completions.create(
11
    model="gemini-2.5-pro",
12
    messages=[
13
        {"role": "user", "content": "解释一下什么是 RAG 技术"}
14
    ]
15
)
16
print(response.choices[0].message.content)
17

18
# 流式调用
19
stream = client.chat.completions.create(
20
    model="gemini-2.5-pro",
21
    messages=[{"role": "user", "content": "写一个 Python 爬虫示例"}],
22
    stream=True
23
)
24
for chunk in stream:
25
    if chunk.choices[0].delta.content:
26
        print(chunk.choices[0].delta.content, end="", flush=True)

1
import anthropic
2

3
# 使用 Anthropic SDK 调用 Claude 后端
4
client = anthropic.Anthropic(
5
    base_url="http://localhost:8317",
6
    api_key="sk-claude-your-key-1"
7
)
8

9
message = client.messages.create(
10
    model="claude-sonnet-4-5",
11
    max_tokens=1024,
12
    messages=[
13
        {"role": "user", "content": "用 Go 语言实现一个并发安全的缓存"}
14
    ]
15
)
16
print(message.content[0].text)

查询可用模型#

1
# 列出所有可用模型
2
curl http://localhost:8317/v1/models \
3
  -H "Authorization: Bearer sk-gemini-your-key-1"

接入主流客户端#

Cursor#

打开 Cursor → Settings → Models
Base URL: http://localhost:8317/v1
API Key: 填入 config.yaml 中配置的任意 api-keys 值
选择模型（如 gemini-2.5-pro）后保存

TIP
如果 Cursor 和 CLIProxyAPI 在同一台机器，使用 http://localhost:8317/v1；如果是远程服务器，替换为服务器 IP。

NextChat / ChatGPT-Next-Web#

打开 NextChat 设置
自定义接口: 勾选
接口地址: http://localhost:8317
API Key: 填入对应的 api-keys
自定义模型名称: gemini-2.5-pro,claude-sonnet-4-5

OpenClaw#

1
设置 → Provider → 自定义
2
Base URL: http://localhost:8317
3
API Type: openai-compatible
4
API Key: sk-global-master-key

注意路径
OpenClaw 接入时 Base URL 不要带 /v1 后缀，因为 OpenClaw 会自动追加路径，否则会出现 /v1/v1/messages 404 错误。

Open WebUI#

1
# 在 Open WebUI 的环境变量中设置
2
OPENAI_API_BASE_URL=http://localhost:8317/v1
3
OPENAI_API_KEY=sk-gemini-your-key-1

Continue（VSCode 插件）#

1
{
2
  "models": [
3
    {
4
      "title": "Gemini 2.5 Pro (Free)",
5
      "provider": "openai",
6
      "model": "gemini-2.5-pro",
7
      "apiBase": "http://localhost:8317/v1",
8
      "apiKey": "sk-gemini-your-key-1"
9
    },
10
    {
11
      "title": "Claude Sonnet",
12
      "provider": "anthropic",
13
      "model": "claude-sonnet-4-5",
14
      "apiBase": "http://localhost:8317",
15
      "apiKey": "sk-claude-your-key-1"
16
    }
17
  ]
18
}

Nginx 反向代理（生产环境）#

在服务器部署时，建议套一层 Nginx + HTTPS：

1
server {
2
    listen 443 ssl;
3
    server_name your-domain.com;
4

5
    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
6
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
7

8
    location / {
9
        proxy_pass         http://127.0.0.1:8317;
10
        proxy_http_version 1.1;
11
        proxy_set_header   Upgrade $http_upgrade;
12
        proxy_set_header   Connection "upgrade";
13
        proxy_set_header   Host $host;
14
        proxy_set_header   X-Real-IP $remote_addr;
15
        proxy_read_timeout 300s;   # 流式响应需要较长超时
16
        proxy_buffering    off;    # 关闭缓冲，确保流式传输即时转发
17
    }
18
}
19

20
server {
21
    listen 80;
22
    server_name your-domain.com;
23
    return 301 https://$host$request_uri;
24
}

1
# 申请证书（Certbot）
2
certbot --nginx -d your-domain.com
3

4
# 重载 Nginx
5
nginx -s reload

常见问题#

认证失效怎么办？#

CLI 工具的 OAuth Token 有有效期，过期后需要重新授权：

1
# 重新授权 Gemini
2
gemini auth login
3

4
# 重新授权 Claude Code
5
claude auth login
6

7
# 将新生成的认证文件复制到 auths 目录
8
# CLIProxyAPI 会热重载自动识别

如何查看请求日志？#

1
# Docker 部署查看日志
2
docker logs -f cliproxyapi
3

4
# 或访问 WebUI 管理页面的日志面板
5
http://YOUR_SERVER:8317/management.html

模型名称不对？#

CLIProxyAPI 支持模型名称映射，可以在 config.yaml 中自定义：

1
model-mapping:
2
  "gpt-4o": "gemini-2.5-pro"       # 把 gpt-4o 请求转发到 Gemini
3
  "claude-3-5-sonnet": "claude-sonnet-4-5"

端口被占用？#

修改 config.yaml 中的 port 字段，或 Docker 部署时修改端口映射：

1
docker run -p 9000:8317 ...  # 映射到宿主机 9000 端口

流式响应中断？#

检查 Nginx 配置中是否设置了 proxy_buffering off 和足够长的 proxy_read_timeout。

安全建议#

生产环境清单

secret-key 设置为强密码（16 位以上随机字符）

api-keys 不要使用简单字符串

服务器防火墙只开放必要端口（建议套 Nginx + HTTPS，不直接暴露 8317）

定期轮换 api-keys

allow-remote: false 如果不需要远程访问管理接口

核心概念#

安装#

方式一：二进制文件（推荐新手）#

方式二：Docker（推荐服务器部署）#

方式三：Docker Compose（推荐生产环境）#

配置文件详解#

负载均衡策略#

CLI 认证授权#

Gemini CLI 授权#

Claude Code 授权#

ChatGPT Codex 授权#

Grok Build 授权#

多账号管理#

WebUI 管理界面#

API 调用示例#

cURL 调用#

Python SDK 调用#

查询可用模型#

接入主流客户端#

Cursor#

NextChat / ChatGPT-Next-Web#

OpenClaw#

Open WebUI#

Continue（VSCode 插件）#

Nginx 反向代理（生产环境）#

常见问题#

认证失效怎么办？#

如何查看请求日志？#

模型名称不对？#

端口被占用？#

流式响应中断？#

安全建议#

相关项目#