サブスクリプションアカウント
Codex、Claude、Antigravity、Grok などのサブスクリプション課金アカウントは、OAuth 認可を完了するか、既存の OAuth JSON をインポートできます。接続後は API キーと同じスケジューリングを共有します。
APIキーとの違い§
ゲートウェイから見れば、サブスクリプションアカウントも APIキーも同じ認証情報プールの一部であり、同じローテーション、リトライ、クールダウン、健全性分離の仕組みを共有します。サブスクリプションアカウント専用の運用手順は不要です。
相違点は3か所のみ：
- 接続方式 — OAuth認可を行うか、既存のOAuth JSONをインポートします。
- 認証情報は期限切れになります — ゲートウェイが認証情報を自動更新します。認可に問題がある場合は、認証情報を手動更新するか、アカウントを再接続できます。
- クォータウィンドウがある — サブスクリプションのクォータは周期ごとにリセットされ、管理画面に残りクォータとリセット時刻が表示されます。
アカウントを接続する§
サブスクリプションアカウントもグループに属します。「グループ → 新規グループ」でCodex、Claude、Antigravity、Grokを選び、アカウントを接続または認証情報をインポートしてください。
認可パネルは常に展開されています。リモートデプロイでは認可リンクとコールバック URL を手動でコピーする場面が多いため、これはフォールバックではなく主要な手順です。
接続方法は、チャネルと認可済みの認証情報を既に持っているかどうかによって 3 種類あります：
- ローカルコールバック（Codex、Claude、Antigravity）— ブラウザーで認可を完了すると、アップストリームがローカルの固定ポートへリダイレクトし、ゲートウェイが認可コードを受け取ります。
- デバイスコード（Grok）— GPT-Load に表示されたコードをアップストリームの Web サイトへ入力して認可します。コールバックポートは不要です。
- OAuth JSON のインポート（全4サブスクリプションチャネル）— 既存のOAuth JSONをアップロードまたは貼り付けます。このマシンでローカルコールバックを完了する必要はありません。
CPA互換、公式Codex、公式Claude Code、sub2apiのOAuth JSONをインポートでき、複数ファイルやアカウント配列にも対応します。PATや必要な更新用認証情報のないファイルは非対応です。
サブスクリプショングループは任意のHTTPS上流ルートURLやパス接頭辞を設定できます。中継先は該当チャネルの呼び出し、モデル検出、クォータ照会に対応する必要があり、業務リクエストは公式URLへ暗黙に戻りません。OAuth認可とトークン更新は引き続き公式エンドポイントを使います。
コールバックポート§
ローカルコールバックを使う3つのチャネルでは、ポートがアップストリームクライアントによって固定されているため変更できません：
| チャネル | コールバックポート | 説明 |
|---|---|---|
| Codex | 1455 | コールバックアドレス http://localhost:1455/auth/callback |
| Claude | 54545 | アップストリームのクライアントによって固定される |
| Antigravity | 51121 | アップストリームのクライアントによって固定される |
| Grok | 必要ない | デバイスコード認証のため、本機のポートを占有しません |
Docker Compose はデフォルトで3つのポートを公開し、メインサービスと同様に127.0.0.1にだけバインドされます：
ports: - "$${BIND_ADDRESS:-${HOST:-127.0.0.1}}:$${PORT:-3001}:$${PORT:-3001}" - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:1455:1455" # Codex - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:54545:54545" # Claude - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:51121:51121" # Antigravity
これらのポートはアップストリームクライアントにより固定され変更できないため、1 台のホストで同時にローカルコールバック認可を使えるデフォルト Compose インスタンスは 1 つだけです。他のインスタンスは既存の OAuth JSON をインポートでき、Grok はデバイス認可も使えます。
リモートデプロイでの認可方法§
ここが最もつまずきやすい点です。サービスがリモートサーバーで動作している場合、ブラウザー内のlocalhostはサーバーではなく、自分のコンピューターを指します。そのため認可後のリダイレクトは失敗します。
解決方法は 3 つあります。いずれかを選んでください：
- 手動でコールバックアドレスを貼り付ける — リダイレクトに失敗したら、ブラウザーのアドレスバーから完全なコールバック URL をコピーし、管理画面のコールバック欄に貼り付けます。ゲートウェイが認可コードを取り出して処理を完了します。この方法は最も汎用的な方法で、ネットワーク設定の変更は不要です。
- SSH ポートフォワーディング — サーバーのコールバックポートをローカルに転送し、
localhostからサーバーへ到達できるようにします：
ssh -L 1455:127.0.0.1:1455 user@your-server # Claude は 54545、Antigravity は 51121 を使用 # 転送は接続を維持している間に認証完了でOK
既存の OAuth JSON がある場合は、そのままアップロードまたは貼り付けてインポートできます。コールバックポートは不要です。
コールバックポートをインターネットへ公開してはいけません。コールバックを手動で貼り付ける、SSH 転送を使う、または既存の OAuth JSON をインポートしてください。OAUTH_CALLBACK_BIND_ADDRESS を 0.0.0.0 に変更する必要はありません。
4種類の認可状態§
各サブスクリプションアカウントには認可状態があり、トラブルシューティングの際はまずそれを確認してください：
| 状態 | 意味 | どうすべきか |
|---|---|---|
| 準備完了 | 認証情報は有効で、正常にスケジュールに参加しています | 処理不要 |
| リフレッシュ中 | ゲートウェイが認証情報を更新しています | 待つだけで通常数秒で完了 |
| 再認可が必要 | アップストリームが更新を拒否したか、既存の認可が無効になっています | 認証情報の更新を試し、失敗が続く場合は再接続またはインポートします |
| 結果不明 | リフレッシュリクエストが明確な結果を取得できなかった場合、ネットワークの問題が考えられます | 認証情報の更新を試し、失敗が続く場合は再接続またはインポートします |
アカウントカードのメニューにある「認証情報を更新」は認証の復旧に使います。「利用枠を更新」は利用枠情報を更新し、回復条件を満たす場合は利用枠によるクールダウンも解除します。 手動で無効にしたアカウントは、有効にしてから認証情報を更新してください。
クォータ期間、リセット時刻、認可状態を同じ画面で確認できます。
クォータ情報の見方§
初回インポート後にクォータを同期し、現在のクォータとリセット時刻を取得してください。アップグレード後にクォータが更新されない、または表示がおかしい場合も、一度手動で更新できます。
利用枠の数値はローテーション順を決めません。上流のレート制限応答は引き続きクールダウンと切り替えを引き起こします。利用枠は能動的な同期や上流の応答で更新され、遅延する場合があります。
新しい利用枠の観測で、一意に対応するウィンドウの使用率が 5 パーセントポイント以上下がると、そのアカウントとモデルの利用枠によるクールダウンが解除されます。能動的な同期と応答からの更新の両方が対象です。他の原因やカスタムルールによるクールダウン、認証、無効化、ブラックリスト、失敗回数は変更されません。
クォータ欄はアカウントを追加すべきか判断するために使い、ゲートウェイが次に選ぶアカウントの予測には使いません。候補Groupと利用可能な認証情報は、監視とトラブルシュートのルートチェックで確認します。
Codex グループを開き、Modern の「クォータを同期」または Classic の「同期」をクリックします。上流が正の残高または無制限のクレジットを返す場合、アカウントカードに「クレジット」が表示されます。表示がなくても残高がゼロとは限りません。
クレジットは周期クォータやリセットクレジットとは別に表示され、合算されず、スケジューリングにも使われません。
Codex と Claude のアカウントでは、利用可能なリセット回数と有効期限が表示される場合があります。リセットは管理画面で手動確認した場合のみ消費され、自動実行されません。実行後は使用量情報を更新して結果を確認してください。結果が不明な場合は、新しいリセットを開始せず、元の操作を確認してください。
使用の前提条件§
- 利用権限のあるアカウントだけを接続し、各プロバイダーのサブスクリプション規約に従ってください。クォータの共有や転売は通常禁止されています。
- サブスクリプションチャネルはアップストリームの OAuth と互換プロトコルに依存します。アップストリームの変更に合わせて更新が必要になる場合があります。こうした変更はゲートウェイでは制御できません。
- 認証情報はローカルで暗号化されますが、復号キーとデータベースを必ず一緒にバックアップしてください。セキュリティと本番運用を参照してください。