😯 模型自由 - 2026 全网最详细手把手带你用上AI代理神器 - CLIProxyAPI

Prorise2026-01-052026-01-09

CLIProxyAPI：把 CLI 订阅变成通用 API

我在项目中需要调用 Gemini 和 Qwen 模型，但每个客户端都要单独配置 OAuth 很麻烦。CLIProxyAPI 解决了这个问题——它把 CLI 工具的 OAuth 授权转换成标准 API Key，任何支持 OpenAI 格式的客户端都能直接用。

这篇文章分三部分：

CLIProxyAPI 能做什么
实战：把 Qwen Code 变成 API
配置文件详解

一、CLIProxyAPI 能做什么

1.1 核心能力

CLIProxyAPI 是一个 Go 语言写的代理服务器，核心功能是 把各种 CLI 工具的 OAuth 授权转换成 OpenAI 兼容的 API 接口。

这意味着：

不用安装 Gemini CLI，就能用 Gemini 2.5 Pro
不用安装 Qwen Code，就能用 Qwen3 Coder
不用安装 Codex，就能用 GPT-5
不用折腾 Cookie，就能用 Gemini 网页版的 Nano Banana 模型

转换后的 API Key 可以在 Cherry Studio、Cursor、Continue 等任何支持 OpenAI 格式的客户端中使用。

1.2 支持的模型

来源	支持的模型
Gemini CLI	gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite，以及最新
Qwen Code	qwen3-coder-plus, qwen3-coder-flash, qwen3-max，以及最新
OpenAI Codex	gpt-5, gpt-5-codex，以及最新
Claude Code	claude-opus-4, claude-sonnet-4, claude-3-7-sonnet，以及最新
Gemini Web	gemini-2.5-flash-image-preview (Nano Banana)，以及最新
iFlow	deepseek-v3.2, deepseek-r1, kimi-k2, glm-4.5 等，以及最新

1.3 多账户轮询

CLIProxyAPI 支持配置多个账户进行负载均衡。比如你有 3 个 Google 账号，每个账号每天有 1000 次 Gemini 调用配额，配置好之后就有 3000 次。

当一个账号触发限流（429 错误），程序会自动切换到下一个账号继续请求，客户端完全无感知。

1.4 资源消耗

程序本身只有 10MB 左右，启动时内存占用不到 10MB，长时间运行峰值也就 100MB。基本上任何电脑都能跑。

二、实战：把 Qwen Code 变成 API

下面以 Windows 为例，演示如何把 Qwen Code 的 OAuth 授权转换成 API Key。

2.1 下载程序

从 GitHub 下载预编译的可执行文件：
🔗 链接地址：Release v6.6.84 · router-for-me/CLIProxyAPI

解压到任意目录，比如 E:\CLIProxyAPI。只需要用到两个文件：

cli-proxy-api.exe - 主程序
config.example.yaml - 配置模板

2.2 创建配置文件

把 config.example.yaml 重命名为 config.yaml，用 vscode 或其他编辑器打开，改成这样：

# 服务端口
port: 8317
# 认证文件存放目录，Windows下用双反斜杠
auth-dir: "E:\\CLIProxyAPI\\auths"
# 请求失败时的重试次数
request-retry: 3
# 账号限流后的处理
quota-exceeded:
# 自动切换到下一个账号
  switch-project: true
# Gemini配额用完后自动切换到Preview模型
  switch-preview-model: true
# 客户端访问代理需要的Key，自己设置一个
api-keys:
  - "ABC-123456"
# 管理 API 设置
remote-management:
# 是否允许远程（非本地）管理访问。
# 为 false 时，仅允许 localhost 访问管理端点（仍需要密钥）。
  allow-remote: false
# 管理密钥。如果此处提供明文值，启动时将进行哈希处理。
# 所有管理请求（即使来自 localhost）都需要此密钥。
# 留空将完全禁用管理 API（所有 /v0/management 路由返回 404）。
  secret-key: "这里输入你的密钥，是用来上管理后台的密钥，和API密钥不同！"
