CLIProxyAPI 是什么,能接哪些账号
说白了,CLIProxyAPI 在你本机跑一个 HTTP 服务,默认监听 8317 端口:对外提供 OpenAI(含 Responses)、Anthropic、Gemini、Codex 几套协议的兼容接口,对内拿你已有的 CLI 账号凭据去调上游模型。任何与这几套协议兼容的客户端或 SDK,都能把 CLIProxyAPI 当成普通 API 来调用。
支持的账号渠道分成两类。第一类是走 OAuth 登录的订阅账号:
- Codex(OpenAI):用 ChatGPT 账号登录即可,官方文档的说法是任意订阅都行,包含免费账户;
- Claude Code(Anthropic):走 Anthropic OAuth 流程;
- Antigravity(Google):中文文档里也写作「反重力」,对应 Gemini 3.x 系列模型;
- Grok Build(xAI):登录后作为 xai 渠道使用,上游默认指向 https://api.x.ai/v1;
第二类不需要登录,直接填 API Key 就行,字段分别是 gemini-api-key、codex-api-key、claude-api-key、xai-api-key、vertex-api-key,以及专门用来接任意 OpenAI 兼容上游的 openai-compatibility,官方文档拿 OpenRouter 举的例子。 项目在 GitHub 上由 router-for-me 维护,目前已经收获约 5.2 万 Star,最新版本 v7.3.7 发布于 9 月 17 日。更新频率很高,一个月能发好几个小版本,下面的字段名动手前建议再核一遍。
安装部署:各平台方式与官方入口
装的方式按系统挑一种就够:
| | |
|---|
| | brew install cliproxyapi,再用 brew services start cliproxyapi 启动 |
| | curl -fsSL https://raw.githubusercontent.com/router-for-me/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash |
| | yay -S cli-proxy-api-bin(或 paru),之后用 systemctl --user start cli-proxy-api 管理 |
| | 到项目 Release 页下载对应平台压缩包,解压后直接运行 |
| | docker run -p 8317:8317 -v /path/to/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/auth-dir:/root/.cli-proxy-api -v /path/to/plugins:/CLIProxyAPI/plugins eceasy/cli-proxy-api:latest |
| | 克隆仓库后执行 go build -o cli-proxy-api ./cmd/server |
macOS 用 Homebrew 有个容易踩的点:以 brew services 方式运行时,程序读的是 $(brew --prefix)/etc/cliproxyapi.conf,不是大家习惯的 ~/.cli-proxy-api/config.yaml。想沿用后者,得在启动服务之前先把软链接指向一个已经存在的文件。悬空软链会让服务一起来就退出。官方文档给了完整的处理脚本,动手前照着走。
Windows 直接下预编译包解压运行就行,或者用桌面客户端省事。Docker 部署记得把插件目录挂到 /CLIProxyAPI/plugins,不然从插件商店装的插件在容器重启之后就没了。
登录授权:四类 OAuth 命令与回调端口
CLIProxyAPI 跑起来不等于有模型可用。先做登录授权,凭证会以 JSON 文件的形式落到 auth-dir 目录,默认是 ~/.cli-proxy-api。四类账号的登录命令和各自的本地回调端口如下:
| | |
|---|
| ./cli-proxy-api --codex-login | |
| ./cli-proxy-api --claude-login | |
| ./cli-proxy-api --antigravity-login | |
| ./cli-proxy-api --xai-login | |
加上 --no-browser 会打印登录地址而不自动拉起浏览器,跑在服务器上或者桌面环境缺失时用这个参数。xAI 那条还支持用 --oauth-callback-port 换回调端口。如果命令行要求手动粘贴回调令牌,只粘令牌本身,别把整段回调 URL 贴进去,这是官方文档专门提醒过的一个坑。
Gemini Web 是另一条路,针对的是 NanoBanana 那类只有网页端才有的图像模型。流程是登录 gemini.google.com,在开发者工具的 Network 面板里筛 ListAccounts,复制请求头里的完整 Cookie,然后执行 cli-proxy-api --gemini-web-auth 粘贴进去。macOS 上如果整串 Cookie 认证失败,可以改用手动填 __Secure-1PSID 和 __Secure-1PSIDTS。这条路本质上是把浏览器会话交给程序使用,敏感程度比 OAuth 高,后面风险那一节会展开说。
多个账号丢进同一个 auth-dir 就能做轮询。CLIProxyAPI 会监听配置文件和 auth-dir 目录的变动自动重载,运行中新增或移除 Codex、Claude Code 的令牌 JSON 不需要重启服务。
Docker 里做 OAuth 会绕一点:在容器里跑登录命令后,程序会打印一段 SSH 隧道命令,需要复制到本地终端执行,并且把端口号换成你 VPS 真实的 SSH 端口,然后保持那个窗口别关,等回调走完。
config.yaml 配置项与接口端点对照
配置文件默认读程序根目录的 config.yaml,也能用 --config 指定别的路径。它支持热重载,改完即生效。实际会动到的项大概是这些:
| | | |
|---|
| | | 绑定地址。留空同时监听 IPv4/IPv6,填 127.0.0.1 则只允许本机访问 |
| | | |
| | | |
| | | |
| | | 全局出站代理,支持 socks5/http/https;单条凭据可以覆盖为 direct 绕过 |
| | | 遇到 403/408/500/502/503/504 时的重试次数 |
| | | |
| | | |
| | | 记录每个请求与响应。单条日志可能很大,磁盘紧张别开 |
| | | |
remote-management.allow-remote | | | |
remote-management.secret-key | | | 管理密钥。留空则所有 /v0/management 路由返回 404 |
quota-exceeded.switch-project | | | |
| | | 凭据选择策略,可选 round-robin 或 fill-first;示例配置里还列出了 weighted-round-robin |
凭据层面有三个字段值得留意。priority 默认 0,数值大的优先被选中;prefix 让模型按 prefix/model 的形式调用,用来区分同一模型的不同上游;excluded-models 支持 * 通配符,比如 *-preview、*flash*。要给模型改名,用 models 下的 name(上游模型名)配 alias(客户端实际看到的模型名)。
OAuth 渠道另有一套 oauth-model-alias 和 oauth-excluded-models,支持的渠道是 vertex、aistudio、antigravity、claude、codex、kimi、xai。要注意别名机制只对 OAuth 渠道生效,填 API Key 的那几类配置不吃这一套。 CLIProxyAPI 对外提供的接口按协议分族:
| | |
|---|
| | |
| | |
| | Claude Code 及 Claude 兼容客户端 |
| | Gemini 原生协议族,另有 /v1beta/interactions |
| | |
| /v1/images/generations、/v1/images/edits | |
| /v1/videos 及 /v1/videos/generations 等 | |
| | WebSocket 传输通道,AI Studio Build 那套走这里 |
| | |
| | |
客户端接入:6 类工具的 base_url 填写
接入最容易错的是 base_url 到底带不带 /v1。这事没有统一规律,得看客户端走哪套协议:OpenAI 兼容的要跟 /v1,Anthropic 兼容的只写到端口。下面这张表逐条对着官方文档核过:
| | |
|---|
| | ANTHROPIC_BASE_URL 填 http://127.0.0.1:8317(不带 /v1),ANTHROPIC_AUTH_TOKEN 填你的 api-key |
| | base_url = "http://127.0.0.1:8317/v1",wire_api = "responses",另外要指定 model_provider |
| | models_base_url = "http://127.0.0.1:8317/v1",models_list_url 指向同域的 /v1/models |
| ~/.config/opencode/opencode.json | provider.openai.options 下 baseURL 填 http://127.0.0.1:8317/v1 |
| | provider 为 openai 时 base_url 跟 /v1;provider 为 anthropic 时只填到端口 |
| | 先执行 pi install npm:@router-for-me/pi-cliproxyapi-provider,再在 PI 里填 Base URL 与 API Key |
规律一眼能看出来:provider 或 wire_api 标 openai/responses 的,base_url 后面跟 /v1;标 anthropic 的,只填到端口。Factory Droid 那份配置里两种写法同时出现,是这条规则最直白的示例。
还有个概念必须先分清:客户端里填的 API Key 是 config.yaml 里 api-keys 那几项,而 claude-api-key、codex-api-key、gemini-api-key 那些是代理去访问上游时用的密钥。前者是别人访问你的代理要出示的凭证,后者是你的代理访问上游要出示的凭证。这两个混了,是新手最常见的配置错误。典型症状是客户端一直报鉴权失败,可上游密钥明明是对的。
凭证安全、许可与额度规则
CLIProxyAPI 本身是 MIT 许可,软件免费,不需要付费也不需要绑卡。它不产生费用,账都记在上游账号上:你用的是订阅额度或 API 余额,代理只负责转发。额度耗尽时的行为由 quota-exceeded 控制,switch-project 为 true 时会自动换到下一个账号继续请求,switch-preview-model 会在预览模型受限时切到别的模型,antigravity-credits 则负责在免费额度全部耗尽后拿带积分的凭据做最后兜底。routing.strategy 决定凭据的选择顺序。
有个版本切换点要记住:从 v6.10.0 起,CLIProxyAPI 本体和官方管理面板都不再预置数据统计功能,需要用量看板就得另配独立的统计服务。
这类工具的风险几乎全部集中在凭证上,动手前把这四条过一遍:
- 别把 8317 端口直接开到公网。remote-management.allow-remote 默认是 false,只允许本机访问管理接口,这是安全的默认值,别为了图方便改掉。另外有个隐蔽的坑:设置了 MANAGEMENT_PASSWORD 这个环境变量会强制启用远程管理,即使 allow-remote 还是 false,官方文档明确写了这一点。
- 管理密钥等于账号控制权。管理 API 里有个 /api-call 端点,能用已配置的凭据发起任意出站请求,官方文档要求严格限制管理密钥的访问权限。还有个同源问题:部署在同一个 origin 下时,插件资源页能读到管理中心的 localStorage,也就是能拿到管理密钥——装带资源页的插件,等于信任它的前端代码。
- auth-dir 里的 JSON 文件就是账号凭据本身。泄露等同于账号被盗。别把 auth-dir 放进同步盘、公开仓库或者随手分享的压缩包里。官方教程里用 Git 仓库做持久化的方案,前提是仓库必须设为私有。用 Gemini Web 那条 Cookie 路线的话同理,Cookie 属于高强度敏感信息。
- 订阅凭据用在非官方客户端上,账号侧是存在风险的。各家服务条款对账号凭据的使用范围都有约定,而项目本身提供了 cloak(请求伪装)和 codex.identity-confuse 这类配置,官方在注释里直接写明,这些是为担心「请求标识被当作封禁依据」的用户准备的。这层设计存在本身就说明上游厂商对客户端身份有校验。稳妥的用法是只在本机、只用自己的账号、按个人正常用量使用,不要对外提供 API 服务,也不要把别人的账号拿来做池化。
常见报错与排错方法
大部分问题出在端口、密钥和目录这三处。按现象对照着查:
| | |
|---|
| | 确认程序在运行、8317 没被别的进程占用;Docker 部署要确认端口已经做了映射 |
| 请求头里带的 Key 不在 api-keys 列表里,或者填成了上游密钥 | 核对 config.yaml 的 api-keys,分清「客户端 Key」和「上游密钥」 |
| 配了 disable-image-generation: true,图像端点被整体关闭 | 改回 false;填 "chat" 则只停用非图像端点上的注入,图像端点保留 |
| 对应账号额度耗尽或触发限流,程序会把该模型临时停用,再次触发还会继续延长停用时间 | 确认 quota-exceeded.switch-project 开着,多配几个账号做轮询,或者等冷却结束 |
偶发 403/408/500/502/503/504 | | 由 request-retry 自动重试,默认 3 次,网络不稳可以调大 |
| disable-control-panel 被设成了 true,服务器跳过了面板下载 | 改回 false 后重启或热重载;也可以用 MANAGEMENT_STATIC_PATH 指定面板存放目录 |
| allow-remote 默认为 false;或 secret-key 留空导致管理路由压根没注册 | 先设 secret-key,确实需要远程访问再打开 allow-remote |
| | 去程序目录的 logs 文件夹找,Docker 里用 tail -f 跟 |
| | 启动时补上插件目录到 /CLIProxyAPI/plugins 的挂载 |
| 令牌文件没落在 auth-dir 目录里,或者路径写错了 | 确认文件确实在 auth-dir 下;程序监听该目录,正常会自动重载 |
CLIProxyAPI 常见问题解答
Q:CLIProxyAPI 免费吗,需要付费或者绑卡吗?
A:CLIProxyAPI 本身是 MIT 许可、完全免费,既不收费也不绑卡。它不产生任何费用,实际消耗的是你上游账号的订阅额度或 API 余额。
Q:官方下载入口在哪,有没有桌面客户端?
A:源码、安装包和版本发布都在 github.com/router-for-me/CLIProxyAPI,用户手册在 help.router-for.me。官方桌面客户端是 EasyCLIProxyAPI,把登录、密钥复制和智能体配置都做成了图形界面,不习惯命令行可以直接用它。
Q:支持哪些客户端和协议?
A:对外提供 OpenAI(含 Responses)、Anthropic Messages、Gemini 原生几套协议,另有图像、视频和 WebSocket 端点。Claude Code、Codex、Grok Build、OpenCode、Factory Droid、PI Agent 这几类客户端官方文档都给了现成配置。
Q:客户端一直报鉴权失败怎么办?
A:先分清用的是哪把钥匙。客户端里要填的是 api-keys 里的值,不是 claude-api-key 那些上游密钥。然后确认 Key 已经写进 config.yaml 并保存。配置文件是热重载的,改完即生效,不用重启。
Q:需要企业资质或者实名认证吗?
A:CLIProxyAPI 不需要,它就是个跑在你机器上的开源本地代理,没有注册环节也没有资质门槛。但如果走 API Key 渠道接上游,资质要求取决于上游那家厂商,与这个项目无关。
Q:CLIProxyAPI 自己不设额度,上限是多少?
A:CLIProxyAPI 不设额度,上限完全由上游账号的订阅或余额决定,比如 Codex 看 ChatGPT 订阅、Gemini 看账号档位。想撑住更大用量,靠的是在 auth-dir 里放多个账号做轮询,而不是调项目参数。
Q:遇到问题去哪里找官方支持?
A:官方仓库的 Issues 区是主渠道,用户手册也覆盖了绝大多数配置问题和报错场景。仓库里还留了中文社群入口,可以自己去看一眼当期有效的联系方式。
Q:把账号凭据交给这个程序安全吗?
A:CLIProxyAPI 是本地运行的,凭据也只落在本机 auth-dir 目录,不会上传到作者的服务器。真正的风险在你的用法上:把端口开到公网、把 auth-dir 放进公开仓库、或者装了来路不明的带界面插件,这三件事都会让凭据暴露。
Q:只在本机自用,怎么配最省事?
A:装官方桌面客户端,OAuth 登录点几下就行,模型和密钥都由界面管。要在服务器上跑,优先用 Docker 加一个带 TLS 的反向代理,管理密钥设复杂一点,然后按需只开需要的渠道。
配置项和额度规则会随版本更新调整,动手前在 config.yaml 的注释或控制台里确认一下当期写法就行。CLIProxyAPI 这类工具的价值,是把散落在好几个订阅里的额度收拢成一个统一接口;把上面这几张表对上,剩下的无非是按自己的用量习惯去调轮询和重试参数。想跟进 CLIProxyAPI 的版本变动和字段改名,可以关注本站的 AI 工具栏目,有新版本我们会同步更新。