這個專案做什麼

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

主要功能：

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

優點：

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

先準備好帳號憑證

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

1
2
3
4
5
6

{
  "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

使用建議

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