# 为 true 时，禁用内置管理控制台资源的下载和 HTTP 路由。
  disable-control-panel: false
# 管理控制台的 GitHub 仓库。接受仓库 URL 或 Releases API URL。
  panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"

这是最小配置，够用了。

2.3 获取 OAuth 授权

在 CLIProxyAPI 目录下打开终端（在文件夹空白处按住 Shift 点右键，选 “在此处打开 PowerShell 窗口”），输入：

1	.\cli-proxy-api.exe --qwen-login

程序会自动打开浏览器，登录你的 Qwen 账户并完成授权。

授权完成后回到终端，程序会提示输入邮箱或昵称。这只是个标识，随便填，比如 qwen-example。

授权成功

认证文件会保存到 auth-dir 指定的目录。

如果浏览器没自动打开，手动复制终端里显示的 URL 到浏览器打开就行。

2.4 启动代理服务

双击 cli-proxy-api.exe，看到类似下面的输出就是启动成功了：

1 2	[INFO] Server started on :8317 [INFO] Loaded 1 Qwen account(s)

2.5 在客户端中使用

以 Claude code 中的可视化软件为例，相关软件见：Claude Code 可视化桌面工具

同样的，支持所有软件，这里就不一一举例了，本质上有 API 密钥和地址就可以了

添加新的模型提供商
填写连接信息：
- API 密钥：ABC-123456（就是 config.yaml 里设置的那个）
- API 地址：http://127.0.0.1:8317
点 “管理模型”，能看到 Qwen Code 的模型列表
测试一下

模型正常返回，配置完成

2.6 可视化管理后台

在 2.2 小节中我们配置了管理后台的配置，输入了密码，我们可以登录：CLI Proxy API Management Center 本地管理后台进行配置，页面如下，详细内容请自由探索或访问官方文档 Web UI | CLIProxyAPI 进行查阅

三、配置文件详解

配置文件支持热重载，改完直接生效，不用重启程序，完整的汉化配置如下，可以通过点击按钮后自取，以下会对于配置进行逐一解释，也可以把汉化后的配置直接粘贴至config.yaml进行配置

# 服务器主机名/接口绑定地址。默认为空 ("") 表示绑定所有接口 (IPv4 + IPv6)。
# 使用 "127.0.0.1" 或 "localhost" 仅限制本地访问。
host: ""

# 服务器端口
port: 8317

# HTTPS 的 TLS 设置。启用后，服务器将使用提供的证书和密钥进行监听。
tls:
  enable: false
  cert: ""
  key: ""

# 管理 API 设置
remote-management:
  # 是否允许远程（非本地）管理访问。
  # 为 false 时，仅允许 localhost 访问管理端点（仍需要密钥）。
  allow-remote: false

  # 管理密钥。如果此处提供明文值，启动时将进行哈希处理。
  # 所有管理请求（即使来自 localhost）都需要此密钥。
  # 留空将完全禁用管理 API（所有 /v0/management 路由返回 404）。
  secret-key: ""

  # 为 true 时，禁用内置管理控制台资源的下载和 HTTP 路由。
  disable-control-panel: false

  # 管理控制台的 GitHub 仓库。接受仓库 URL 或 Releases API URL。
  panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"

# 认证目录（支持 ~ 表示主目录）
auth-dir: "~/.cli-proxy-api"

# 用于认证的 API 密钥
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"
  - "your-api-key-3"

# 启用调试日志
debug: false

# 为 true 时，禁用高开销的 HTTP 中间件功能，以减少高并发下的单次请求内存使用。
commercial-mode: false

# 为 true 时，将应用程序日志写入轮转文件而不是标准输出 (stdout)
logging-to-file: false

# 日志目录下日志文件的最大总大小 (MB)。超出时，将删除最旧的日志文件直到限制范围内。设置为 0 禁用此功能。
logs-max-total-size-mb: 0

# 为 false 时，禁用内存中的使用情况统计聚合
usage-statistics-enabled: false

# 代理 URL。支持 socks5/http/https 协议。示例：socks5://user:pass@192.168.1.1:1080/
proxy-url: ""

