CLIProxyAPI 完整配置指南：从入门到实战#

说实话，第一次看到这个工具的时候，我有点懵。它到底能解决什么问题？后来折腾了一阵子才明白——CLIProxyAPI 是个挺有意思的中间层，专门用来打通各种 AI 编程助手的 OAuth 订阅和 OpenAI 兼容的 API 格式。

简单讲，如果你手上有 Gemini CLI、Claude Code、OpenAI Codex 或者 Qwen Code 的订阅，但想把这些模型接到 Cursor、Cline、Roo Code 这类支持 OpenAI API 格式的工具里用，CLIProxyAPI 就是干这个的。它把 OAuth 那套登录流程封装起来，对外暴露标准的 /v1/chat/completions 接口，让你不用管背后到底是哪个提供商在响应。

这篇文章把我实际用过的配置完整贴出来，逐段解释每个字段是干嘛的，顺便说说踩过的坑。

完整配置分享#

以下是一份生产环境真实使用的配置，敏感信息已脱敏处理（用 xxx 或占位符替换）：

1
# 基础服务配置
2
port: 8317
3
tls:
4
  enable: false
5
  cert: /root/.acme.sh/xxx.com_ecc/xxx.com.cer
6
  key: /root/.acme.sh/xxx.com_ecc/xxx.com.key
7

8
# 远程管理面板配置
9
remote-management:
10
  allow-remote: true
11
  secret-key: xxx
12
  disable-control-panel: false
13
  panel-github-repository: https://github.com/kongkongyo/Cli-Proxy-API-Management-Center
14

15
# 认证文件存放目录
16
auth-dir: /root/cliproxyapi/auth
17

18
# API 访问密钥列表
19
api-keys:
20
  - sk-xxx-key-1
21
  - sk-xxx-key-2
22
  - sk-xxx-key-3
23
  - sk-xxx-key-4
24
  - sk-xxx-key-5
25
  - sk-xxx-key-6
26
  - sk-xxx-key-7
27
  - sk-xxx-key-8
28
  - sk-xxx-key-9
29
  - sk-xxx-key-10
30
  - sk-xxx-key-11
31

32
# 调试与日志配置
33
debug: true
34
commercial-mode: false
35
logging-to-file: true
36
logs-max-total-size-mb: 10
37
usage-statistics-enabled: true
38

39
# 请求路由与重试配置
40
force-model-prefix: false
41
request-retry: 3
42
max-retry-interval: 20
43

44
# 配额超限处理策略
45
quota-exceeded:
46
  switch-project: true
47
  switch-preview-model: true
48

49
# 负载均衡策略
50
routing:
51
  strategy: round-robin
52

53
# WebSocket 认证开关
54
ws-auth: true
55

56
# 非流式请求保活间隔
57
nonstream-keepalive-interval: 15
58

59
# 流式响应配置
60
streaming:
61
  keepalive-seconds: 15
62
  bootstrap-retries: 2
63

64
# Codex 指令功能开关
65
codex-instructions-enabled: false
66

67
# OAuth 模型别名映射
68
oauth-model-alias:
69
  antigravity:
70
    - name: gemini-3-pro-image
71
      alias: gemini-3-pro-image-preview
72
    - name: gemini-3-pro-high
73
      alias: gemini-3-pro-preview
74
    - name: gemini-3-flash
75
      alias: gemini-3-flash-preview
76
    - name: gpt-oss-120b-medium
77
      alias: gpt-oss-120b
78
  qwen:
79
    - name: vision-model
80
      alias: qwen3-vision-model
81
    - name: coder-model
82
      alias: qwen3.5-plus
83
  github-copilot:
84
    - name: claude-haiku-4.5
85
      alias: claude-haiku-4-5
86
    - name: claude-opus-4.1
87
      alias: claude-opus-4-1
88
    - name: claude-opus-4.5
89
      alias: claude-opus-4-5
90
    - name: claude-opus-4.6
91
      alias: claude-opus-4-6
92
    - name: claude-sonnet-4.5
93
      alias: claude-sonnet-4-5
94
    - name: claude-sonnet-4.6
