クォータガバナンス：Quota Protection + Smart Warmup の組み合わせ戦術
Antigravity Tools でプロキシを動かしていると、最も怖いのは 1 つのこと：主力モデルのクォータが「こっそり使い尽くされ」、本当に使いたい時に低すぎて打てないと気づくことです。
このレッスンは クォータガバナンス に特化します：Quota Protection で重要なモデルを残し；Smart Warmup でクォータが回復した時に「軽量ウォームアップ」を行い、一時的な脱落を減らします。
クォータガバナンスとは？
クォータガバナンスとは、Antigravity Tools で 2 セットの連動メカニズムを使って「クォータをどう使うか」を制御することです：あるモデルの残りクォータが閾値以下になった場合、Quota Protection はそのモデルをアカウントの protected_models に加え、そのモデルをリクエストする際、優先的に回避します；クォータが 100% に戻ると、Smart Warmup が極小トラフィックのウォームアップリクエストをトリガーし、ローカル履歴ファイルで 4 時間のクールダウンを行います。
このレッスンでできること
- Quota Protection を有効にし、低クォータアカウントが自動的に「譲歩」させ、高価値モデルを重要なリクエストのために残す
- Smart Warmup を有効にし、クォータ回復後に自動的にウォームアップし（4 時間クールダウンがトリガー頻度にどう影響するかを理解）
quota_protection/scheduled_warmup/protected_modelsの 3 つのフィールドがどこで有効になるかを明確にする- どのモデル名が「保護グループ」に正規化されるか（およびどのモデルがされないか）を知る
現在の悩み
- 「アカウントをローテーションしている」と思っているが、実際はずっと同じ種類の高価値モデルを消費している
- クォータが低くなって初めて気づく、さらに Claude Code/クライアントがバックグラウンドで warmup してクォータを食い尽くしている
- ウォームアップを有効にしたが、いつトリガーされるか、クールダウンがあるか、クォータに影響するかがわからない
この方法をいつ使うか
- 複数のアカウントプールがあり、「重要な瞬間」に重要モデルの余力を残したい
- クォータ回復時間を手動で監視したくなく、システムに「回復後の軽量検証」を自動させたい
🎒 始める前の準備
前提条件
このレッスンは、既に以下ができることを前提としています：
- Accounts ページでアカウントリストを見て、手動でクォータを更新できる
- ローカルリバースプロキシを少なくとも 1 回起動できる（少なくとも
/healthzにアクセス可能）
まだ動かない場合は、まず ローカルリバースプロキシを起動して最初のクライアントを接続する を見てください。
また、Smart Warmup はローカル履歴ファイル warmup_history.json を書き込みます。これはデータディレクトリにあり、データディレクトリの位置とバックアップ方法は先に 初回起動時の必知事項：データディレクトリ、ログ、トレイ、自動起動 を見てください。
コアコンセプト
この「組み合わせ戦術」の背後は実は非常にシンプルです：
- Quota Protection は「もう無駄遣い」を担当：あるモデルが閾値以下になったら、保護済みモデルとしてマークし、そのモデルをリクエストする際、優先的に回避（モデルレベルで、アカウント全体を無条件に無効化しない）。
- Smart Warmup は「回復したら検証」を担当：モデルが 100% に戻ると、軽量リクエストを 1 回トリガーし、リンクが利用可能かを確認し、4 時間のクールダウンで繰り返し邪魔されないようにする。
これらに対応する設定フィールドはすべてフロントエンドの AppConfig にあります：
quota_protection.enabled / threshold_percentage / monitored_models（src/types/config.ts参照）scheduled_warmup.enabled / monitored_models（src/types/config.ts参照）
そして実際に「そのモデルをリクエストする際、このアカウントをスキップするか」を決定するロジックはバックエンドの TokenManager にあります：
- アカウントファイルの
protected_modelsはget_token(..., target_model)でフィルタリングに参加（src-tauri/src/proxy/token_manager.rs参照） target_modelはまず 1 回正規化（normalize_to_standard_id）されるため、claude-sonnet-4-5-thinkingなどの変体は同じ「保護グループ」に折り畳まれる（src-tauri/src/proxy/common/model_mapping.rs参照）
次のレッスン予告
次のレッスンでは Proxy Monitor：リクエストログ、フィルタリング、詳細復元とエクスポート を学び、呼び出しブラックボックスを再現可能な証拠チェーンにします。
さあ、一緒にやってみよう
ステップ 1：まずクォータを「把握できる」まで更新
なぜ Quota Protection はアカウントの quota.models[].percentage に基づいて判断します。あなたのクォータが更新されていないと、保護ロジックは何もできません。
操作パス：Accounts ページを開き、ツールバーの更新ボタンをクリック（単一アカウントまたは全量どちらでも可）。
期待される結果：アカウント行に各モデルのクォータパーセンテージ（例：0-100）と reset time が表示される。
ステップ 2：Settings で Smart Warmup を開く（オプションだが推奨）
なぜ Smart Warmup の目標は「クォータを節約」ではなく「クォータが回復したらリンクを自己検証」です。モデルクォータが 100% になった時のみトリガーされ、さらに 4 時間のクールダウンがあります。
操作パス：Settings を開き、アカウント関連設定エリアに切り替え、Smart Warmup スイッチを有効にし、監視したいモデルにチェックを入れる。
設定を保存するのを忘れないでください。
期待される結果：Smart Warmup が展開され、モデルリストが表示される；少なくとも 1 つのモデルがチェックされている。
ステップ 3：Quota Protection を開き、閾値と監視モデルを設定
なぜ Quota Protection は「余力を残す」コアです：監視モデルのクォータパーセンテージ <= threshold_percentage の場合、そのモデルをアカウントファイルの protected_models に書き込み、その後そのモデルをリクエストする際、この種のアカウントを優先的に回避します。
操作パス：Settings で Quota Protection を開く。
- 閾値を設定（
1-99） - 監視したいモデルにチェックを入れる（少なくとも 1 つ）
非常に便利な初期設定
迷う場合、デフォルト threshold_percentage=10 から始めればよい（src/pages/Settings.tsx 参照）。
期待される結果：Quota Protection のモデルチェックで少なくとも 1 つが残っている（UI は最後の 1 つをキャンセルすることを阻止します）。
ステップ 4：「保護グループ正規化」があなたをハマらせないことを確認
なぜ TokenManager がクォータ保護判断を行う際、まず target_model を標準 ID（normalize_to_standard_id）に正規化します。例：claude-sonnet-4-5-thinking は claude-sonnet-4-5 に正規化されます。
これは以下を意味します：
- Quota Protection で
claude-sonnet-4-5をチェックする - 実際に
claude-sonnet-4-5-thinkingをリクエストする
それでも保護がマッチする（同じグループに属するため）。
期待される結果：あるアカウントの protected_models に claude-sonnet-4-5 が含まれている場合、claude-sonnet-4-5-thinking へのリクエストはそのアカウントを優先的に回避する。
ステップ 5：すぐに検証したい場合、「手動ウォームアップ」で 1 回 warmup をトリガー
なぜ 定期 Smart Warmup のスキャンサイクルは 10 分に 1 回（src-tauri/src/modules/scheduler.rs 参照）。すぐにリンクを検証したい場合、手動ウォームアップの方が直接的。
操作パス：Accounts ページを開き、ツールバーの「ウォームアップ」ボタンをクリック：
- アカウントを選択しない：全量ウォームアップをトリガー（
warm_up_all_accounts呼び出し） - アカウントを選択：選択したアカウントに 1 つずつウォームアップをトリガー（
warm_up_account呼び出し）
期待される結果：トーストが表示され、内容はバックエンドが返した文字列（例："Warmup task triggered ..."）に由来する。
チェックポイント ✅
- Accounts ページで各アカウントのモデルクォータパーセンテージが見える（クォータデータリンクが OK の証拠）
- Settings で Quota Protection / Smart Warmup を開き、設定を正常に保存できる
protected_modelsが「モデルレベル」制限であることを理解：1 つのアカウントが一部のモデルに対してのみ回避される可能性がある- warmup には 4 時間のクールダウンがあることを知っている：短時間で繰り返しウォームアップをクリックすると、「skipped/cooldown」関連のプロンプトが見える可能性がある
よくある落とし穴
1) Quota Protection を有効にしたが、ずっと有効にならない
最も一般的な原因：アカウントに quota データがない。保護ロジックはバックエンドでまず quota.models[] を読み取る必要があるため、閾値を判断（src-tauri/src/proxy/token_manager.rs 参照）。
ステップ 1 に戻り、まずクォータを更新してください。
2) なぜ少数のモデルしか「保護グループ」として扱われないのか？
TokenManager の target_model 正規化は「ホワイトリスト式」です：明確に列挙されたモデル名のみが標準 ID にマッピングされます（src-tauri/src/proxy/common/model_mapping.rs 参照）。
正規化後のロジックは：正規化後の名称（標準 ID または元のモデル名）を使ってアカウントの protected_models フィールドにマッチします。マッチ成功した場合、そのアカウントはスキップされます（src-tauri/src/proxy/token_manager.rs:555-560, 716-719 参照）。これは以下を意味します：
- ホワイトリスト内のモデル（例：
claude-sonnet-4-5-thinking）は標準 ID（claude-sonnet-4-5）に正規化され、その後protected_modelsに含まれるかを判断 - ホワイトリスト外のモデル正規化失敗時、元のモデル名にフォールバックし、依然として
protected_modelsにマッチする
つまり、クォータ保護判断は「すべてのモデル名」に有効ですが、ホワイトリスト内のモデルはまず正規化されます。
3) 手動/定期ウォームアップはなぜプロキシが実行されている必要があるのか？
ウォームアップリクエストは最終的にローカルプロキシの内部エンドポイントに打ち込みます：POST /internal/warmup（src-tauri/src/proxy/server.rs のルート、および src-tauri/src/proxy/handlers/warmup.rs の実装を参照）。プロキシサービスを起動しない場合、warmup は失敗します。
また、ウォームアップ呼び出しのポートは設定から来ます：proxy.port（設定読み取り失敗時、8045 にフォールバック、src-tauri/src/modules/quota.rs 参照）。
このレッスンのまとめ
- Quota Protection は「損切り」：閾値以下になるとモデルを
protected_modelsに書き込み、そのモデルをリクエストする際、優先的に回避 - Smart Warmup は「回復自己検査」：100% 時のみトリガー、10 分に 1 回スキャン、4 時間クールダウン
- 両方とも「クォータ更新」リンクに依存：まず
quota.models[]があってこそ、ガバナンスの基礎がある
次のレッスン予告
クォータガバナンスが解決するのは「どうより安定して使うか」。次のレッスンでは Proxy Monitor を続けて見ることを推奨し、リクエストログ、アカウントマッチ、モデルマッピングをすべて再生可能な証拠チェーンにします。
付録：ソースコード参考
クリックしてソースコードの位置を展開
更新日時：2026-01-23
| 機能 | ファイルパス | 行番号 |
|---|---|---|
| Quota Protection UI（閾値、モデルチェック、少なくとも 1 つ残す） | src/components/settings/QuotaProtection.tsx | 13-168 |
| Smart Warmup UI（有効化後デフォルトチェック、少なくとも 1 つ残す） | src/components/settings/SmartWarmup.tsx | 14-120 |
クォータガバナンス設定フィールド（quota_protection / scheduled_warmup） | src/types/config.ts | 54-94 |
デフォルト閾値とデフォルト設定（threshold_percentage: 10） | src/pages/Settings.tsx | 20-51 |
protected_models 書き込み/復元（閾値判断と永続化） | src-tauri/src/proxy/token_manager.rs | 254-467 |
リクエスト側クォータ保護フィルタリング（get_token(..., target_model)） | src-tauri/src/proxy/token_manager.rs | 470-674 |
保護グループ正規化（normalize_to_standard_id） | src-tauri/src/proxy/common/model_mapping.rs | 230-254 |
Smart Warmup 定期スキャン（10 分に 1 回 + 4 時間クールダウン + warmup_history.json） | src-tauri/src/modules/scheduler.rs | 11-221 |
手動ウォームアップコマンド（warm_up_all_accounts / warm_up_account） | src-tauri/src/commands/mod.rs | 167-212 |
ウォームアップ実装（内部エンドポイント /internal/warmup 呼び出し） | src-tauri/src/modules/quota.rs | 271-512 |
| 内部ウォームアップエンドポイント実装（リクエスト構築 + アップストリーム呼び出し） | src-tauri/src/proxy/handlers/warmup.rs | 3-220 |