codex-quota 実践ガイド：コマンドをそのまま使う Local・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 は 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

運用のヒント

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

Docker Compose on KnightLiブログ

codex-quota 実践ガイド：コマンドをそのまま使う Local・Web・Docker 運用

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

先にアカウント認証情報を準備する

Local CLI の使い方（元コマンドを維持）

CLI オプション説明（README 準拠）

Web Dashboard の使い方（元コマンドを維持）

HTTP エンドポイント（自動化向け）

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

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

運用のヒント