95
      alias: claude-sonnet-4-6
96
  kiro:
97
    - name: kiro-claude-sonnet-4-5
98
      alias: claude-sonnet-4-5
99
    - name: kiro-claude-sonnet-4
100
      alias: claude-sonnet-4
101
    - name: kiro-claude-opus-4-6
102
      alias: claude-opus-4-6
103
    - name: kiro-claude-opus-4-5
104
      alias: claude-opus-4-5
105
    - name: kiro-claude-haiku-4-5
106
      alias: claude-haiku-4-5
107
    - name: kiro-gpt-4o
108
      alias: gpt-4o
109
    - name: kiro-gpt-3-5-turbo
110
      alias: gpt-3.5-turbo
111
    - name: kiro-gpt-4
112
      alias: gpt-4
113
    - name: kiro-gpt-4-turbo
114
      alias: gpt-4-turbo
115
    - name: kiro-qwen3-coder-next
116
      alias: qwen3-coder-next
117
    - name: kiro-deepseek-3-2
118
      alias: deepseek-v3.2
119
    - name: kiro-minimax-m2-1
120
      alias: minimax-m2.1
121
    - name: kiro-claude-sonnet-4-6
122
      alias: claude-sonnet-4-6
123

124
# 错误日志文件数量限制
125
error-logs-max-files: 10
126

127
# pprof 性能分析配置
128
pprof:
129
  enable: false
130
  addr: 127.0.0.1:8316
131

132
# OpenAI 兼容的第三方提供商配置
133
openai-compatibility:
134
  # 智谱 AI (BigModel)
135
  - name: bigmodel
136
    base-url: https://open.bigmodel.cn/api/paas/v4
137
    api-key-entries:
138
      - api-key: xxx
139
        proxy-url: socks5://127.0.0.1:40000
140
    models:
141
      - name: GLM-4.7-Flash
142
        alias: glm-4.7-flash
143
      - name: GLM-4.6V-Flash
144
        alias: glm-4.6v-flash
145
      - name: GLM-Z1-Flash
146
        alias: glm-z1-flash
147
      - name: GLM-4.1V-Thinking-Flash
148
        alias: glm-4.1v-thinking-flash
149
    headers:
150
      Content-Type: application/json
151
      Accept: "*/*"
152
      Accept-Encoding: "gzip, br"
153
      User-Agent: "opencode/1.2.25 ai-sdk/provider-utils/3.0.20 runtime/bun/1.3.10"
154

155
  # OpenRouter 聚合平台
156
  - name: openrouter
157
    base-url: https://openrouter.ai/api/v1
158
    api-key-entries:
159
      - api-key: sk-or-v1-xxx
160
        proxy-url: socks5://127.0.0.1:40000
161
      - api-key: sk-or-v1-xxx
162
        proxy-url: socks5://127.0.0.1:40000
163
      - api-key: sk-or-v1-xxx
164
        proxy-url: socks5://127.0.0.1:40000
165
    models:
166
      - name: arcee-ai/trinity-large-preview:free
167
        alias: trinity-large-preview
168
      - name: openai/gpt-oss-120b:free
169
        alias: gpt-oss-120b
170
      - name: openai/gpt-oss-20b:free
171
        alias: gpt-oss-20b
172
      - name: z-ai/glm-4.5-air:free
173
        alias: glm-4.5-air
174
      - name: stepfun/step-3.5-flash:free
175
        alias: step-3.5-flash
176
    headers:
177
      Content-Type: application/json
178
      Accept: "*/*"
179
      Accept-Encoding: "gzip, br"
180
      User-Agent: "opencode/1.2.25 ai-sdk/provider-utils/3.0.20 runtime/bun/1.3.10"
181

182
  # NVIDIA NIM 平台
183
  - name: nvidia
184
    base-url: https://integrate.api.nvidia.com/v1
185
    api-key-entries:
186
      - api-key: nvapi-xxx
187
        proxy-url: socks5://127.0.0.1:40000
188
      - api-key: nvapi-xxx
189
        proxy-url: socks5://127.0.0.1:40000
190
      - api-key: nvapi-xxx
