CLI Proxy API 完全指南：统一多个 AI 服务的代理解决方案

Frank Dum2026-02-032026-02-04

前言

在 AI 编程助手百花齐放的今天，开发者常常需要同时使用多个 AI 服务：Claude Code、Gemini CLI、OpenAI Codex 等。每个服务都有独立的认证方式、API 格式和调用方法，管理起来相当繁琐。

CLI Proxy API 正是为解决这个问题而生。它是一个开源代理服务器，提供统一的 OpenAI/Gemini/Claude 兼容 API 接口，让你通过单一端点访问所有 AI 服务。

项目地址：https://github.com/router-for-me/CLIProxyAPI

核心价值

统一接口：一套 API 访问所有 AI 模型
OAuth 认证：无需 API Key，使用 OAuth 登录即可
负载均衡：多账户轮询，提高可用性
协议兼容：支持 Chat Completions、Response、Gemini、Claude 等多种协议

核心特性

支持的 AI 服务

服务	认证方式	特性
Claude Code	OAuth 登录	完整功能支持
Gemini CLI	OAuth 登录	多账户负载均衡
OpenAI Codex	OAuth 登录	GPT 模型访问
Qwen Code	OAuth 登录	通义千问模型
iFlow	OAuth 登录	集成支持

主要功能

流式和非流式响应
函数调用 / 工具支持
多模态输入（文本 + 图像）
模型别名映射
请求重试机制
WebSocket 支持

安装部署

macOS

使用 Homebrew 一键安装：

# 安装
brew install cliproxyapi

# 启动服务
brew services start cliproxyapi

Linux

一键安装脚本：

1	curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer \| bash

Arch Linux (AUR)：

# 使用 yay
yay -S cli-proxy-api-bin

# 或使用 paru
paru -S cli-proxy-api-bin

服务管理：

# 启动服务
systemctl --user start cli-proxy-api

# 开机自启
systemctl --user enable cli-proxy-api

配置文件初始化：

1 2	mkdir -p ~/.cli-proxy-api cp /usr/share/doc/cli-proxy-api-bin/config.example.yaml ~/.cli-proxy-api/config.yaml

Windows

从 GitHub Releases 下载最新版本，或使用桌面 GUI 应用。

Docker 部署

docker run --rm -p 8317:8317 \
  -v /path/to/config.yaml:/CLIProxyAPI/config.yaml \
  -v /path/to/auth-dir:/root/.cli-proxy-api \
  eceasy/cli-proxy-api:latest

Docker Compose：

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    ports:
      - "8317:8317"
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auth:/root/.cli-proxy-api
    restart: unless-stopped

源码编译

# 克隆仓库
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI

# 编译（Linux/macOS）
go build -o cli-proxy-api ./cmd/server

# 编译（Windows）
go build -o cli-proxy-api.exe ./cmd/server

# 运行
./cli-proxy-api

配置详解

配置文件使用 YAML 格式，默认位置为 ~/.cli-proxy-api/config.yaml。

基础配置

# 服务器设置
host: ""           # 空字符串监听所有接口，"127.0.0.1" 仅本地
port: 8317         # 服务端口
debug: false       # 调试模式
logging-to-file: false  # 日志写入文件

# TLS 配置（可选）
tls:
  cert: /path/to/cert.pem
  key: /path/to/key.pem

认证配置

# API 密钥（客户端访问认证）
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"

# 认证文件目录
auth-dir: ~/.cli-proxy-api

# WebSocket 认证
ws-auth: true

# 管理 API 配置
remote-management:
  allow-remote: false      # 是否允许远程访问管理 API
  secret-key: "your-secret"  # 管理密钥
  disable-control-panel: false

Gemini 配置

gemini-api-key:
  - api-key: "AIzaSy..."
    prefix: "test"           # 可选：请求前缀
    base-url: "https://generativelanguage.googleapis.com"
    models:
      - name: "gemini-2.5-flash"
        alias: "gemini-flash"  # 模型别名
    excluded-models:
      - "gemini-2.5-*"       # 排除的模型（支持通配符）

Claude 配置

claude-api-key:
  - api-key: "sk-atSM..."
    cloak:                   # 请求伪装配置
      mode: "auto"           # auto/always/never
      strict-mode: false
      sensitive-words:
        - "API"
        - "proxy"

OpenAI 兼容配置

openai-compatibility:
  - name: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: "sk-or-v1-..."

高级配置

# 路由策略
routing:
  strategy: "round-robin"    # round-robin 或 fill-first

