CLIProxyAPI 安装与使用教程：把 CLI/OAuth 账号封装成统一 API

2026年5月26日 网络工具

CLIProxyAPI 是一个把 Gemini CLI、Claude Code、OpenAI Codex、Grok Build 等 CLI/OAuth 能力封装成 OpenAI、Gemini、Claude、Codex 兼容 API 的代理服务。简单说，它可以把本地或多账号 CLI 登录能力，变成常见客户端和 SDK 可以调用的统一 API。

一、它能做什么？

  • 提供 OpenAI / Gemini / Claude / Codex / Grok 兼容接口。
  • 支持 Gemini、OpenAI Codex、Claude Code、Grok Build 等 OAuth 登录。
  • 支持多账号轮询、负载均衡、流式响应、工具调用和多模态输入。
  • 可以给 Cursor、Claude Code、Open WebUI、OpenAI SDK、各种兼容客户端提供统一 Base URL。

二、部署方式选择

CLIProxyAPI 常见部署方式有三种：直接运行二进制、Docker 部署、源码编译。个人 VPS 推荐 Docker 或二进制；开发者定制可以源码编译。

三、Docker 快速部署

官方文档和社区常用镜像会随版本变化，部署前建议以项目 GitHub / 官方文档为准。下面给出一个通用 Docker 部署模板，实际镜像名按你使用的版本替换。

mkdir -p ~/cliproxyapi && cd ~/cliproxyapi
nano docker-compose.yml
services:
  cliproxyapi:
    image: eceasy/cli-proxy-api:latest
    container_name: cliproxyapi
    restart: always
    ports:
      - "8317:8317"
    volumes:
      - ./data:/app/data
      - ./config:/app/config
    environment:
      - TZ=Asia/Shanghai
docker compose up -d
docker compose logs -f

如果你使用的是项目 release 二进制，也可以把配置目录挂载到固定路径，便于升级时保留账号和配置。

四、二进制安装思路

二进制方式适合不想引入 Docker 的 VPS。基本流程是：下载 release、解压、写配置、创建 systemd 服务。

# 示例流程，版本号和文件名请以 GitHub Releases 为准
mkdir -p /opt/cliproxyapi
cd /opt/cliproxyapi

# 下载对应系统架构的 release
# wget https://github.com/router-for-me/CLIProxyAPI/releases/download/vX.X.X/xxx-linux-amd64.tar.gz
# tar xzf xxx-linux-amd64.tar.gz

chmod +x cliproxyapi
./cliproxyapi --help

创建 systemd 服务示例：

sudo nano /etc/systemd/system/cliproxyapi.service
[Unit]
Description=CLIProxyAPI Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/cliproxyapi
ExecStart=/opt/cliproxyapi/cliproxyapi
Restart=always
RestartSec=5
Environment=TZ=Asia/Shanghai

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now cliproxyapi
sudo systemctl status cliproxyapi
sudo journalctl -u cliproxyapi -f

五、初始化账号和 OAuth 登录

CLIProxyAPI 的核心是把 CLI/OAuth 账号接入代理。不同后端的登录方式不同，通常会在本地或管理端触发 OAuth 授权流程。常见后端包括：

  • Gemini CLI / AI Studio
  • OpenAI Codex / ChatGPT OAuth
  • Claude Code OAuth
  • Grok Build OAuth
  • 自定义 OpenAI-compatible 上游

登录完成后，服务会保存账号凭据，并在请求时按配置路由到对应后端。多账号场景下，可以设置轮询、别名、模型映射和 fallback。

六、OpenAI 兼容调用示例

配置完成后，客户端通常可以把 Base URL 指向 CLIProxyAPI。以下是 OpenAI Chat Completions 风格示例：

curl http://127.0.0.1:8317/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro",
    "messages": [
      {"role": "user", "content": "你好，介绍一下 CLIProxyAPI"}
    ],
    "stream": true
  }'

如果客户端支持 OpenAI SDK，也可以这样配置：

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key",
    base_url="http://127.0.0.1:8317/v1"
)

resp = client.chat.completions.create(
    model="gemini-3-pro",
    messages=[{"role": "user", "content": "hello"}]
)
print(resp.choices[0].message.content)

七、反向代理 HTTPS

如果要给外部客户端使用，建议通过 Nginx/Caddy 暴露 HTTPS，不要直接开放裸端口。

server {
    listen 80;
    server_name cpa.example.com;

    location / {
        proxy_pass http://127.0.0.1:8317;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

八、接入 Open WebUI

在 Open WebUI 中添加 OpenAI-compatible 连接：

  • Base URL：https://你的域名/v1
  • API Key：CLIProxyAPI 中配置的访问密钥
  • Model：填写 CLIProxyAPI 暴露的模型别名，例如 gemini-3-pro、claude-sonnet、gpt-5 等

九、常用运维命令

# Docker
docker compose ps
docker compose logs -f
docker compose restart
docker compose pull && docker compose up -d

# systemd
sudo systemctl status cliproxyapi
sudo journalctl -u cliproxyapi -f
sudo systemctl restart cliproxyapi

十、安全建议

  • 管理端口尽量只监听 127.0.0.1 或放在内网。
  • 公网访问必须加 HTTPS，并建议加 Cloudflare Access、Basic Auth 或 IP 白名单。
  • OAuth 凭据目录要备份，但不要公开。
  • 不同账号建议做分组和限流，避免单账号被打满。
  • 不要把真实 API Key、OAuth token、配置文件发到公开仓库。

十一、总结

CLIProxyAPI 适合把多个 CLI/OAuth 账号统一包装成标准 API，尤其适合 AI 编程工具、多账号池和 OpenAI-compatible 客户端接入。部署时建议先本地或内网测试，确认账号登录、模型映射和调用链路稳定后，再通过 HTTPS 反代提供给外部客户端。

归档