xAI OAuth Usage Checker

Hermes xAI Usage Checker

Hermesのcanonical OAuth credentialを使い、xAIの週間利用率とリセット時刻を読み取り専用で確認する。 credentialの変更、再認証、課金操作は行わず、モデル固有の上限だとも断定しない。

When to Use

• xAI OAuth / Grokの利用率、残量、リセット日時を聞かれたとき
• xai-oauth/grok-4.6がbillingまたはquota exhaustedになったとき
• quota回復後にHermesのfallbackやx_searchを再検証できるか判断するとき

Prerequisites

• Hermesのcanonical auth storeに有効なxai-oauth credentialがあること
• python3と、https://cli-chat-proxy.grok.comへのHTTPS接続が使えること
• ユーザーがxAI Billing endpointへのOAuth読み取り照会を承認済みであること。未承認なら先に確認する

How to Run

Hermesのterminalで、sanitized JSON出力を指定して実行する。

terminal(command='python3 "${HERMES_SKILL_DIR}/scripts/check_xai_usage.py" --json', timeout=30)

人間向け表示だけが必要な場合もterminalを使い、--jsonを外す。 通常表示とstderrはHERMES_LANGUAGE、次にHermesのdisplay.languageへ従う。日本語設定なら日本語、それ以外や設定取得失敗時は英語になる。JSONのキーとエラー文は英語固定。

実行ファイル: scripts/check_xai_usage.py

Quick Reference

Procedure

1. 依頼が利用枠の読み取り照会であり、認証変更や課金操作を含まないことを確認する。
2. How to Runのterminal呼び出しを一度実行する。redirect、login、logout、refresh、reset、top-upは行わない。
3. status: okなら、利用率、残量、period_end_jst、残り時間、product_usageだけをHermesの表示言語で簡潔に報告する。
4. remaining_percentが0でremaining_secondsが正なら、quota回復前として扱う。
5. status: errorなら、errorとhttp_statusだけを報告し、401/403でも自動再認証しない。
6. access token、refresh token、ID token、auth.jsonの内容、生のAPIレスポンスを表示・保存・回答へ含めない。

報告例:

xAI OAuthの週間枠は100%使用済みです。
リセットは2026-08-29 23:04 JST、残り約29時間3分です。
内訳: GrokBuild 100%。

Pitfalls

• billingの期間は統合された週間枠の場合がある。Grok 4.6固有のlimitとは断定しない。
• 残り時間は実行中に減る。回答ではperiod_end_jstを正本にし、残り時間は概算と明記する。
• リセット時刻を過ぎてもHermesがbillingのままなら、blind resetせず一度だけ再照会する。
• usage画面の表示がなくてもAPI照会結果を優先するが、失敗時は未確認として扱う。
• scriptはredirectを拒否する。別hostへAuthorization headerを送る代替実装に変更しない。

Verification

source checkoutでは、skill directory内でネットワークを使わない回帰テストを実行する。

python3 -m unittest discover -s tests -v

Hermesからインストールしたskillでは、ネットワークを使わないsmoke testを実行できる。

terminal(command='python3 "${HERMES_SKILL_DIR}/scripts/check_xai_usage.py" --help', timeout=30)

承認済みの場合だけHow to Runのlive照会も行い、status: ok、正しいsource_host、token fieldがないことを確認する。