# 为 true 时，无前缀的模型请求仅使用无前缀的凭据（除非 prefix == model name）。
force-model-prefix: false

# 请求重试次数。如果 HTTP 响应代码为 403, 408, 500, 502, 503 或 504，将进行重试。
request-retry: 3

# 冷却中的凭据在触发重试前的最大等待时间（秒）。
max-retry-interval: 30

# 配额超限行为
quota-exceeded:
  switch-project: true # 配额超限时是否自动切换到另一个项目
  switch-preview-model: true # 配额超限时是否自动切换到预览模型

# 当有多个匹配凭据时的路由策略。
routing:
  strategy: "round-robin" # round-robin (默认轮询), fill-first (优先填满)

# 为 true 时，启用 WebSocket API (/v1/ws) 的认证。
ws-auth: false

# 流式传输行为 (SSE 保活 + 安全引导重试)。
# streaming:
#   keepalive-seconds: 15   # 默认: 0 (禁用)。<= 0 禁用保活。
#   bootstrap-retries: 1    # 默认: 0 (禁用)。发送首个字节前的重试次数。

# Gemini API 密钥
# gemini-api-key:
#   - api-key: "AIzaSy...01"
#     prefix: "test" # 可选：要求类似 "test/gemini-3-pro-preview" 的调用才使用此凭据
#     base-url: "https://generativelanguage.googleapis.com"
#     headers:
#       X-Custom-Header: "custom-value"
#     proxy-url: "socks5://proxy.example.com:1080"
#     models:
#       - name: "gemini-2.5-flash" # 上游模型名称
#         alias: "gemini-flash"    # 映射到上游模型的客户端别名
#     excluded-models:
#       - "gemini-2.5-pro"     # 排除此提供商的特定模型（精确匹配）
#       - "gemini-2.5-*"       # 通配符匹配前缀（例如 gemini-2.5-flash, gemini-2.5-pro）
#       - "*-preview"          # 通配符匹配后缀（例如 gemini-3-pro-preview）
#       - "*flash*"            # 通配符匹配子串（例如 gemini-2.5-flash-lite）
#   - api-key: "AIzaSy...02"

# Codex API 密钥
# codex-api-key:
#   - api-key: "sk-atSM..."
#     prefix: "test" # 可选：要求类似 "test/gpt-5-codex" 的调用才使用此凭据
#     base-url: "https://www.example.com" # 使用自定义 codex API 端点
#     headers:
#       X-Custom-Header: "custom-value"
#     proxy-url: "socks5://proxy.example.com:1080" # 可选：每个密钥单独的代理覆盖
#     models:
#       - name: "gpt-5-codex"   # 上游模型名称
#         alias: "codex-latest" # 映射到上游模型的客户端别名
#     excluded-models:
#       - "gpt-5.1"         # 排除特定模型（精确匹配）
#       - "gpt-5-*"         # 通配符匹配前缀（例如 gpt-5-medium, gpt-5-codex）
#       - "*-mini"          # 通配符匹配后缀（例如 gpt-5-codex-mini）
#       - "*codex*"         # 通配符匹配子串（例如 gpt-5-codex-low）

# Claude API 密钥
# claude-api-key:
#   - api-key: "sk-atSM..." # 使用官方 Claude API 密钥，无需设置 base url
#   - api-key: "sk-atSM..."
#     prefix: "test" # 可选：要求类似 "test/claude-sonnet-latest" 的调用才使用此凭据
#     base-url: "https://www.example.com" # 使用自定义 Claude API 端点
#     headers:
#       X-Custom-Header: "custom-value"
#     proxy-url: "socks5://proxy.example.com:1080" # 可选：每个密钥单独的代理覆盖
#     models:
#       - name: "claude-3-5-sonnet-20241022" # 上游模型名称
#         alias: "claude-sonnet-latest"      # 映射到上游模型的客户端别名
#     excluded-models:
#       - "claude-opus-4-5-20251101" # 排除特定模型（精确匹配）
#       - "claude-3-*"               # 通配符匹配前缀（例如 claude-3-7-sonnet-20250219）
#       - "*-thinking"               # 通配符匹配后缀（例如 claude-opus-4-5-thinking）
#       - "*haiku*"                  # 通配符匹配子串（例如 claude-3-5-haiku-20241022）

