codex-quota 實戰指南：保留命令列的本機、Web 與 Docker 用法

Thu, 16 Apr 2026 18:13:04 +0800

這個專案做什麼

codex-quota 是一個輕量工具，可查詢 ChatGPT Codex 配額使用情況，資料來源是 https://chatgpt.com/backend-api/wham/usage。

主要功能：

支援單帳號或多帳號（account/*.auth.json）查詢。
輸出 five_hour%、weekly%、weekly_reset，並標記來源（network 或 cache）。
對暫時性失敗（408、429、5xx）做指數退避重試。
內建本地快取，減少配額耗盡時的重複請求。
提供 Web Dashboard、JSON API、auth 檔管理頁面。

優點：

輕量：單腳本即可執行，依賴簡單。
實用：CLI 與 Web 兩種入口都能使用。
可部署：支援 Docker 與 Docker Compose。
易維運：支援重試、快取與定時刷新。

先準備好帳號憑證

在 account/<name>.auth.json 建立憑證檔，例如：

{
  "tokens": {
    "access_token": "eyJ...",
    "account_id": "user-xxxxxxxx"
  }
}

說明：

access_token 與 account_id 是查詢介面所需欄位。
檔名中的 <name> 會作為結果中的帳號名稱。

本機 CLI 用法（保留原命令）

安裝依賴：

`1`	`pip install -r requirements.txt`

說明：安裝專案執行依賴。

查詢全部帳號：

`1`	`python codex_quota.py`

說明：讀取 account/*.auth.json，彙總輸出所有帳號配額。

查詢單一帳號：

`1`	`python codex_quota.py your_account_name`

說明：只查詢 account/your_account_name.auth.json。

強制刷新（跳過快取）：

`1`	`python codex_quota.py --refresh`

說明：忽略本地快取，直接請求最新介面資料。

CLI 參數說明（README 對齊）

account_name：可選帳號名（不含 .auth.json）。
--account-dir：憑證目錄，預設 account。
--chatgpt-url：配額介面位址。
--raw-json：輸出完整 JSON 回應體。
--raw-headers：輸出回應標頭。
--refresh：忽略快取。
--retries：重試次數，預設 3。
--retry-delay：基礎重試間隔秒數，預設 2.0。

Web Dashboard 用法（保留原命令）

啟動服務：

`1`	`python codex_quota_service.py --host 0.0.0.0 --port 8081`

說明：啟動 HTTP 服務並監聽 8081 埠。

存取位址：http://localhost:8081

Service 參數：

--host：監聽位址，預設 0.0.0.0。
--port：服務埠，預設 8081。
--interval-seconds：排程刷新間隔，預設 3600。
--account-dir：憑證目錄，預設 account。
--state-file：狀態檔路徑，預設 <account-dir>/codex_quota_web_results.json。
--account-name：可選，單帳號模式。
--chatgpt-url：配額介面位址。
--retries：重試次數。
--retry-delay：基礎重試延遲。
--refresh：排程刷新時忽略 CLI 快取。

HTTP 介面（方便接自動化）

GET /：Dashboard 頁面。
GET /api/results：最新結果 JSON。
GET /refresh：立即刷新並跳回 /。
GET /auth：列出 auth 檔。
GET /auth/new：新建 auth 檔表單。
GET /auth/edit?name=<account>：編輯 auth 檔表單。
POST /auth/save：建立/更新 auth 檔。
POST /auth/delete：刪除 auth 檔。

Docker 用法（保留原命令）

建置映像：

`1`	`docker build -t codex-quota .`

說明：將目前專案打包為 codex-quota 映像。

執行容器（映射 8081）：

`1`	`docker run --rm -p 8081:8081 -v ./account:/app/account codex-quota`

說明：

--rm：容器退出後自動刪除。
-p 8081:8081：主機埠映射到容器埠。
-v ./account:/app/account：把本地憑證目錄掛載進容器。

存取位址：http://localhost:8081

Docker Compose 用法（保留原命令）

啟動：

`1`	`docker compose up --build`

說明：依 docker-compose.yml 建置並啟動服務。

存取位址：http://localhost:8081

使用建議

多帳號場景優先使用 Dashboard，便於統一查看與管理 auth 檔。
告警或自動化整合優先使用 GET /api/results。
公開倉庫不要提交真實 access_token。
若看到大量暫時性錯誤，可調大 --retries 與 --retry-delay。

Docker Compose on KnightLi的博客

codex-quota 實戰指南：保留命令列的本機、Web 與 Docker 用法

這個專案做什麼

先準備好帳號憑證

本機 CLI 用法（保留原命令）

CLI 參數說明（README 對齊）

Web Dashboard 用法（保留原命令）

HTTP 介面（方便接自動化）

Docker 用法（保留原命令）

Docker Compose 用法（保留原命令）

使用建議