这个项目做什么

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。