191
        proxy-url: socks5://127.0.0.1:40000
192
    models:
193
      - name: openai/gpt-oss-120b
194
        alias: gpt-oss-120b
195
      - name: openai/gpt-oss-20b
196
        alias: gpt-oss-20b
197
      - name: minimaxai/minimax-m2.5
198
        alias: minimax-m2.5
199
      - name: moonshotai/kimi-k2-instruct
200
        alias: kimi-k2-instruct
201
      - name: moonshotai/kimi-k2-instruct-0905
202
        alias: kimi-k2-instruct-0905
203
      - name: moonshotai/kimi-k2-thinking
204
        alias: kimi-k2-thinking
205
      - name: moonshotai/kimi-k2.5
206
        alias: "kimi-k2.5"
207
      - name: qwen/qwen3-next-80b-a3b-instruct
208
        alias: qwen3-next-80b-a3b-instruct
209
      - name: qwen/qwen3.5-397b-a17b
210
        alias: qwen3.5-397b-a17b
211
      - name: stepfun-ai/step-3.5-flash
212
        alias: step-3.5-flash
213
      - name: z-ai/glm4.7
214
        alias: glm-4.7
215
      - name: z-ai/glm5
216
        alias: glm-5
217
    headers:
218
      Content-Type: application/json
219
      Accept: "*/*"
220
      Accept-Encoding: "gzip, br"
221
      User-Agent: "opencode/1.2.25 ai-sdk/provider-utils/3.0.20 runtime/bun/1.3.10"
222

223
  # 本地 DS2API 服务
224
  - name: ds2api
225
    base-url: http://127.0.0.1:5001/v1
226
    api-key-entries:
227
      - api-key: xxx
228
    models:
229
      - name: deepseek-chat
230
        alias: ""
231
      - name: deepseek-reasoner
232
        alias: ""
233
      - name: deepseek-chat-search
234
        alias: ""
235
      - name: deepseek-reasoner-search
236
        alias: ""
237
    headers:
238
      Content-Type: application/json
239
      Accept: "*/*"
240
      Accept-Encoding: "gzip, br"
241
      User-Agent: "opencode/1.2.25 ai-sdk/provider-utils/3.0.20 runtime/bun/1.3.10"
242

243
  # 阿里云灵积平台
244
  - name: aliyun
245
    base-url: https://coding.dashscope.aliyuncs.com/v1
246
    api-key-entries:
247
      - api-key: sk-xxx
248
    models:
249
      - name: qwen3.5-plus
250
        alias: ""
251
      - name: qwen3-max-2026-01-23
252
        alias: ""
253
      - name: qwen3-coder-next
254
        alias: ""
255
      - name: qwen3-coder-plus
256
        alias: ""
257
      - name: glm-5
258
        alias: ""
259
      - name: glm-4.7
260
        alias: ""
261
      - name: kimi-k2.5
262
        alias: ""
263
      - name: MiniMax-M2.5
264
        alias: minimax-m2.5
265
    headers:
266
      Content-Type: application/json
267
      Accept: "*/*"
268
      Accept-Encoding: "gzip, br"
269
      User-Agent: "opencode/1.2.25 ai-sdk/provider-utils/3.0.20 runtime/bun/1.3.10"
270
    priority: 1
271

272
  # 月之暗面 Kimi
273
  - name: kimi
274
    base-url: https://api.kimi.com/coding/v1
275
    api-key-entries:
276
      - api-key: sk-xxx
277
    models:
278
      - name: kimi-k2.5
279
        alias: ""
280
      - name: kimi-k2-thinking
281
        alias: ""
282
      - name: kimi-k2
283
        alias: ""
284
      - name: kimi-for-coding
285
        alias: ""
286
    headers:
287
      Content-Type: application/json
288
      Accept: "*/*"
289
      Accept-Encoding: "gzip, br"
290
      User-Agent: "RooCode/3.51.1"
291
      HTTP-Referer: "https://github.com/RooVetGit/Roo-Cline"
292
      X-Title: "Roo Code"
293
    priority: 2
294

295
# OAuth 模型排除列表
296
oauth-excluded-models:
297
  antigravity:
298
    - tab_flash_lite_preview
299
    - tab_jump_flash_lite_preview
300
  kiro:
301
    - kiro-auto
302
    - kiro-claude-opus-4-6-agentic
303
    - kiro-claude-opus-4-5-agentic
304
    - kiro-claude-sonnet-4-5-agentic
305
    - kiro-claude-sonnet-4-agentic
306
    - kiro-claude-haiku-4-5-agentic
307
    - kiro-claude-sonnet-4-6-agentic
308
  gemini-cli:
309
    - gemini-2.5-flash-lite
310
    - gemini-2.5-flash
311
    - gemini-2.5-pro
312
    - gemini-3-pro-preview
313
  codex:
314
    - gpt-5
315
    - gpt-5-codex
316
    - gpt-5-codex-mini
317
    - gpt-5.1
318
    - gpt-5.1-codex
319
    - gpt-5.1-codex-mini
320
    - gpt-5.1-codex-max
321
    - gpt-5.2-codex
322
    - gpt-5.2
323

324
# Gemini API 密钥直连配置（用于本地转发）
325
gemini-api-key:
326
  - api-key: xxx
327
    base-url: http://localhost:8741
328
    headers:
329
      Content-Type: application/json
330
      Accept: "*/*"
331
      Accept-Encoding: "gzip, br"
332
      User-Agent: "opencode/1.2.25 ai-sdk/provider-utils/3.0.20 runtime/bun/1.3.10"
333
    models:
334
      - name: opus-4.6
335
        alias: claude-opus-4-6
336
      - name: sonnet-4.6
337
        alias: claude-sonnet-4-6
338
      - name: gemini-3-flash
339
        alias: gemini-3-flash-preview
340
      - name: gemini-3.1-pro-high
341
        alias: gemini-3.1-pro-preview
342
      - name: gemini-3.1-pro-high
343
        alias: gemini-3-pro-preview
344
      - name: gemini-3-pro-image
345
        alias: gemini-3-pro-image-preview
346
    excluded-models:
347
      - '*'
348

349
# Claude/Codex API 密钥配置（当前为空）
350
claude-api-key: []
351
proxy-url: ""
352
codex-api-key: []

配置详解#

接下来逐段解释这个配置文件里每个部分的作用。

基础服务配置#

1
port: 8317
2
tls:
3
  enable: false
4
  cert: /root/.acme.sh/xxx.com_ecc/xxx.com.cer
5
  key: /root/.acme.sh/xxx.com_ecc/xxx.com.key

port: 服务监听的端口，默认是 8317。如果你在同一台机器上跑多个实例，记得改端口避免冲突。

tls: HTTPS 配置。生产环境建议前面架一层 Nginx 或 Caddy 做 TLS 终结，后端保持 HTTP 就行。直接让 CLIProxyAPI 处理 TLS 也可以，但证书路径要写对。

注意这里没有 host 字段，默认会监听所有网卡。如果是本地测试，建议显式写成 host: 127.0.0.1 防止外部访问。

远程管理面板#

1
remote-management:
2
  allow-remote: true
3
  secret-key: xxx
4
  disable-control-panel: false
5
  panel-github-repository: https://github.com/kongkongyo/Cli-Proxy-API-Management-Center

CLIProxyAPI 内置了一个 Web 管理面板，用来查看 OAuth 登录状态、模型列表、用量统计等。

allow-remote: 是否允许远程访问管理面板。生产环境建议设为 false，只让本机访问。
secret-key: 登录管理面板的密码，强烈建议用环境变量注入，别直接写在配置文件里。
panel-github-repository: 自定义管理面板的前端仓库地址，可以用社区开发的面板替代默认界面。

根据官方文档，管理面板默认走 http://localhost:8317 的 /panel 路径。

API 密钥管理#

1
api-keys:
2
  - sk-xxx-key-1
3
  - sk-xxx-key-2
4
  ...

这是客户端调用 API 时需要携带的密钥列表。CLIProxyAPI 支持多密钥，可以实现简单的权限隔离：

