CLIProxyAPI 完整教學

一個 Go proxy，把你買的 Claude Pro / ChatGPT Plus / Gemini Pro CLI 訂閱重新打包成 OpenAI 相容 API。 同時也是 「中國地下 API 中轉站經濟」（koc.com.tw 2026-05-18 報導）的關鍵元件 — 這份教學會把技術與爭議同時講清楚。

⚠️ 本份教學立場：技術導向、不評斷使用，但明確標示資安、合規、ethics 風險。

1. 專案定位

1.1 一句話介紹

CLIProxyAPI = 拿到一份 Claude Code / ChatGPT Codex / Gemini CLI / Antigravity / Grok Build 的官方訂閱（你已經付錢 / 拿免費試用），用 OAuth 登入後，CLIProxyAPI 把這些 CLI 的後端流量重新封裝成 OpenAI / Anthropic / Google AI Studio 相容的 REST API，你的任何 client（LiteLLM、Cursor、LangChain、Cline、自家 app）就能透過 http://localhost:8317/v1/chat/completions 串接。

加上 multi-account round-robin，可以把多份訂閱組成一個 pool。

1.2 為什麼有這個工具？

flowchart LR
    A[官方 CLI
Claude Code / Codex / Gemini] -->|OAuth login
本機綁定 IDE| B[使用者]
    C[官方 API
api.anthropic.com / api.openai.com] -->|計費
$0.003-$0.075/k tok| B
    D[CLIProxyAPI] -->|把 CLI 的 OAuth token
暴露成 OpenAI 格式 API| B
    A -.->|被 wrap| D

官方 CLI 的訂閱（Claude Pro $20/月、ChatGPT Plus $20、Gemini Pro $20）有大量 token 配額，但官方限定只能在 CLI / IDE 用。CLIProxyAPI 把這條路徑「打通」到任何 OpenAI-compatible client。

合法情境：

• 一份訂閱多個 IDE 共用
• 自己的私人 dev tool 想跑 Claude 4.6 但不想付 API 費用
• 把不同家 model 統一到 OpenAI API 格式
• 做 model A/B test

爭議情境（見 §6 / §9）：

• 訂閱條款多禁止「程式化使用」或「轉讓配額」
• 中國灰色市場大量買低價地區帳號或免費試用組池，0.2 RMB = $1 訂閱價的代理
• 用戶資料隱私問題（程式碼通過第三方 proxy）

1.3 數字快照（2026-05-19）

• ⭐ 33,376 stars / 5,546 forks（7 月 2025 才建立，10 個月內擴散到 33k+ — 中國 AI 圈現象級工具）
• 🌍 README 3 語（English / 中文 / 日本語）
• 🛠 525 個 .go 檔，Go 1.26+
• 💸 4 個贊助商，全部是 API relay service provider（PackyCode、AICodeMirror、BmoPlus、VisionCoder）— 收費代理服務商，靠 CLIProxyAPI 自架基礎建設
• 🚨 2026-05-18/19 兩天內湧入 14 個資安審計 issue，全部 OPEN（見 §6）

2. 安裝指南

2.1 前置需求

• Go 1.26+（自編譯）或 Docker
• 至少一份官方 CLI 訂閱（Claude Pro / ChatGPT Plus / Gemini Pro / Grok Premium 等）
• 開放 OAuth callback port（預設 8085 / 1455 / 54545 / 51121 / 11451）

2.2 三條安裝路徑

flowchart TD
    A[使用者] --> B{偏好?}
    B -->|最快| C[Docker compose]
    B -->|可改 Go code| D[go build]
    B -->|無腦| E[GitHub Releases 預編 binary]
    C --> F[localhost:8317
OpenAI 相容 endpoint]
    D --> F
    E --> F

2.3 路徑 A：Docker（推薦）

 1git clone https://github.com/router-for-me/CLIProxyAPI.git
 2cd CLIProxyAPI
 3cp config.example.yaml config.yaml
 4
 5# 編輯 config.yaml：
 6# - api-keys: 設你的私 API key（client 端用）
 7# - remote-management.secret-key: 設管理 key
 8# - host: "127.0.0.1"  ← 強烈建議
 9
