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的博客