CLIProxyAPI：把 Codex、Claude Code、Gemini CLI 统一封装成 API

Sun, 24 May 2026 10:03:33 +0800

CLIProxyAPI 是一个很有“民间工程味”的项目：它不是再造一个大模型，也不是单纯做 API 转发，而是把一堆原本偏交互式、偏 CLI、偏 OAuth 登录的 AI 工具，重新包成统一 API 服务。

它支持的对象包括 Gemini CLI、OpenAI Codex、Claude Code、Amp CLI、AI Studio Build，以及上游 OpenAI 兼容服务。换句话说，它想解决的问题是：

我手上有 CLI 工具、有订阅账号、有 OAuth 登录态，能不能像调用普通 API 一样，把这些能力接到自己的客户端、脚本、IDE 或内部服务里？

CLIProxyAPI 给出的答案是：可以，中间加一层代理，把不同来源的 CLI 能力转换成 OpenAI、Gemini、Claude、Codex 兼容接口。

它真正解决的痛点

很多 AI 编程工具的能力本来很强，但默认使用方式并不适合自动化。

比如：

Gemini CLI 能登录账号使用，但你的程序更习惯调用 HTTP API。
Claude Code 很适合交互式编码，但接入其他客户端时会遇到协议不一致。
Codex CLI 支持 OAuth 登录和 Responses 风格能力，但不是所有上层工具都知道怎么和它说话。
一个团队可能有多个账号，需要轮询、负载均衡、异常账号剔除和配额观察。
你想让某些工具只认 OpenAI 格式，但后端实际可能是 Gemini、Claude 或 Codex。

CLIProxyAPI 的定位，就是做这些工具和客户端之间的“协议适配层”。

它把复杂的一侧藏在后面：OAuth、CLI 登录、多账号、不同协议、不同 provider。前面则暴露相对熟悉的接口，比如 OpenAI Chat Completions、OpenAI Responses、Gemini、Claude Messages、Codex 相关端点。

能力概览

从官方 README 和文档看，CLIProxyAPI 目前的核心能力包括：

为 CLI 模型提供 OpenAI、Gemini、Claude、Codex 兼容 API 端点。
通过 OAuth 登录接入 OpenAI Codex 和 Claude Code。
支持流式、非流式响应，以及部分场景下的 WebSocket。
支持函数调用、工具调用和多模态输入。
支持 Gemini、OpenAI、Claude 多账号轮询与负载均衡。
支持 Gemini AI Studio API Key。
支持 AI Studio Build、Gemini CLI、Claude Code、OpenAI Codex 的多账号池。
可以通过配置接入 OpenAI 兼容上游，比如 OpenRouter。
提供 Go SDK，方便把代理能力嵌入到自己的服务里。

这类项目最有价值的地方，不是“多支持几个模型名”，而是把账号登录、协议转换和请求路由这些琐碎工作打包起来。

它适合谁用

CLIProxyAPI 更适合下面几类人：

第一类是重度 AI 编程用户。你已经在用 Codex、Claude Code、Gemini CLI，但想把它们接到 Cursor、Cline、RooCode、Amp、内部脚本或自建工作流里。

第二类是有多账号池的人。比如你有多个 Gemini、OpenAI、Claude 登录态，不想手工切换，希望自动轮询、均衡使用、遇到异常账号时能快速排查。

第三类是做团队内部网关的人。团队不希望每个客户端都分别适配 Gemini、Claude、Codex，而是想通过一个中间层统一暴露 API。

第四类是喜欢折腾协议的人。你可能关心 Responses、Chat Completions、Claude Messages、Gemini v1beta 这些接口如何互相转换，也可能希望在同一套客户端里切换不同后端。

如果只是个人偶尔问几句 AI，或者只用官方 App 聊天，那 CLIProxyAPI 的部署和维护成本就显得重了。

和普通 API 中转有什么不同

普通 API 中转服务一般是：

`1`	`客户端 -> 中转 API -> 上游模型 API`

CLIProxyAPI 的链路更像：

`1`	`客户端 -> CLIProxyAPI -> CLI / OAuth 登录态 / 多账号池 -> 模型服务`