给不同团队分配不同的 key
给 CI/CD 流水线单独一个 key，方便监控用量
某个 key 泄露了，直接从列表里删掉就行

安全建议：用环境变量注入，比如 - "${API_KEY_DEV}"，避免密钥硬编码到配置文件里提交到 Git。

调试与日志#

1
debug: true
2
logging-to-file: true
3
logs-max-total-size-mb: 10
4
usage-statistics-enabled: true

debug: 开启后会输出详细的请求/响应日志，排查问题时很有用，但生产环境建议关掉，否则日志量太大。
logging-to-file: 日志写入文件，默认路径是 ~/.cli-proxy-api/proxy.log。
logs-max-total-size-mb: 日志文件总大小限制，超过会自动清理。
usage-statistics-enabled: 开启用量统计，可以在管理面板看到每个 API key 的调用次数。

请求重试与配额处理#

1
request-retry: 3
2
max-retry-interval: 20
3
quota-exceeded:
4
  switch-project: true
5
  switch-preview-model: true

这套配置是 CLIProxyAPI 的核心优势之一——自动故障转移。

request-retry: 请求失败后的重试次数。设为 3 表示最多重试 3 次。
max-retry-interval: 重试间隔上限（秒），防止疯狂重试被服务商风控。
quota-exceeded: 配额超限后的处理策略：
- switch-project: 自动切换到同一账号下的其他项目（如果有的话）
- switch-preview-model: 自动降级到 preview 版本的模型

实际使用中，当 Google Antigravity 或 Claude 的额度用完时，这个机制能自动找备用渠道，不用人工介入。

负载均衡策略#

1
routing:
2
  strategy: round-robin

目前支持两种策略：

round-robin: 轮询，请求均匀分布到多个账号
fill-first: 优先填满第一个账号的额度，再用第二个

多账号场景下，round-robin 适合均匀分配压力；fill-first 适合把主账号额度用光再切备用账号。

流式响应保活#

1
streaming:
2
  keepalive-seconds: 15
3
  bootstrap-retries: 2

流式响应（SSE）容易遇到网关超时的问题，特别是 Cloudflare 这类 CDN 默认 100 秒无数据就断连。

keepalive-seconds: 每隔多少秒发送一个空行保活，防止连接被切断。
bootstrap-retries: 首字节返回前的重试次数，避免模型加载慢导致客户端超时。

如果你的服务架在 Cloudflare 后面，这个配置必须开，否则长回复会中断。

OAuth 模型别名#

1
oauth-model-alias:
2
  antigravity:
3
    - name: gemini-3-pro-high
4
      alias: gemini-3-pro-preview
5
  ...

这是模型名称的映射表。上游服务商（如 Google Antigravity）返回的模型名可能很长，客户端用起来不方便。通过别名可以简化：

比如把 gemini-3-pro-high 映射成 gemini-3-pro-preview，客户端调用时直接用短名字就行。

支持的 OAuth 渠道包括：

antigravity: Google Antigravity（Gemini CLI）
github-copilot: GitHub Copilot 内置的 Claude 模型
kiro: Kiro IDE 的模型
qwen: 通义千问
claude: Anthropic Claude Code
codex: OpenAI Codex
gemini-cli: Gemini CLI

OpenAI 兼容提供商#

1
openai-compatibility:
2
  - name: openrouter
3
    base-url: https://openrouter.ai/api/v1
4
    api-key-entries:
5
      - api-key: sk-or-v1-xxx
6
        proxy-url: socks5://127.0.0.1:40000

除了 OAuth 渠道，CLIProxyAPI 还能对接标准的 OpenAI 兼容 API。这节的配置比较灵活：

name: 提供商标识，随便起，客户端调用时要用
base-url: 上游 API 的基础地址
api-key-entries: 支持多个 API key，每个可以配独立的代理出口
models: 模型映射表，可以把上游模型名映射成更友好的别名
headers: 自定义请求头，有些平台需要特定的 User-Agent 或 Referer
priority: 优先级，数字越小越优先。当多个渠道有同名模型时，按优先级选择

模型排除列表#

1
oauth-excluded-models:
2
  gemini-cli:
