ChatGPT Codex 配额使用情况查询面板：codex-quota的使用方法

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

ChatGPT Codex 配额使用情况查询面板：codex-quota的使用方法

这个项目做什么

先准备好账号凭证

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

CLI 参数说明（README 对齐）

Web Dashboard 用法（保留原命令）

HTTP 接口（方便接自动化）

Docker 用法（保留原命令）

Docker Compose 用法（保留原命令）

使用建议