10docker compose up -d

2.4 路徑 B：Go 自編譯

1git clone https://github.com/router-for-me/CLIProxyAPI.git
2cd CLIProxyAPI
3go build -o cli-proxy-api ./cmd/server
4./cli-proxy-api --config config.yaml --tui   # TUI 模式 OAuth 登入互動

2.5 路徑 C：預編譯 binary

到 Releases 拉 cli-proxy-api_linux_amd64.tar.gz 等檔。

2.6 OAuth 登入流程（拿訂閱配額）

1./cli-proxy-api --tui
2# 進 TUI 後選 "Add account" → 選 "Claude Code" / "Codex" / "Gemini" ...
3# 自動開瀏覽器 → 登入官方帳號 → callback 寫到 auths/ 目錄
4# auths/*.json 是該帳號的 refresh token 池

之後啟動 server，把瀏覽器 OAuth 換來的 token 拿去呼叫官方 CLI 同名 endpoint：

1curl http://localhost:8317/v1/chat/completions \
2     -H "Authorization: Bearer your-api-key-1" \
3     -H "Content-Type: application/json" \
4     -d '{"model":"claude-opus-4-7","messages":[{"role":"user","content":"hi"}]}'

3. 核心架構解析

3.1 內部模組

flowchart TB
    subgraph In[Inbound layer]
        API[internal/api
Gin HTTP + Amp module]
        WS[internal/wsrelay
WebSocket relay]
    end
    subgraph Mid[Translation layer]
        TR[internal/translator
OpenAI ↔ Claude ↔ Gemini]
        TH[internal/thinking
canonical reasoning config]
    end
    subgraph Out[Outbound layer]
        EXE[internal/runtime/executor
per-provider executor]
        REG[internal/registry
model list + remote updater]
    end
    subgraph Sto[Storage / auth]
        AUTH[internal/auth
OAuth flows]
        STORE[internal/store
file / Postgres / git / object]
        CACHE[internal/cache
request signature]
        WATCH[internal/watcher
config hot-reload]
    end
    subgraph Mgmt[Management surface]
        MGMT[/v0/management/
API + management.html SPA/]
        ASSET[internal/managementasset
auto-download panel HTML]
    end
    Client[OpenAI-compatible client] --> API
    API --> TR
    TR --> EXE
    EXE --> Claude[Anthropic API]
    EXE --> OpenAI[OpenAI API]
    EXE --> Gemini[Google AI Studio]
    EXE --> Grok[xAI Grok]
    AUTH --> STORE
    EXE --> STORE
    MGMT --> ASSET

3.2 三層 API 轉換

canonical 是 internal pivot representation；新增 backend 只需寫一個 translator + executor，不必 n × n 改寫。

3.3 多帳號 round-robin

auths/ 目錄下每個 .json 是一個 OAuth 帳號的 token。CLIProxyAPI 啟動時掃描所有，按 backend 分組做 round-robin：

1auths/
2├── claude_code_user1.json
3├── claude_code_user2.json   ← Claude pool round-robin
4├── claude_code_user3.json
5├── codex_user1.json          ← Codex pool round-robin
6├── codex_user2.json
7└── gemini_user1.json         ← Gemini single

每次請求過來，按 model family 找對應 pool，依序輪用帳號；其中一個被 ban / quota 滿就 fallback 下一個。

3.4 Management API + Web Panel