# OpenAI 兼容提供商
# openai-compatibility:
#   - name: "openrouter" # 提供商名称；将用于 User Agent 和其他地方。
#     prefix: "test" # 可选：要求类似 "test/kimi-k2" 的调用才使用此提供商凭据
#     base-url: "https://openrouter.ai/api/v1" # 提供商的基础 URL。
#     headers:
#       X-Custom-Header: "custom-value"
#     api-key-entries:
#       - api-key: "sk-or-v1-...b780"
#         proxy-url: "socks5://proxy.example.com:1080" # 可选：每个密钥单独的代理覆盖
#       - api-key: "sk-or-v1-...b781" # 不带代理 URL
#     models: # 该提供商支持的模型。
#       - name: "moonshotai/kimi-k2:free" # 实际模型名称。
#         alias: "kimi-k2" # API 中使用的别名。

# Vertex API 密钥 (Vertex 兼容端点，使用 API key + base URL)
# vertex-api-key:
#   - api-key: "vk-123..."                        # x-goog-api-key 标头
#     prefix: "test"                              # 可选：要求类似 "test/vertex-pro" 的调用才使用此凭据
#     base-url: "https://example.com/api"         # 例如 https://zenmux.ai/api
#     proxy-url: "socks5://proxy.example.com:1080" # 可选：每个密钥单独的代理覆盖
#     headers:
#       X-Custom-Header: "custom-value"
#     models:                                     # 可选：将别名映射到上游模型名称
#       - name: "gemini-2.5-flash"                # 上游模型名称
#         alias: "vertex-flash"                   # 客户端可见的别名
#       - name: "gemini-2.5-pro"
#         alias: "vertex-pro"

# Amp 集成
# ampcode:
#   # 配置 Amp CLI OAuth 和管理功能的上游 URL
#   upstream-url: "https://ampcode.com"
#   # 可选：覆盖 Amp 上游 API 密钥（否则使用环境变量或文件）
#   upstream-api-key: ""
#   # 每个客户端的上游 API 密钥映射
#   # 将客户端 API 密钥（来自顶级 api-keys）映射到不同的 Amp 上游 API 密钥。
#   # 当不同客户端需要使用不同的 Amp 账户/配额时很有用。
#   # 如果客户端密钥未被映射，则回退到 upstream-api-key（默认行为）。
#   upstream-api-keys:
#     - upstream-api-key: "amp_key_for_team_a"    # 这些客户端使用的上游密钥
#       api-keys:                                 # 使用此上游密钥的客户端密钥
#         - "your-api-key-1"
#         - "your-api-key-2"
#     - upstream-api-key: "amp_key_for_team_b"
#       api-keys:
#         - "your-api-key-3"
#   # 限制 Amp 管理路由 (/api/auth, /api/user 等) 仅限 localhost 访问 (默认: false)
#   restrict-management-to-localhost: false
#   # 强制模型映射在检查本地 API 密钥之前运行 (默认: false)
#   force-model-mappings: false
#   # Amp 模型映射
#   # 将不可用的 Amp 模型路由到本地代理中可用的替代模型。
#   # 当 Amp CLI 请求你没有访问权限的模型（例如 Claude Opus 4.5）
#   # 但你有类似的可用模型（例如 Claude Sonnet 4）时很有用。
#   model-mappings:
#     - from: "claude-opus-4-5-20251101"          # Amp CLI 请求的模型
#       to: "gemini-claude-opus-4-5-thinking"     # 路由到此可用模型
#     - from: "claude-sonnet-4-5-20250929"
#       to: "gemini-claude-sonnet-4-5-thinking"
#     - from: "claude-haiku-4-5-20251001"
#       to: "gemini-2.5-flash"