3
    - gemini-2.5-flash
4
    - gemini-2.5-pro

有些模型你不想暴露给客户端，可以用排除列表隐藏。支持通配符匹配：

精确匹配：gemini-2.5-pro
前缀匹配：gemini-2.5-*
后缀匹配：*-preview
子串匹配：*flash*

Gemini API 直连配置#

1
gemini-api-key:
2
  - api-key: xxx
3
    base-url: http://localhost:8741
4
    models:
5
      - name: opus-4.6
6
        alias: claude-opus-4-6

这部分是 CLIProxyAPI 的高级用法——本地转发。你可以把另一个 Gemini API 转发服务（比如自己搭的 ds2api）作为上游，通过 CLIProxyAPI 统一暴露。

base-url: 本地转发服务的地址
excluded-models: 设为 '*' 表示默认隐藏所有模型，只有显式声明的才暴露

实际应用示例#

场景一：个人开发环境#

最简单的用法，只需要配置一个 OAuth 渠道：

1
port: 8317
2
auth-dir: ~/.cli-proxy-api
3
api-keys:
4
  - "${MY_API_KEY}"
5

6
oauth-model-alias:
7
  antigravity:
8
    - name: gemini-2.5-pro
9
      alias: g2.5p

然后登录 Antigravity：

1
cliproxyapi --login

会自动打开浏览器完成 OAuth 授权，token 保存在 ~/.cli-proxy-api/ 目录。

启动服务：

1
cliproxyapi --config config.yaml

客户端配置（以 Roo Code 为例）：

1
base_url: http://localhost:8317/v1
2
api_key: sk-your-key
3
model: g2.5p

场景二：多账号负载均衡#

如果你有多个 Google 账号，每个都有 Antigravity 订阅：

1
# 登录第一个账号
2
cliproxyapi --login --auth-dir ~/.cli-proxy-api/account1
3

4
# 登录第二个账号
5
cliproxyapi --login --auth-dir ~/.cli-proxy-api/account2

配置文件：

1
auth-dir: ~/.cli-proxy-api
2
routing:
3
  strategy: round-robin

CLIProxyAPI 会自动轮询多个账号，某个账号额度用完时会自动切换。

场景三：生产环境部署#

生产环境建议用 systemd 管理服务：

1
[Unit]
2
Description=CLIProxyAPI Service
3
After=network.target
4

5
[Service]
6
Type=simple
7
User=cliproxy
8
WorkingDirectory=/opt/cliproxyapi
9
ExecStart=/opt/cliproxyapi/cliproxyapi --config /opt/cliproxyapi/config.yaml
10
Restart=on-failure
11
RestartSec=5
12
Environment="API_KEY_DEV=sk-xxx"
13
Environment="OPENROUTER_KEY=sk-or-v1-xxx"
14

15
[Install]
16
WantedBy=multi-user.target

注意环境变量的设置方式，避免密钥硬编码。

场景四：配合 Nginx 反向代理#

如果要用 HTTPS，可以用 Nginx 做反向代理：

1
server {
2
    listen 443 ssl http2;
3
    server_name api.example.com;
4

5
    ssl_certificate /path/to/cert.pem;
6
    ssl_certificate_key /path/to/key.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 86400;
16
    }
17
}

proxy_read_timeout 要设长一点，因为 AI 模型响应可能很慢。

总结#

CLIProxyAPI 的配置自由度很高，从个人本地测试到团队多账号管理都能应付。核心要记住的几点：

安全第一：API key 用环境变量注入，管理面板限制访问范围
别名简化：给模型起短名字，客户端配置更清爽
自动故障转移：合理设置重试和配额超限策略，减少人工干预
日志监控：开启用量统计，方便排查问题和分摊费用
流式保活：如果架在 CDN 后面，记得开保活防止断连

这套配置在我这边已经稳定运行了几个月，处理过单日上万次的请求。只要上游 OAuth 账号的额度没用完，基本不用管。

如果你有更复杂的场景（比如按用户限流、动态模型路由），可以看看 CLIProxyAPI 的 SDK 文档，支持用 Go 写自定义中间件。

参考链接：