• /v0/management/* REST API — 加帳號、改 config、看 usage
• /management.html 是 第三方 SPA（從 https://github.com/router-for-me/Cli-Proxy-API-Management-Center 下載），由 CLIProxyAPI 啟動時 auto-update
• ⚠️ 這正是 #3455 / #3457 / #3458 三個資安 issue 的中心 — 第三方 JS 在 runtime 下載 + 無 SRI + fallback 走無簽章 HTTP（見 §6）

4. Helper Scripts / 重要設定

4.1 config.yaml 關鍵段（v7.1.14）

 1host: ""              # ← 預設綁所有 interface（!! 建議改 "127.0.0.1"）
 2port: 8317
 3
 4remote-management:
 5  allow-remote: false # ← 預設僅 localhost OK
 6  secret-key: ""      # 管理 key
 7
 8pprof:
 9  enable: false
10  addr: "127.0.0.1:8316"   # ← #3454 警告：runtime 不強制 loopback
11
12api-keys:               # ← client 端用的 API key（自訂）
13  - "your-api-key-1"
14  - "your-api-key-2"
15
16auth-dir: "~/.cli-proxy-api"

4.2 Server CLI flags

1./cli-proxy-api \
2    --config config.yaml \
3    --tui \
4    --standalone \
5    --local-model \           # 不從遠端 update model list
6    --no-browser \
7    --oauth-callback-port 8085

4.3 Storage backends

• file（預設）：~/.cli-proxy-api/auths/*.json
• Postgres：PGSTORE_* env vars
• Git：GITSTORE_* env vars（⚠️ #3461 — PAT 可能外洩）
• Object store：OBJECTSTORE_* env vars

4.4 Supporting tools（社群）

• CPA Usage Keeper — Redis queue → SQLite dashboard
• CLIProxyAPI Usage Dashboard — local-first quota dashboard
• CPA-Manager — request-level monitor + LiteLLM price sync + Codex quota detection

5. 應用場景

5.1 場景 A：個人開發者把 Claude Pro 變成 API

1# 1. 你有 Claude Pro 訂閱 $20/月
2# 2. 跑 CLIProxyAPI + Claude Code OAuth
3# 3. 從 Cursor / Cline / 自家 app 透過 localhost:8317 用 Claude Opus

理論上一份訂閱 = 在多個工具中用。Anthropic ToS 對「程式化使用」的看法存疑，請自查。

5.2 場景 B：團隊統一 model gateway

1所有員工 client → 內部 CLIProxyAPI gateway → 多家 backend pool
2                                            ├── Claude pool (10 帳號)
3                                            ├── Codex pool (10 帳號)
4                                            └── Gemini pool (5 帳號)

集中 quota 管理、統一 audit log。

5.3 場景 C（爭議）：API 中轉站 reseller

這是 koc.com.tw 2026-05-18 報導的核心場景。

營運者大量買 / 集 / 試用官方訂閱 → 透過 CLIProxyAPI 暴露成 OpenAI API → 在閒魚 / 淘寶 / Twitter / Telegram 上轉賣給其他開發者，價格 0.2-0.3 RMB/$1 = 官方價的 3-4%。

Anthropic / OpenAI 立場：違反 ToS、會 ban 帳號。 白宮 2026-04-23 備忘錄：警告中國實體「工業規模蒸餾」攻擊使用此類 proxy 網路。 Anthropic 2026-02 報告：單一代理網路管理超過 20,000 個詐騙帳號。

6. 資安掃描報告

掃描方法：grep 關鍵字 + 檢視 14 個 2026-05-18/19 開的資安 issue + 看 README / config.example.yaml / docker-compose.yml + 看 LICENSE / 維護者變更。

6.1 結論：🔴 HIGH RISK

v7.1.14 目前狀態 NOT suitable for production / multi-tenant deployment。資安 baseline 落後當代 production-grade proxy 一個世代。

6.2 細項 — 全部對應 2026-05-18/19 官方 issue tracker

6.3 給使用者的 mitigation 建議

最低限度（個人使用）：

1. 改 host: "127.0.0.1"，不要 bind 0.0.0.0
2. 不要 enable pprof（或確保只在 loopback）
3. 不開放 /management.html 外網
4. docker-compose 改 127.0.0.1:8317:8317 而非 8317:8317
5. Container 跑在 isolated network namespace

企業 / 多租戶（強烈建議）：

1. 不要在 production 用 v7.1.14 — 等 14 個 OPEN issue 被處理
2. 自己 fork 一份，patch 上述安全洞
3. 或選 production-grade 替代品（LiteLLM / OpenRouter / 自建 proxy）

6.4 帳號層風險（與資安 issue 獨立）

• 用 CLIProxyAPI 可能違反 Claude / OpenAI / Gemini ToS（「程式化使用」「轉讓配額」「禁止 proxy」條款）
• 帳號被 ban 後沒有 appeal 途徑，付出的訂閱費可能無法退
• 自有 codebase 通過 proxy 時，程式碼會被 server 看到（自架還好，用 reseller 服務 = 程式碼上傳給陌生人）

7. FAQ — 結合 koc.com.tw 那篇文章的問答

以下 Q&A 整合「中國AI學生每天狂燒GPT-5.4上億Token只要一美金！地下API中轉站經濟揭露」（電腦王阿達，2026-05-18）的核心觀察。

Q1：koc 文章那種「$1/天燒一億 token」是真的還是行銷？

A：koc 引用的是 Reddit r/vibecoding 上中國資工系學生 u/No-Chance-6828 的貼文，旁證牛津中國政策實驗室 Zilan Qian 5/5 ChinaTalk 長文。現象真實存在：

• 閒魚 / 淘寶上有 GPT API 賣家以 0.2-0.3 RMB / $1 訂閱價賣（官方價 3-4%）
• Claude 因為安全機制嚴，灰色價落在官方 10-20%
• 從 Reddit + 中國微博 + Twitter + Telegram 都能找到實作截圖

CLIProxyAPI 正是這條供應鏈的最關鍵 OSS 元件。

Q2：那 reseller 怎麼把成本壓到 3%？

A：koc 引用「五大技術套利手法」（電腦王阿達另文）：

1. 大量買 菲律賓 / 印度 / 巴西 等低定價地區訂閱（地理價差）
2. 用 ChatGPT Plus 免費試用 帳號池（一個身分證一次免費試用）
3. 用 SMS 農場 + 假手機號 大量註冊
4. CLIProxyAPI round-robin 集中分配給轉售客戶
5. 後端可任意切換 model（用戶以為用 GPT-5.4，實際拿到 cheaper model 回應）

koc 文中的「編按：我個人比較傾向是用這個伎倆」直指第 5 點 — 客戶根本不知道自己拿到的是不是宣稱的 model。

Q3：自己用合法嗎？我有正版訂閱想做多 IDE 共用，這算 OK 嗎？

A：灰色地帶。

• 技術上 CLIProxyAPI 只是把官方 OAuth flow 暴露成 API
• 但 Anthropic / OpenAI ToS 多禁止：「使用 automation 反覆 query」、「程式化重用 session」、「將 personal 帳號用於 third party」
• 個人 dev tool 自用：通常 Anthropic 不太抓，但保留 ban 權利
• 轉賣 / 共享給他人：明確違 ToS，帳號可能直接被 close

koc 文章的核心場景是「轉賣」，與「自用」是不同層級的問題。

Q4：白宮 2026-04-23 備忘錄為什麼點名這類 proxy？

A：koc 引用：白宮警告中國實體用「工業規模 distillation（蒸餾）」攻擊美國 frontier AI model — 用幾萬個代理帳號刷大量 query，把 input/output 對拿回家訓練自己的 model。Anthropic 同期報告稱發現單一網路管理 20,000+ 詐騙帳號。

Zilan Qian 的反駁：白宮 + Anthropic 都誤讀了 — 這個生態系是「中轉站經濟（Transfer Station）」，背後是 GitHub + 閒魚 + 淘寶 + Twitter + Telegram 公開運作的 API 代理市場，遠超實驗室 distillation 規模。參與者包括大學教授、學生、業餘愛好者、獨立開發者、甚至中國大型科技公司的工程師（在非敏感任務上）。

CLIProxyAPI 33,376 stars 的擴散度與這個觀察一致。

Q5：中國國產模型（DeepSeek 等）的原本價格優勢去哪了？

A：koc 引用 Reddit 發文者：「當 GPT-5.4 透過代理拿到的價格跟 DeepSeek 一樣便宜時，大部分開發者會選 GPT-5.4」。

• DeepSeek 等中國模型原本最大賣點是價格（比 Anthropic / OpenAI 便宜 10×）
• 但 grey market 把 GPT / Claude 也壓到 3-4% 官方價
• 產業結構衝擊：中國國產模型在中國開發者間的市佔被 grey market 稀釋

對台灣 / 美國 / 歐盟開發者來說，這個套利通道不存在（語言、SMS 農場、低價地區帳號取得難度高），但對中國開發者來說是「default channel」。

Q6：用 CLIProxyAPI 連到 reseller 的服務，我的程式碼會怎樣？

A：koc 文章引述「傳聞部分營運者把互動數據轉賣給中國 AI 實驗室」— 也呼應白宮的 distillation 警告。程式碼通過 reseller 的 server 完整可讀：

• 你的 prompt
• 你的 code snippet
• 你的 secret（如果不小心放在 prompt 裡）
• 你的 reasoning chain

中國開發者社群普遍態度：「我早就把資料交給 OpenAI 了，多一個中間人差別不大。」但這個立場對於有商業機密 / 法規（HIPAA / GDPR / 各國個資法）需求的場景並不適用。

Q7：可靠度與 model swap 詐騙

A：koc 引用兩個風險：

1. 帳號 ban 風潮：OpenAI / Anthropic 持續 ban，reseller 必須補帳號池；服務不穩
2. 後端 model swap：reseller 可在客戶不知情下，把宣稱的 gpt-5.4 路由到 gpt-3.5，計費按高的收

對策：

• 要付費用 reseller 服務：選社群長期口碑好的（如 koc 文章 reseller 經濟存在比價網站 / 品質測試平台）
• 自架 CLIProxyAPI：完全在自己機器上，沒有 model swap 風險（但帳號池維護全自負）
• 正規 API：付官方 API 費用，最貴但最穩

Q8：AI 廠商怎麼反制？

A：koc 引用 Anthropic 多層安全：

1. 地理封鎖（block 中國 IP）
2. 電話驗證
3. 信用卡要求（白名單地區）
4. KYC + 即時生物特徵驗證

但每層都有 counter：

1. → VPN + 住宅 IP proxy
2. → SMS 農場（中國有租用 SIM card 服務）
3. → 跨境代理刷卡
4. → 生物特徵資料收集（黑灰產）

Zilan Qian 警告：這些「繞過基礎設施」的長期影響不只是中美科技戰，更侵蝕 AI 廠商的用戶溯源能力，可能被惡意行為者利用。

Q9：對台灣 / 一般開發者的實務建議？

個人 dev 自用：

• 有正版訂閱想多 IDE 共用 → 謹慎使用，自架在 127.0.0.1，patch §6.3 5 條
• 別在 production / 給多人共用，會出資安問題
• 別買中國 reseller 的服務（程式碼隱私 + 模型 swap 雙重風險）

團隊 / 企業：

• 走 LiteLLM（OSS，安全 baseline 較高）+ 官方 API
• 或 OpenRouter（合法 aggregator）
• 別在 multi-tenant 環境用 v7.1.14（14 個 unaddressed security issue）

研究者：

• CLIProxyAPI 是研究「LLM gray market economy」的關鍵 case
• 從 stars 增長曲線、issue 內容、贊助商組成可推斷 reseller ecosystem 規模

8. 進階技巧

8.1 用 LiteLLM 當前面 client 串 CLIProxyAPI

1# litellm_config.yaml
2model_list:
3  - model_name: claude-opus-via-cli
4    litellm_params:
5      model: openai/claude-opus-4-7
6      api_base: http://127.0.0.1:8317/v1
7      api_key: your-api-key-1

8.2 多帳號池子健檢

1# /v0/management/accounts → 列所有 auths/ 帳號狀態
2curl http://127.0.0.1:8317/v0/management/accounts \
3     -H "X-Management-Key: $MGMT_KEY"

或裝 CPA-Manager 跑 Codex quota detection。

8.3 Provider pinning

/api/provider/{provider}/v1/... 強制路由到指定 backend：

1# 強制走 Claude（不要被 round-robin 跑到 Codex）
2curl http://127.0.0.1:8317/api/provider/claude/v1/messages \
3     -H "Authorization: Bearer your-api-key-1" \
4     -d '{...}'

8.4 Hot reload config

config.yaml 修改後 internal/watcher/ 會自動 reload，無需 restart。

9. 整合進其他工作流

9.1 與本專案 (AI-knowledge_template) 的關係

flowchart LR
    A[ai-save
抓 koc 文章] --> B[inbox/.../642913.md]
    C[gh-tutorial-qd
本份 tutorial] --> D[結合 B 的 §6 §7]
    D --> E[quarkdown HTML]
    E --> F[Discord 打包]

這份 tutorial 示範了 gh-tutorial-qd 工作流的延伸用法：repo metadata + 外部報導素材 (ai-save) → 一份兼顧技術深度與 ethics / 社會脈絡的綜合報告。

9.2 競品 / 替代

9.3 與 koc 文章生態系工具的對照

注意 README 列的 4 個贊助商全部是 API relay service provider，這在 OSS 圈不常見 — 商業利益鏈條清晰。

10. 重點摘要 Checklist

• CLIProxyAPI = 把 Claude Code / Codex / Gemini CLI 等 OAuth-based CLI 訂閱重新包成 OpenAI 相容 API
• 7 個月內擴散到 33,376 stars，5,546 forks，現象級工具
• 內部三層架構：translator → canonical → executor，新 backend 只需寫 1 對
• 多帳號 round-robin 是賣點，也是 reseller 經濟基礎
• 🔴 HIGH RISK：14 個資安 issue 在 2026-05-18/19 兩天集中湧入，全部 OPEN 未回應
• 不適合 production / multi-tenant，自用要至少 patch §6.3 5 條
• License 個人 OK，但訂閱條款大多禁止程式化使用 / 轉讓
• koc.com.tw 2026-05-18 報導：中國 grey market 以 官方 3-4% 價格 賣轉售服務，CLIProxyAPI 是核心 OSS 元件
• 白宮 + Anthropic 都在追擊，但 koc 引述 Zilan Qian 認為這是被誤讀的「中轉站經濟」遠超 distillation 規模
• 對台灣 / 一般開發者：個人自架自用可，但別買 reseller 服務

11. 進一步閱讀

• GitHub repo：https://github.com/router-for-me/CLIProxyAPI
• 中文 README：https://github.com/router-for-me/CLIProxyAPI/blob/main/README_CN.md
• 官方文件站：https://help.router-for.me/
• 配套管理工具 CPA-Manager、CPA Usage Keeper、Usage Dashboard
• koc 文章原文（本份 tutorial §7 主要引述）：https://www.koc.com.tw/archives/642913
• Zilan Qian / Oxford China Policy Lab：https://www.chinatalk.media/p/how-to-buy-cheap-claude-tokens-in
• Reddit 原文：https://www.reddit.com/r/vibecoding/comments/1tehf5o/i_vibe_code_with_gpt54_for_1day_100m_tokens_some/
• 白宮 2026-04-23 中國 AI distillation 備忘錄（搜尋 “April 2026 industrial-scale distillation”）
• LiteLLM（合法替代）：https://github.com/BerriAI/litellm
• OpenRouter：https://openrouter.ai/

Captured：2026-05-19 by gh-tutorial-qd workflow（depth=full / lang=zh-tw / qd_preset=report / security=on / extra=koc-article-integration）。