cliproxyapi (0.6.0)
Installation
registry=https://gitea.jsc.idv.tw/api/packages/jiantw83/npm/npm install cliproxyapi@0.6.0"cliproxyapi": "0.6.0"About this package
CLIProxyAPI
統一管理多個 OAuth 登入的 CLI 工具，以一個 OpenAI 相容端點對外派工
- 執行環境：Node.js 20.11 以上
- 外部依賴：無（只使用 Node 內建模組；管理介面的互動終端機是 vendor 進來的 xterm.js 靜態檔案，
不是 npm 依賴，
npm install不會下載任何套件） - 更新時間：2026/08/06 14:53:10
這是什麼
Antigravity（agy）、OpenAI Codex、GitHub Copilot CLI、Claude Code——這幾個各自要用瀏覽器 OAuth
登入的 CLI 工具，平常得一個一個登入、一個一個記住現在能不能用。CLIProxyAPI 把它們收進同一個本機
服務裡統一管理：
- 一個 Web 管理介面，看得到每個工具目前是停用／啟用／已登入，能直接安裝、走 OAuth 登入、登出、 或打開真正的互動終端機操作。
- 一個 OpenAI 相容 API（
/v1/chat/completions等），呼叫端只要照平常呼叫 OpenAI 的方式打過來， 服務會依請求的模型自動盤點、實測、挑選目前最適合、回應最快的工具執行；某個工具失敗會自動換下一個 候選，呼叫端不需要自己判斷「這次該用哪個 CLI」。
換句話說：對你的應用程式來說，這就是一個裝了好幾支 CLI 助理、隨時知道誰能用、誰壞了要換人的 「派工窗口」。
功能模組
| 模組 | 說明 |
|---|---|
| CLI 工具三態管理 | 停用／啟用／登入三態自動偵測（安裝狀態、認證方式、版本、健康度），定時重新檢查 |
| OpenAI 相容派工引擎 | /v1/chat/completions、/v1/completions、/v1/responses；依近期速度與失敗率排序候選，失敗自動換手，支援串流、回應快取、指數退避冷卻 |
| 模型盤點與實測 | 自動盤點各工具目前能用的模型，並對每個「工具 × 模型」組合實際下提示驗證真的能用，區分永久／暫時性失敗；以工具狀態雜湊判斷是否需要重跑，避免重複實測 |
| Web 管理介面 | 側邊欄導覽（總覽、CLI 工具、模型路由、測試呼叫、派工紀錄、系統日誌、金鑰管理），所有頁面透過 SSE 即時更新；總覽頁有本機資源走勢面板與工具狀態分布 |
| 互動式終端機 | 登入與「操作 CLI」都用真正的終端機模擬器（xterm.js），連全螢幕 TUI（信任資料夾對話框等）都能正確顯示與操作 |
| Gitea OAuth2 登入保護 | 用 Gitea 帳號登入管理介面，只允許 Gitea 系統管理員（is_admin）存取；登入後右上角顯示頭像與名稱卡片；設定頁貼上 Gitea PAT 即可自動建立 OAuth 應用程式並算出正確的回呼網址，換部署位置不用到 Gitea 後台手動維護 |
| API 金鑰管理 | 管理介面可產生／查看（遮蔽）／刪除 /v1/* 端點用的 Bearer 金鑰 |
| 隔離執行環境 | 可對單一工具啟用獨立 HOME／XDG，避免代理讀到開發主機既有的 CLI 設定與 skill |
| 零依賴圖示產生器 | 光柵化與 PNG／ICO 編碼全部自製，不需要 librsvg／ImageMagick／sharp |
安裝／更新／移除
前置條件只有 Node.js 20.11 以上（node -v 確認）。專案零依賴，安裝過程不會向 registry 下載任何套件。
安裝
# 方式一：clone 原始碼並全域安裝（推薦，取得全域指令）
git clone https://gitea.jsc.idv.tw/jiantw83/CLIProxyAPI.git && cd CLIProxyAPI && npm install -g .
# 方式二：從 Gitea npm 套件庫安裝（不需要 clone）
npm install -g cliproxyapi --registry=https://gitea.jsc.idv.tw/api/packages/jiantw83/npm/
方式二若套件庫需要認證，先把具備 package 權限的 token 設到 npm 設定，不要把 token 直接寫進安裝指令：
npm config set -- '//gitea.jsc.idv.tw/api/packages/jiantw83/npm/:_authToken' "$GITEA_TOKEN"
npm config set registry https://gitea.jsc.idv.tw/api/packages/jiantw83/npm/
npm install -g cliproxyapi
安裝完成後多了兩個等價的全域指令：
| 指令 | 說明 |
|---|---|
cliproxyapi |
啟動服務（Ctrl+C 結束） |
cliproxy |
同上，短別名 |
cliproxyapi --help |
顯示用途、管理介面／API 位址、設定檔位置、環境變數 |
cliproxyapi --version |
顯示版本 |
不想全域安裝，也可以直接在專案目錄下執行（見下方〈啟動〉）。
更新
# 方式一（clone 原始碼安裝的）：拉最新原始碼後重新全域安裝
git pull && npm run install:global
# 方式二（從 Gitea npm 套件庫安裝的）：直接更新全域套件到最新版
npm update -g cliproxyapi --registry=https://gitea.jsc.idv.tw/api/packages/jiantw83/npm/
方式二若之前已用 npm config set registry ... 設定過預設 registry，可省略 --registry 參數。
更新完成後執行 cliproxyapi --version 確認版本號，並重啟服務（Ctrl+C 後重新執行 cliproxyapi）才會套用新版程式碼。
移除
npm run uninstall:global
# 或在任意目錄下：npm uninstall -g cliproxyapi
全域安裝只放置程式碼與指令；設定與狀態一律留在 ~/.cliproxyapi/，
因此移除套件不會刪掉設定、實測結果與工作目錄，重新安裝即可接續使用。
啟動
cliproxyapi # 全域安裝後，任意目錄都可啟動
npm start # 或在專案目錄下執行（等同 node src/index.js）
npm run dev # 開發模式：檔案變更自動重啟
啟動後：
| 位置 | 說明 |
|---|---|
http://127.0.0.1:8317/ui/ |
管理介面 |
http://127.0.0.1:8317/v1 |
OpenAI 相容端點（SDK 的 base_url） |
~/.cliproxyapi/config.json |
設定檔（首次啟動就會自動把預設值寫到磁碟，之後可直接編輯或透過介面修改） |
~/.cliproxyapi/work/ |
CLI 工具的執行目錄（與呼叫端專案隔離） |
環境變數：CLIPROXY_HOME（資料目錄）、CLIPROXY_HOST、CLIPROXY_PORT、CLIPROXY_LOG_LEVEL（TRC/DBG/INF/WRN/ERR）。
以 OpenAI SDK 呼叫：
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8317/v1", api_key="unused")
print(client.chat.completions.create(
model="claude-haiku-4.5",
messages=[{"role": "user", "content": "台北今天天氣如何？"}],
).choices[0].message.content)