# 全局 OAuth 模型名称映射（按通道）
# 这些映射会重命名模型列表和请求路由中的模型 ID。
# 支持的通道：gemini-cli, vertex, aistudio, antigravity, claude, codex, qwen, iflow。
# 注意：映射不适用于 gemini-api-key, codex-api-key, claude-api-key, openai-compatibility, vertex-api-key 或 ampcode。
# oauth-model-mappings:
#   gemini-cli:
#     - name: "gemini-2.5-pro"          # 此通道下的原始模型名称
#       alias: "g2.5p"                  # 客户端可见的别名
#       fork: true                      # 为 true 时，保留原始模型名称，并添加别名作为额外模型（默认：false）
#   vertex:
#     - name: "gemini-2.5-pro"
#       alias: "g2.5p"
#   aistudio:
#     - name: "gemini-2.5-pro"
#       alias: "g2.5p"
#   antigravity:
#     - name: "gemini-3-pro-preview"
#       alias: "g3p"
#   claude:
#     - name: "claude-sonnet-4-5-20250929"
#       alias: "cs4.5"
#   codex:
#     - name: "gpt-5"
#       alias: "g5"
#   qwen:
#     - name: "qwen3-coder-plus"
#       alias: "qwen-plus"
#   iflow:
#     - name: "glm-4.7"
#       alias: "glm-god"

# OAuth 提供商排除的模型
# oauth-excluded-models:
#   gemini-cli:
#     - "gemini-2.5-pro"     # 排除特定模型（精确匹配）
#     - "gemini-2.5-*"       # 通配符匹配前缀（例如 gemini-2.5-flash, gemini-2.5-pro）
#     - "*-preview"          # 通配符匹配后缀（例如 gemini-3-pro-preview）
#     - "*flash*"            # 通配符匹配子串（例如 gemini-2.5-flash-lite）
#   vertex:
#     - "gemini-3-pro-preview"
#   aistudio:
#     - "gemini-3-pro-preview"
#   antigravity:
#     - "gemini-3-pro-preview"
#   claude:
#     - "claude-3-5-haiku-20241022"
#   codex:
#     - "gpt-5-codex-mini"
#   qwen:
#     - "vision-model"
#   iflow:
#     - "tstars2.0"

# 可选的 Payload 配置
# payload:
#   default: # default 规则仅在 Payload 中缺少参数时设置参数。
#     - models:
#         - name: "gemini-2.5-pro" # 支持通配符（例如 "gemini-*"）
#           protocol: "gemini" # 将规则限制为特定协议，选项：openai, gemini, claude, codex
#       params: # JSON 路径 (gjson/sjson 语法) -> 值
#         "generationConfig.thinkingConfig.thinkingBudget": 32768
#   override: # override 规则始终设置参数，覆盖任何现有值。
#     - models:
#         - name: "gpt-*" # 支持通配符（例如 "gpt-*"）
#           protocol: "codex" # 将规则限制为特定协议，选项：openai, gemini, claude, codex
#       params: # JSON 路径 (gjson/sjson 语法) -> 值
#         "reasoning.effort": "high"

3.1 基础配置

# 服务端口
# 如果8317被占用，换成其他端口
port: 8317

# 认证文件存放目录
# 默认是用户目录下的 .cli-proxy-api 文件夹
# Windows: C:\Users\你的用户名\.cli-proxy-api
# Linux: /home/你的用户名/.cli-proxy-api
# 用默认值就行，除非你有特殊需求
auth-dir: "~/.cli-proxy-api"

# 是否输出Debug日志
# 平时关着，遇到问题需要排查时打开
debug: false

# 是否把日志写到文件
# 开启后日志保存在程序目录的logs文件夹
# 关闭则直接输出到控制台
logging-to-file: true

# 是否开启使用统计
# 可以通过WebUI或EasyCLI查看调用量
usage-statistics-enabled: true

# 代理设置
# 如果你的网络需要代理才能访问外网，在这里配置
# 支持 socks5/http/https 协议
# 格式：socks5://user:pass@192.168.1.1:1080/
proxy-url: ""

