このプロジェクトは何をするか

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 は API クエリに必要な項目です。
• ファイル名の <name> は出力時のアカウント名として使われます。

Local 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：クォータ API エンドポイント。
• --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

説明：8081 ポートで HTTP サービスを起動します。

アクセス URL：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：クォータ API エンドポイント。
• --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：ローカル認証ディレクトリをコンテナにマウント。

アクセス URL：http://localhost:8081

Docker Compose の使い方（元コマンドを維持）

起動：

1

docker compose up --build

説明：docker-compose.yml に従ってビルド・起動します。

アクセス URL：http://localhost:8081

運用のヒント

1. 複数アカウント運用では、まず Dashboard で一元管理するのがおすすめです。
2. 通知や自動連携には GET /api/results を優先すると扱いやすいです。
3. 公開リポジトリに実際の access_token をコミットしないでください。
4. 一時エラーが多い場合は --retries と --retry-delay を増やしてください。