先说问题:订阅买了,却只能在官方 CLI 里用
现在主流 AI 厂商都在推 CLI 形态的编程工具:Google 的 Gemini CLI、OpenAI 的 ChatGPT Codex、Anthropic 的 Claude Code,还有 Antigravity、Grok Build、Kimi Code 这些。配套的订阅(比如 Google AI Pro、ChatGPT Plus/Pro、Claude 订阅)额度都不低,但有个共同的尴尬:这些额度被锁死在各自的官方 CLI 里。
你想在自己顺手的编辑器插件里用,不行;想写个脚本批量跑任务,不行;想在第三方聊天客户端里调用,还是不行——因为厂商根本没给你一个标准 API 入口,订阅和 API 是两套计费体系,API 那套要另外按量付费。
CLIProxyAPI 解决的就是这层隔阂:它把你已经登录的 CLI 账号接进来,对外统一暴露成 OpenAI / Gemini / Claude / Codex 兼容的标准 API。一句话定位:它是一个「订阅账号 → 标准 API」的转换层,让订阅额度第一次能被任何兼容客户端调用。
本篇主线:讲清它是什么、解决什么问题 → Docker Compose 部署 → config.yaml 关键配置 → OAuth 登录账号与多账号轮换 → 客户端接入实测 → 管理 API 与用量统计 → 和 LiteLLM 的分工 → 风险与合规提醒。
项目地址:https://github.com/router-for-me/CLIProxyAPI ,官方文档:https://help.router-for.me/cn/
CLIProxyAPI 是什么
CLIProxyAPI 是一个开源的代理服务(Go 编写,MIT 协议),工作方式分两步:
- 上游侧:通过各厂商官方的 OAuth 登录流程,把你的 CLI 账号授权给它,登录凭证以文件形式保存在本地的凭证目录里。支持的账号来源包括 Gemini CLI、Antigravity、ChatGPT Codex、Claude Code、Grok Build、Kimi 等。
- 下游侧:对外提供 OpenAI(含 Responses)、Gemini、Claude、Codex、Grok 五种兼容格式的 API 端点,支持流式与非流式响应、Function Calling / 工具调用、多模态(文本+图片)输入。
也就是说,客户端只管按 OpenAI 格式发请求,CLIProxyAPI 在中间做协议翻译,再拿着你的订阅账号凭证去调上游模型,最后把结果转回客户端要的格式。多个同类账号还可以组队:同一厂商登录多个账号后,请求会在账号之间轮换分发,做负载均衡和额度摊薄。
它解决什么问题
把场景列一下就清楚了:
- 订阅额度用满:订阅是包月制,额度不用过期作废;转成 API 后,编辑器插件、脚本、自动化任务都能消耗这些额度,而不是只在官方 CLI 里慢慢敲。
- 客户端自由:任何支持 OpenAI 兼容接口的工具——编程助手、聊天客户端、翻译工具、工作流平台——填上 CLIProxyAPI 的地址和 Key 就能用上订阅背后的模型。
- 多账号聚合:手里有多个账号时,一个一个切换登录很痛苦;统一托管后对外只有一个入口,轮换、故障转移都由服务侧处理。
- 协议互转:客户端只会说 OpenAI 格式、模型只提供 Claude 格式这类错位,也能在这一层抹平。
反过来,它不适合的场景也要说清:你需要的是厂商官方 API 的 SLA 保障、要开发票对公结算、要给团队几十号人发 Key——那应该走官方 API 或 LiteLLM 这类 API Key 网关,而不是个人订阅转换。
Docker Compose 部署
官方提供 Docker 镜像 eceasy/cli-proxy-api,一条 Compose 文件就能跑起来。先建目录、准备两个挂载点:配置文件 config.yaml 和凭证目录 auths/。
services: cli-proxy-api: image: eceasy/cli-proxy-api:latest container_name: cli-proxy-api restart: unless-stopped ports: - "8317:8317" volumes: - ./config.yaml:/CLIProxyAPI/config.yaml - ./auths:/root/.cli-proxy-api目录结构长这样:
cliproxyapi/├── docker-compose.yml├── config.yaml # 主配置文件└── auths/ # OAuth 登录凭证文件,一账号一份启动与看日志:
docker compose up -ddocker compose logs -f cli-proxy-api日志里看到监听 8317 端口、加载了配置文件,就说明服务本身起来了。此时还没有任何上游账号,接口调不通是正常的——先把配置写对,再去登录账号。
config.yaml 关键项
最小可用配置如下,逐项说明在后面:
# 监听地址与端口;host 留空表示监听所有网卡,只在本机用可写 127.0.0.1host: ""port: 8317
# OAuth 凭证文件存放目录(容器内路径,与 Compose 的挂载对应)auth-dir: "/root/.cli-proxy-api"
# 客户端访问这个服务时用的 Key,自己随便设强口令,可配多个分发给不同客户端# 注意:这是「进门钥匙」,不是任何上游厂商的 API Keyapi-keys: - "sk-my-client-key-please-change"
# 远程管理开关:默认关闭远程管理,只允许本机访问管理接口remote-management: allow-remote: false # 管理密钥,管理 API 和管理面板都要用它鉴权,务必设强口令 secret-key: "my-management-secret-please-change"
# 多账号调度策略:round-robin 轮询(默认),fill-first 填满一个再用下一个request-retry: 3routing: strategy: "round-robin"几个容易踩的点:
api-keys是给你的客户端用的,和上游账号没有任何关系。客户端请求时把它当成 OpenAI 的 API Key 填进去即可。auth-dir目录里的文件就是账号本体,凭证文件泄露等于账号直接被人拿走用,目录权限和备份都要按密钥级别对待。remote-management.allow-remote默认false时,管理接口只接受本机请求;改成true之前先想清楚暴露面,见文末风险一节。
账号登录:走一遍 OAuth
服务跑起来只是空壳,真正的燃料是账号。登录通过给主程序传 --login 类参数完成,每种账号一个入口,常用的有:
# 在容器里执行登录(以 Gemini 为例,其余同理换参数)docker compose exec cli-proxy-api ./CLIProxyAPI --login # Gemini CLIdocker compose exec cli-proxy-api ./CLIProxyAPI --codex-login # ChatGPT Codexdocker compose exec cli-proxy-api ./CLIProxyAPI --claude-login # Claude Codedocker compose exec cli-proxy-api ./CLIProxyAPI --antigravity-login # Antigravity流程都一样:命令输出一个授权链接 → 在浏览器里打开、用你的订阅账号登录并授权 → 回调完成后,凭证自动写成一个 JSON 文件落进 auths/ 目录。无图形界面的服务器上,就把链接复制到本地浏览器打开,按提示完成回调即可。
登录成功后可以看一眼目录确认:
ls -l auths/# 每多登录一个账号,这里就多一份凭证文件多账号轮换不需要额外配置:同一厂商多登录几个账号,请求会自动按 routing.strategy 的策略(默认轮询)在账号间分发。某个账号额度耗尽或报错,服务会重试并切换到其他可用账号——这也是它比手动切号省心的地方。配多个账号时注意,不要把来路不明的账号凭证往里塞,来历不明的凭证文件同样可能反过来盗走你的服务。
客户端接入
账号就位后,先用 curl 验证 OpenAI 兼容端点:
# 列出当前可用模型curl http://127.0.0.1:8317/v1/models \ -H "Authorization: Bearer sk-my-client-key-please-change"
# 发一条对话请求(model 换成上一步列表里实际有的)curl http://127.0.0.1:8317/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-my-client-key-please-change" \ -d '{ "model": "gemini-2.5-pro", "messages": [{"role": "user", "content": "用一句话解释什么是负载均衡"}], "stream": false }'能返回正常补全内容,整条链路就通了。之后任何客户端接入都是同一套填法:
- Base URL:
http://你的服务器:8317/v1 - API Key:config.yaml 里
api-keys配的任意一个 - 模型名:以
/v1/models返回的列表为准
比如给编程工具当后端——把工具的模型供应商指向这个地址,它就会拿你的订阅额度干活;命令行 AI 助手类工具同理,细节可对照本系列的《命令行里的 AI 助手》。除了 OpenAI 格式,它还提供 Gemini 格式(/v1beta/...)与 Claude 格式(/v1/messages)端点,原生吃这两种协议的客户端不用绕 OpenAI 格式也能直连。
管理 API 与用量统计
CLIProxyAPI 带一套管理 API(路径前缀 /v0/management/),用 secret-key 鉴权,能远程做这些事:查看与增删客户端 API Key、列出已登录的凭证文件、开关远程管理、热更新部分配置,不用每次都去改文件重启。官方还提供配套的 Web 管理面板,部署后按文档启用即可在浏览器里操作。
两个使用要点:
- 管理请求要带密钥请求头,本机调用也一样,别图省事把
secret-key留空——留空等于管理接口裸奔。 - 用量统计:较新的版本已经不再内置用量统计功能,官方推荐外接独立统计服务(如 CPA Usage Keeper、CPA-Manager-Plus 这类社区项目),它们通过管理 API 拉取数据,落库到 SQLite 再出仪表盘。想看每个账号烧了多少额度、哪个模型调用最多,装其中一个即可,部署细节见官方文档的 Usage Statistics 章节。
与 LiteLLM 的分工
本系列上一篇 LiteLLM 和这篇经常被放在一起比较,其实两者聚合的东西根本不同,最好配合而不是二选一:
| 对比项 | CLIProxyAPI | LiteLLM |
|---|---|---|
| 聚合对象 | AI 产品的订阅账号(OAuth 凭证) | 各厂商的 API Key(官方计费通道) |
| 上游来源 | Gemini CLI、Codex、Claude Code 等 CLI 账号 | OpenAI、Anthropic、Gemini 等 100+ 厂商 API |
| 计费方式 | 吃订阅的包月额度,不另计费 | 按官方 API 用量计费,网关只做转发 |
| 多账号/多 Key | 多账号轮询、故障切换 | 多 Key 负载均衡、预算与限流 |
| 典型角色 | 把「只能 CLI 里用」的额度解放出来 | 团队统一网关、成本管控、协议标准化 |
| 合规属性 | 灰色地带,取决于各厂商订阅条款 | 官方通道,正规用法 |
分工结论:个人场景用 CLIProxyAPI 把已有订阅额度榨干,正规 API 需求走 LiteLLM 统一管理;两者甚至可以串联——CLIProxyAPI 作为 LiteLLM 的一个上游渠道接进去。选型思路的完整版在系列第一篇《AI 工具全景图与选型指南》里。
风险与合规提醒
这一节不是套话,是用之前必须想清楚的三件事:
WARNING账号条款风险:把订阅账号转成 API 调用,并不在多数厂商订阅条款预期的使用方式之内。一旦被厂商判定违规,处置是封号而不是提醒,订阅费和账号里的其他权益可能一起没了。用不用、用哪个账号用,自己权衡,别拿大号主力账号去试水。
- 凭证保管:
auths/里的 JSON 凭证等价于登录态,任何拿到文件的人都能以你的账号调用。不要进 Git 仓库、不要随手发人、备份要加密。 - 网络暴露:8317 端口不要直接暴露在公网。哪怕设了
api-keys,暴露面也意味着别人可以持续爆破和白嫖你的订阅额度。远程使用优先走内网穿透到私有网络、或在前面套一层带鉴权的反向代理,只给自己的设备放行。 - 管理面隔离:
remote-management.allow-remote能不开就不开;必须开时,secret-key用长随机串,并且不要和管理端口一起裸奔公网。
常见问题与排障
1. 容器起来了,但 /v1/models 返回空列表
还没登录任何账号,或凭证没被加载。先 ls auths/ 确认凭证文件存在,再看启动日志里有没有加载凭证的记录;文件不在就重新走一遍登录流程。
2. 客户端调用返回 401
两种 401 别混淆:客户端 → CLIProxyAPI 这一段的 401,是 api-keys 没填对(注意 Bearer 前缀和空格);CLIProxyAPI → 上游的鉴权失败,是凭证过期或被吊销,回容器重新执行一次对应账号的登录命令刷新凭证。
3. 登录时浏览器回调失败、流程卡住
服务器无图形界面时,授权链接要拿到本地浏览器打开,并保证回调能回到服务所在机器。实在走不通回调,就换一台能直连的机器先登录、把生成的凭证文件拷进服务器的 auths/ 再重启服务,效果一样。
4. 请求频繁返回 429 或额度错误 单个账号的订阅额度到顶了。要么等额度窗口恢复,要么多登录几个账号摊薄——轮询策略下请求会自动分散。注意这解决的是「额度不够」而不是「绕过额度」,总额度还是那些。
5. 某个模型调不通,其他模型正常
多半是账号来源不对:每个模型只能由对应厂商的账号提供,比如 Claude 系列要 Claude Code 账号、GPT 系列要 Codex 账号。先用 /v1/models 对照模型与账号的对应关系,再看日志里实际上游报错。
6. 改了 config.yaml 不生效
确认 Compose 挂载的是你改的那份文件(路径写错是最常见原因),然后 docker compose restart 重启容器;管理类配置有些支持热更新,但端口、监听地址这类必须重启。
小结
- CLIProxyAPI 的本质是协议与额度的转换层:上游接 CLI 订阅账号的 OAuth 凭证,下游吐 OpenAI / Gemini / Claude 兼容 API。
- 部署就三步:Compose 起服务 → 写对 config.yaml(端口、auth-dir、api-keys、管理密钥)→ 逐个账号走 OAuth 登录。
- 多账号轮询是它的核心红利:订阅额度从「一个 CLI 里慢慢用」变成「一个标准入口随便接客户端用」。
- 和 LiteLLM 不冲突:一个聚合订阅账号、一个聚合 API Key,按场景分工,甚至可以串联。
- 最后再强调一次:凭证当密钥保管、端口别裸奔公网、账号条款风险自己掂量——工具是好工具,用法决定它是省钱利器还是封号导火索。