# 请求重试
request-retry: 3
max-retry-interval: 30s

# 代理设置
proxy-url: "http://127.0.0.1:7890"

# 流式响应保活
streaming:
  keepalive-seconds: 30

# 请求参数修改
payload:
  default:                   # 设置缺失参数的默认值
    - models:
        - name: "gemini-2.5-pro"
      params:
        "generationConfig.thinkingConfig.thinkingBudget": 32768

API 使用

服务启动后，默认监听 http://localhost:8317。

兼容端点

CLI Proxy API 提供多种兼容格式的端点：

端点	兼容格式
`/v1/chat/completions`	OpenAI Chat Completions
`/v1/responses`	OpenAI Responses
`/v1beta/models`	Gemini API
`/v1/messages`	Claude API

调用示例

OpenAI 格式调用：

curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "stream": false
  }'

Python 调用：

from openai import OpenAI

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

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {"role": "user", "content": "用 Python 写一个快速排序"}
    ]
)

print(response.choices[0].message.content)

管理 API

管理 API 基础路径：http://localhost:8317/v0/management

认证方式：

# Header 认证
Authorization: Bearer <management-secret-key>
# 或
X-Management-Key: <management-secret-key>

常用端点：

# 获取配置
curl -H "Authorization: Bearer <KEY>" \
  http://localhost:8317/v0/management/config

# 获取使用统计
curl -H "Authorization: Bearer <KEY>" \
  http://localhost:8317/v0/management/usage

# 启动 OAuth 登录（Claude）
curl -H "Authorization: Bearer <KEY>" \
  http://localhost:8317/v0/management/anthropic-auth-url

# 启动 OAuth 登录（Gemini）
curl -H "Authorization: Bearer <KEY>" \
  "http://localhost:8317/v0/management/gemini-cli-auth-url?project_id=<PROJECT_ID>"

# 查看认证文件
curl -H "Authorization: Bearer <KEY>" \
  http://localhost:8317/v0/management/auth-files

实战示例

多账户负载均衡

配置多个 Gemini 账户实现负载均衡：

gemini-api-key:
  - api-key: "AIzaSy...account1"
  - api-key: "AIzaSy...account2"
  - api-key: "AIzaSy...account3"

routing:
  strategy: "round-robin"  # 轮询策略

模型别名映射

将复杂的模型名映射为简短别名：

oauth-model-alias:
  gpt4: "gpt-4-turbo-preview"
  claude: "claude-3-opus-20240229"
  gemini: "gemini-2.5-pro"

调用时直接使用别名：

1 2	curl http://localhost:8317/v1/chat/completions \ -d '{"model": "gemini", "messages": [...]}'

IDE 集成

VS Code 配置（settings.json）：

{
  "openai.apiKey": "your-api-key",
  "openai.baseUrl": "http://localhost:8317/v1"
}

Cursor 配置：

在 Cursor 设置中将 API Base URL 设置为 http://localhost:8317/v1。

生态工具

CLI Proxy API 拥有丰富的生态系统：

工具	平台	说明
vibeproxy	macOS	菜单栏应用，无需 API Key 使用 AI
ProxyPal	macOS	GUI 管理工具
CodMate	macOS	SwiftUI 会话管理应用
ProxyPilot	Windows	Windows 原生客户端
Claude Proxy VSCode	VSCode	VSCode 扩展
ZeroLimit	Windows	配额监控工具
CPA-XXX Panel	Web	轻量级 Web 管理面板

常见问题

服务无法启动

检查配置文件格式是否正确：

1 2	# 验证 YAML 格式 cat ~/.cli-proxy-api/config.yaml \| python -c "import yaml,sys; yaml.safe_load(sys.stdin)"

OAuth 登录失败

确保网络可以访问对应服务
检查是否需要配置代理：

1	proxy-url: "http://127.0.0.1:7890"

请求超时

调整重试配置：

1 2	request-retry: 5 max-retry-interval: 60s

总结

CLI Proxy API 是一个功能强大的 AI 服务代理工具，它解决了多 AI 服务管理的痛点：

统一入口：一个端点访问所有 AI 模型
简化认证：OAuth 登录，无需管理多个 API Key
高可用：多账户负载均衡，自动重试
灵活配置：模型别名、请求修改、协议转换

无论你是个人开发者还是团队使用，CLI Proxy API 都能显著提升 AI 服务的使用体验。

相关链接：

GitHub：https://github.com/router-for-me/CLIProxyAPI
文档：https://help.router-for.me/