CLIProxyAPI(CLI Proxy API)是 router-for-me 组织开源的 MIT 协议代理服务,把 Claude Code、ChatGPT Codex、Google Antigravity、Kimi、xAI Grok 等 CLI 订阅账号包装成 OpenAI / Gemini / Claude 兼容的本地 API,默认监听 8317 端口。官方推荐 Docker 部署,镜像为 eceasy/cli-proxy-api。本文按 3 种部署方式和 5 个实操步骤讲透,并附配置文件逐项说明。 CLIProxyAPI 官方仓库与镜像入口
部署前先把入口认准,避免下到改名换姓的第三方包:
- Docker 镜像:eceasy/cli-proxy-api:latest —— 官方 docker-compose.yml 中 CLI_PROXY_IMAGE 变量的默认值,可直接 docker pull。
- 桌面客户端:EasyCLIProxyAPI(同一组织的开源项目)—— 图形化配置、自动更新、系统托盘常驻,不想碰命令行可走这条。
- 管理面板:Cli-Proxy-API-Management-Center(CPAMC)—— 通过 /v0/management 系列接口做账号与配置管理。
注意区分:仓库是"取代码"的地方,镜像是"跑服务"的地方,管理面板是"管账号"的地方。三者版本不联动,升级时不要只更新其中一个。
Docker 部署的详细步骤
下面以官方推荐路径为例,从零到能调通接口共 5 步。命令以 Linux 为准,Windows/macOS 在 Docker Desktop 下同样适用,把卷路径换成本地绝对路径即可。
- 准备环境:安装 Docker 与 Git。Debian/Ubuntu 可执行 apt update && apt install -y docker.io git,其他系统参考 Docker 官方文档;装完用 docker version 确认守护进程正常。
- 取回配置模板:git clone https://github.com/router-for-me/CLIProxyAPI.git 后进入目录,执行 cp config.example.yaml config.yaml;不想克隆整个仓库,也可以用 curl 单独下载 config.example.yaml。
- 改关键配置:至少改三处——api-keys 换成自己的随机串(推荐 openssl rand -hex 32 生成)、remote-management.secret-key 设置管理密钥、只本机访问时把 host 填成 127.0.0.1。
- 启动服务:docker compose up -d(旧版命令为 docker-compose up -d);也可以直接 docker run,把 config.yaml、auths、logs 三个路径挂进容器并映射 8317 端口,官方 compose 的挂载点为 /CLIProxyAPI/config.yaml、/root/.cli-proxy-api、/CLIProxyAPI/logs。
- 验证是否跑通:curl http://localhost:8317/v1/models -H "Authorization: Bearer 你的APIKey",能返回模型列表即服务正常。此时还没授权任何账号,列表可能为空,需要继续执行 OAuth 登录。
关键提示:auth-dir(默认 ~/.cli-proxy-api)里的凭证文件等同于账号密码,泄露等于把订阅额度拱手让人。务必收紧目录权限、加入 .gitignore,不要随截图、日志或代码仓库外传。
除 Docker 之外还有两条路:
Release 二进制方式
到仓库 Releases 页下载对应平台的二进制(截至 2026 年 9 月 10 日,最新标签为 v7.2.155,发布于 2026-09-08),按同样方式准备 config.yaml 后直接运行即可。适合本机自用、没有 Docker 的环境,升级就是下载新版本替换可执行文件。
源码编译方式
需要改代码或定制插件时走这条:安装 Go 工具链(官方 Dockerfile 使用 golang:1.26 镜像构建),克隆仓库后执行 go build -o ./CLIProxyAPI ./cmd/server/。编译产物与 Release 二进制用法完全一致。
config.yaml 参数与端口说明
服务的所有行为都由 config.yaml 控制。以下是部署阶段最常改的字段,字段名与默认值取自仓库根目录的 config.example.yaml:
| | |
|---|
| | 绑定网卡,空表示监听全部网卡(IPv4 + IPv6);填 127.0.0.1 则仅本机可访问 |
| | |
| | |
| | |
remote-management.allow-remote | | |
remote-management.secret-key | | 管理密钥,明文写入会在启动时自动哈希;留空则所有 /v0/management 路由返回 404 |
| | |
quota-exceeded.switch-project | | |
| | 多凭证选择策略,另有 weighted-round-robin、fill-first |
| | |
| | |
三种部署方式如何选择,可参考下面的对比:
| | | |
|---|
| | | |
| | | |
| | Go 工具链(官方构建镜像为 golang:1.26) | |
端口方面,官方 docker-compose.yml 默认映射了 8317、8085、1455、54545、51121、11451 六个端口,其中 8317 是 API 主端口,其余端口的具体用途以官方 compose 文件与文档说明为准。用 docker run 单独部署时若遇到登录回调打不通,可检查这些端口是否放行,或用 -oauth-callback-port 手动指定回调端口。
OAuth 登录与多账号轮询
服务跑起来还不等于能用,必须先完成授权。登录命令在服务二进制上执行:源码或 Release 方式为 ./CLIProxyAPI -xxx-login,Docker 方式为 docker exec -it cli-proxy-api ./CLIProxyAPI -xxx-login。
| | |
|---|
| | |
| | |
| | |
| | |
| | |
| | |
| -no-browser / -oauth-callback-port / -config | |
每成功登录一次,auth-dir 目录下就多一份凭证文件;重复登录多个账号即可自动获得轮询负载均衡,配合 routing.strategy 选择 round-robin(轮流)、fill-first(先用满一个再换下一个)或 weighted-round-robin(按权重分配)。配额打满时,quota-exceeded.switch-project 会自动切到下一个项目继续服务。在没有图形界面的服务器上,加 -no-browser 后手动把终端输出的授权链接复制到本机浏览器打开即可。
除了 OAuth,还有两条接入路径可以并存:一是通过配置接入任意 OpenAI 兼容的上游服务商(例如 OpenRouter)以及 Generative Language API Key;二是用 -vertex-import 导入 Google Vertex 服务账号的 JSON 密钥文件。前者适合补足订阅里没有的模型,后者适合已有云上额度的团队。 常见报错与排查方法
| | |
|---|
| Authorization 头里的 Key 与 config.yaml 的 api-keys 不一致 | 核对 api-keys 是否完全匹配,改完重启服务 |
| secret-key 留空导致管理路由未启用,或 allow-remote 为 false 时从外部访问 | 在 remote-management 下填写 secret-key;需要远程管理则把 allow-remote 改为 true |
| | 增加账号数量做轮询,或依赖 quota-exceeded 自动切换项目 |
| | 查看日志定位具体 provider,重新执行对应登录命令 |
| | 加 -no-browser,手动打开终端输出的授权链接 |
| | 修改 config.yaml 的 port,或停掉占用端口的进程 |
| | 检查 auth-dir 下是否生成了凭证文件,没有就重新执行登录命令 |
安全与合规注意事项
- 不要把 8317 端口裸奔到公网。需要远程访问时,至少设置高强度的 api-keys 和 secret-key,并在反向代理层加 HTTPS 与 IP 白名单。
- 凭证文件只放自有机器。多人共用一套代理时,建议给每个人分配独立 api-key,方便溯源和单独吊销。
- 合规提醒:把订阅制 CLI 账号包装成 API 调用,可能违反对应服务商的用户协议,用于团队共享或转售的风险更高。部署前请先阅读你所订阅服务的条款,商用场景优先选择官方 API 或官方授权渠道。
- 版本迭代极快,Release 近乎每日发布,配置项字段名可能随版本调整。升级前先 diff 新版的 config.example.yaml,不要直接覆盖正在使用的配置。
- 官方自 v6.10.0 起不再内置用量统计,需要查看消耗得接入第三方方案(如 CPA Usage Keeper、CPA-Manager-Plus)。
CLIProxyAPI 部署常见问题
Q:CLIProxyAPI 是免费的吗?
A:软件本身开源免费,采用 MIT 许可,可自由使用和修改。但实际产生调用的仍是你的 Claude / ChatGPT / Gemini / Kimi / Grok 订阅账号,订阅费用按各家标准照付。
Q:部署对服务器配置有什么要求?
A:它是一个转发层,不做模型推理,CPU 和内存占用都很低,1 核 1G 的轻量云服务器通常即可跑起来。真正影响体验的是网络到上游服务商的链路质量。
Q:支持哪些客户端和调用格式?
A:任何 OpenAI(含 Responses)、Gemini(含 Interactions)或 Claude 兼容的客户端与 SDK 都能接。把 base_url 指向 http://你的IP:8317/v1,密钥填 api-keys 中的任意一个即可,支持流式、非流式、函数调用与图文多模态输入。
Q:Docker 和二进制该选哪个?
A:长期跑在服务器上选 Docker,重启策略和挂载管理都省心;本机临时自用选二进制,零依赖;要改代码或开发插件才选源码编译。
Q:没有图形界面的服务器怎么完成授权?
A:加 -no-browser 参数,命令会打印一条授权链接,复制到本机浏览器打开并登录即可;Codex 还可以直接用 -codex-device-login 走设备码流。
Q:一个账号够用吗,多账号怎么配?
A:个人轻度使用够,团队或高频编码建议多登几个。重复执行登录命令即可叠加凭证,服务会按 routing.strategy 自动轮询;fill-first 适合想先把单账号额度用满的场景。
Q:管理后台怎么打开?
A:先在 config.yaml 的 remote-management 下设置 secret-key(留空则 /v0/management 全部返回 404),远程访问还需把 allow-remote 改为 true。可视化面板可搭配官方的 Cli-Proxy-API-Management-Center 项目。
Q:会不会泄露我的账号和数据?
A:服务部署在你自己的机器上,请求用你本人的凭证直连上游,不经过项目方服务器。风险点在于你把服务暴露给了谁——不要把 8317 端口对公网开放,也不要把凭证交给来路不明的第三方托管面板。
Q:值得自建吗,什么场景推荐?
A:适合已经订阅了多个编码类 CLI 服务、又想在自己的工具链里统一用一个 OpenAI 兼容接口调用的开发者。若只是偶尔调几个模型、或需要正式的商用 SLA 与发票,直接买官方 API 或官方授权渠道反而更省事。
以上内容参考 CLIProxyAPI 官方仓库(router-for-me/CLIProxyAPI)及其 config.example.yaml、docker-compose.yml 整理,该项目迭代频繁,配置项、镜像地址与登录参数可能随版本变动,请以仓库 README、config.example.yaml 与 https://help.router-for.me/ 最新公布为准。使用第三方订阅账号接入 API 前,请自行确认符合对应服务商的用户协议。