区别在于，它处理的不只是 API Key 转发，还包括 CLI 工具、OAuth 账号、协议表面和模型别名。

比如 Codex 和 Claude Code 这类工具，本身就不是传统意义上“拿一个 API Key 就能稳定调用”的模式。CLIProxyAPI 把这些登录态和调用逻辑包装起来，让外部客户端像调用 API 一样访问它们。

这也是它吸引人的地方，同时也是它复杂的地方。

使用时最容易误解的地方

第一，不要以为统一 /v1/... 就能解决所有协议差异。

CLIProxyAPI 文档里专门提醒过：当你需要某一类后端的请求和响应形态时，优先使用 provider-specific 路径。例如 messages 风格用 /api/provider/{provider}/v1/messages，Gemini 模型路径用 /api/provider/{provider}/v1beta/models/...，chat-completions 风格用 /api/provider/{provider}/v1/chat/completions。

统一入口方便，但不同协议的语义并不会凭空消失。工具调用、流式返回、多模态输入、系统消息处理，都可能因为后端不同而有细节差异。

第二，模型名不等于唯一后端。

如果多个后端暴露了相同的客户端可见模型名，仅靠路径不一定能锁定真正执行推理的那个后端。要严格固定后端，最好使用唯一 alias、前缀，或者避免让多个后端暴露同名模型。

第三，多账号轮询不是无限额度。

轮询只能更均匀地使用账号池，不能绕过上游服务的真实限制。账号异常、配额耗尽、风控、OAuth 失效，都需要单独监控。

第四，它不是免维护魔法盒。

一旦你把它放进日常工作流，就要关心配置、日志、上游账号状态、版本升级、客户端兼容性和安全边界。

管理和监控怎么办

官方 README 提到，从 v6.10.0 开始，CLIProxyAPI 和 CPAMC 不再预置数据统计功能。如果需要使用量统计，可以配合独立项目：

CPA Usage Keeper：同步 CLIProxyAPI 数据，存到 SQLite，并提供聚合 API 和仪表盘。
CLIProxyAPI Usage Dashboard：本地优先的用量与配额看板，可展示账号、模型、时间窗口和 Codex 配额余量。
CPA-Manager：更完整的管理中心，面向请求监控、费用估算、账号池巡检、异常账号定位和清理建议。

这说明 CLIProxyAPI 的核心更偏“代理和协议层”，而不是一站式商业管理后台。如果是团队使用，最好一开始就把日志、监控和账号池管理考虑进去。

一个比较合理的使用姿势

如果要试用，可以按这个顺序来：

先用官方文档的 Quick Start 跑起来。
只接一个 provider，比如 Gemini CLI 或 Codex，确认基本请求能通。
再测试流式响应、工具调用、多模态输入这些高风险能力。
确认客户端实际使用的是哪个 endpoint，不要混用协议路径。
最后再加入多账号轮询、管理面板和用量统计。

不要一上来就把 Gemini、Codex、Claude、OpenRouter、多账号和所有客户端全接进去。这样出错时很难判断是认证问题、协议问题、模型名问题，还是上游账号问题。

安全边界也要想清楚

CLIProxyAPI 会接触到账号登录态、API Key、OAuth 相关凭据和请求内容。它如果只跑在自己机器上，风险相对可控；如果暴露到公网或团队内网，就必须认真处理认证、访问控制、日志脱敏和网络隔离。

尤其是管理端点，最好只允许本机或可信内网访问。不要为了省事直接把管理接口裸露出去。

总结

CLIProxyAPI 的价值在于，它把原本散落在多个 CLI、多个账号、多个协议里的 AI 能力，收拢成一个可编程的 API 层。

它适合重度 AI 编程用户、多账号用户和团队内部网关场景；不太适合只想“开箱即用、完全无维护”的轻量用户。

如果你正在折腾 Codex、Claude Code、Gemini CLI 这些工具，并且希望把它们接进自己的客户端或自动化工作流里，CLIProxyAPI 值得认真看一眼。但要把它当基础设施来用，而不是当一次性小工具来用。

参考资料：

Gemini CLI on KnightLi的博客