# 请求失败时的重试次数
# 遇到403, 408, 500, 502, 503, 504这些错误码会自动重试
request-retry: 3

3.2 远程管理配置

remote-management:
  # 是否允许远程访问管理接口
  # 本地使用设为false，部署到服务器上设为true
  allow-remote: false

  # 管理接口的密钥
  # 如果要用EasyCLI或WebUI远程管理，必须设置这个
  # 不需要远程管理就留空
  secret-key: ""

  # 是否禁用内置的WebUI
  # 设为false可以通过 http://IP:端口/management.html 打开管理界面
  disable-control-panel: false

3.3 限流处理配置

quota-exceeded:
  # 多账户轮询的核心开关
  # true: 一个账号触发429，自动切换到下一个账号重试
  # false: 直接把429错误返回给客户端
  # 如果你配了多个账号，建议开启
  switch-project: true

  # Gemini专用配置
  # 正式版配额用完后，自动切换到Preview模型
  # 比如 gemini-2.5-pro 用完了，自动切到 gemini-2.5-pro-preview-05-06
  switch-preview-model: true

3.4 API Key 配置

这里有两种 Key，别搞混了：

api-keys：客户端访问 CLIProxyAPI 需要的 Key（你自己设置的）
其他的 Key：CLIProxyAPI 访问上游服务需要的 Key

# 客户端访问代理需要的Key
# 可以设置多个，任意一个都能用
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"

Gemini 官方 API Key

# 如果你有Gemini的官方API Key，可以填在这里
# 注意：官方Key的配额比CLI授权少，填了会一起参与轮询
# 如果你已经配了Gemini CLI授权，不建议再填这个
generative-language-api-key:
  - "AIzaSy...01"
  - "AIzaSy...02"

Codex 中转 Key

# 第三方中转站提供的Codex Key
codex-api-key:
  - api-key: "sk-atSM..."
    base-url: "https://www.example.com"

Claude Key

# Claude的Key
# 官方Key不填base-url，第三方中转填base-url
claude-api-key:
  - api-key: "sk-atSM..."  # 官方Key
  - api-key: "sk-atSM..."
    base-url: "https://www.example.com"  # 中转Key

OpenAI 兼容接口

# 接入其他OpenAI兼容的服务商（比如OpenRouter）
openai-compatibility:
  - name: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    api-keys:
      - "sk-or-v1-...b780"
      - "sk-or-v1-...b781"
    models:
      # name是服务商提供的模型名
      # alias是你想在客户端看到的名字
      - name: "moonshotai/kimi-k2:free"
        alias: "kimi-k2"

3.5 Gemini Web 配置

这部分是给 Gemini 网页版用的，如果你不用 Nano Banana 模型，可以跳过。

gemini-web:
  # 会话状态管理
  # true: 程序会记住之前的对话，只发送新消息
  # false: 每次都把完整上下文发给服务器
  # 用Nano Banana必须设为true，否则无法连续对话修图
  context: true

  # 单次请求的最大字符数
  # 保持默认就行
  max-chars-per-request: 1000000

  # 消息截断时是否附加等待提示
  # 当消息超长需要分批发送时，程序会在末尾加一条"请等待"的消息
  # 保持false即可
  disable-continuation-hint: false

  # 编程模式
  # 开启后会使用系统自带的编码助手Gem，思考内容会并入正文
  # 用Nano Banana必须关闭
  # 不写代码就别开
  code-mode: false

四、其他 CLI 工具的授权方式

上面演示的是 Qwen Code，其他工具的授权命令：

工具	授权命令
Gemini CLI	`cli-proxy-api --login --project_id [项目ID]`
OpenAI Codex	`cli-proxy-api --codex-login`
Claude Code	`cli-proxy-api --claude-login`
iFlow	`cli-proxy-api --iflow-login`

流程都一样：运行命令 → 浏览器授权 → 输入标识名 → 完成。

如果要配置多个账号，重复执行授权命令就行，每次用不同的标识名。

下面详细说明 Codex 和 Gemini CLI 的配置过程，因为这两个稍微复杂一点。