xai-grok-onboarding

🟢 xAI OAuth オンボーディング

有効な xAI アカウント（X Premium、X Premium+、SuperGrok、SuperGrok Heavy のいずれか）を使用して、grok-4.3、grok-build-0.1、grok-4.20-* およびマルチエージェントモデルを利用できます。個別の API キーは不要です。

これは標準の OAuth 2.0（RFC 8628 Device Authorization Grant）であり、ベンダー独自のフローではありません。

ティア → モデルアクセス

auth.x.ai が発行する JWT には tier クレームが含まれており、ティアが高いほど /v1/models からより多くのモデルを利用できます。観測されたマッピング（xAI はこれを公式には公開していません）:

ティア	サブスクリプション	おおよそのモデルアクセス
1	X Premium（月額 $8）	grok-4.3 ベースライン
2	X Premium+（月額 $16）	+ grok-4.20-0309 バリアント
3	SuperGrok（月額 $30）	+ 推論モデル
4	SuperGrok Heavy（月額 $300）	+ grok-build-0.1 + マルチエージェント

status() はユーザーのティアを報告するため、どのモデルが利用可能かを把握できます。

これはスクリプトモードのスキルです — ツールは登録されません。このファイルを読み、bash ブロックからエクスポートを呼び出してください。

関連項目

• byok-custom-model スキル — ベンダーキーによる BYOK セットアップ用（console.x.ai から取得する xAI API キー、仕組みが異なります — トークン単位で課金され、サブスクリプションには紐付きません）
• chatgpt-codex-onboarding スキル — 同じパターンで、ChatGPT/Codex サブスクリプション用
• config/context/references/model-onboarding.md — モデル選択の全体像

バックエンドの互換性

このスキルは、プラットフォームイメージ内の core.xai_grok Python パッケージに依存しています（2026-05-22 出荷）。古いイメージでは、スキルは正常に読み込まれますが、すべてのパブリック関数が次を返します:

{
  "ok": false,
  "error": "xai_oauth_backend_unavailable",
  "detail": "ModuleNotFoundError: core.xai_grok not found in any of: [/app, /data/workspace/starchild-clawd]",
  "hint": "Update the platform image OR fall back to byok-custom-model with an xAI API key."
}

この応答が表示された場合は、再試行しないでください — プラットフォーム自体の更新が必要です。イメージの更新を待つか、console.x.ai から取得した API キーを使ってユーザーを byok-custom-model に誘導してください。

---

このスキルを使用する場面

✅ 使用する — ユーザーが次のいずれかを明示的に述べた場合:

• 「Grok / SuperGrok アカウントでサインインしたい」
• 「SuperGrok / X Premium サブスクリプションを使いたい」
• 「SuperGrok Heavy を接続したい」
• 「xAI / Grok でログインしたい」
• 「Grok Heavy サブスクリプションを使いたい」

❌ 使用しない — 次の場合:

• 「API キーで Grok を追加したい」/「xAI API キーを持っている」 → byok-custom-model（xAI テンプレート）を使用
• その他のベンダー（Anthropic、OpenAI、Gemini、Qwen など） → byok-custom-model を使用
• サブスクリプションに言及せず「Grok モデルを追加したい」 → どちらの経路を希望するか（サブスクリプション OAuth か API キー BYOK か）をユーザーに確認してください

この 2 つの経路は課金の面で排他的です。サブスクリプション OAuth はユーザーの月次クォータを使用し、BYOK API キーは console.x.ai のトークン単位の従量課金クレジットを使用します。

---

重要な事前確認 — アカウントゲートに関する注意

xAI には既知のバックエンドゲートがあり、有効な SuperGrok サブスクリプションがあっても一部のアカウントでは OAuth グラントが拒否されます。これは上流の xAI の動作であり、クライアントのバグではありません。症状:

• 確認ページは読み込まれるが、「Approve」をクリックすると、トークンエンドポイントから access_denied が返る
• Hermes Agent も issue #26847 で同様の事例を記録しています

poll() が AccountAccessDenied を返した場合:

1. ユーザーの SuperGrok サブスクリプションが有効であることを確認する（grok.com / 設定）
2. 新規のシークレットウィンドウではなく、すでにログイン済みのブラウザで確認 URL を試すよう提案する
3. それでも拒否される場合 → BYOK API キーの経路にフォールバックする（byok-custom-model スキル、xAI テンプレート、https://console.x.ai から取得したキー）

黙って再試行しないでください — ゲートはアカウントごとに決定的であり、再試行は時間の無駄です。

---

フロー

フローにはユーザーから見える 4 つのステップがあります。次のように進めます:

1. start() — 確認 URL を生成する

python3 - <<'EOF'
import json, sys
sys.path.insert(0, '/data/workspace/skills/xai-grok-onboarding')
from exports import start
print(json.dumps(start(), indent=2))
EOF

verification_url_with_code を返します — ユーザーにブラウザでこれを開き、（必要なら）ログインして Approve をクリックするよう伝えてください。

⚠️ poll() を呼び出す前に、ユーザーからの明示的な確認を待ってください。 早まってポーリングすると、「まだ保留中」の状態のためにトークンを浪費します。

2. poll() — 承認を確認する（ユーザーが「完了」と答えた後）

python3 - <<'EOF'
import json, sys
sys.path.insert(0, '/data/workspace/skills/xai-grok-onboarding')
from exports import poll
print(json.dumps(poll(), indent=2))
EOF

3 つの最終的な結果:

• status="connected" → 成功。切り替え先として default_model_id をユーザーに示します
• status="pending" → ユーザーがまだ承認していません。再ポーリングする前に確認を促してください
• ok=false で access_denied → 上記の「account gate」セクションを参照してください
• ok=false で expired → デバイスコードがタイムアウトしました（15 分）。start() をもう一度呼び出してください

3. 接続成功後 — ユーザーに伝える

poll() が status='connected' を返したら、最初に必ず行うことはユーザーに次のように伝えることです:

「接続に成功しました。ブラウザのページを更新してください — 再読み込みすると、新しい xai-grok/* モデルがモデルピッカーに表示されます。」

Web フロントエンドはモデル一覧をクライアント側でキャッシュしており、OAuth 接続の完了後に自動更新は行いません。手動でページを更新しないと、ユーザーは新しく利用可能になったモデルを確認できず、接続に失敗したと考えるでしょう。返信には必ずこの指示を含めてください — ピッカーが自動的に更新されると想定しないでください。

更新後、デフォルトのモデルは xai-grok/grok-4.3 です。その他の利用可能なモデルはサブスクリプションのティアによって異なります（SuperGrok Heavy では grok-build-0.1 が利用可能になります）。

切り替えるには: /model xai-grok/grok-4.3 を使用するか、ピッカーを使用します。

---

関数リファレンス

関数	引数	戻り値
status()	—	現在の認証情報の状態 + 利用可能なモデル + 有効期限
start()	—	デバイスコードのプロンプト: {verification_url_with_code, user_code, expires_in_seconds}
poll(pending_id=None)	オプションの pending_id	{status: connected/pending} + 認証情報
logout()	—	認証情報を削除 + エージェントキャッシュをフラッシュ
refresh()	—	アクセストークンを強制更新（デバッグ用。通常は自動）
models(force=False)	—	OAuth エンドポイントから利用可能なモデルを一覧表示

models の force=True はキャッシュの TTL をバイパスします。

すべての関数は、成功時は ok: True、失敗時は ok: False, error: "..." を含む dict を返します。

---

接続後

モデルは xai-grok/ プレフィックス付きで表示されます:

• xai-grok/grok-4.3 — 主要なチャットモデル（デフォルト）
• xai-grok/grok-build-0.1 — Grok Build コーディングモデル（SuperGrok Heavy ティアのみ）
• xai-grok/grok-4.20-0309-reasoning — 推論バリアント
• xai-grok/grok-4.20-0309-non-reasoning — より高速、推論なし
• xai-grok/grok-4.20-multi-agent-0309 — マルチエージェントバリアント（内部的に /v1/responses を使用）

ユーザーは /model xai-grok/grok-4.3 またはモデルピッカー UI で切り替えます。

レーンのルーティング（透過的）

プロバイダーはモデル ID に基づいて自動的にルーティングします:

• マルチエージェントモデル → https://api.x.ai/v1/responses（Responses API）
• その他すべての Grok モデル → https://api.x.ai/v1/chat/completions（OpenAI 互換）

ユーザーは各モデルがどの方言を使うかを知る必要はありません — 標準的な messages=[...] の形式を渡せばどちらでも動作します。マルチエージェントの場合、オプションの thinking={"effort": "low"|"medium"|"high"} で協調するエージェントの数を制御できます。

以降のチャット呼び出しは、OAuth ベアラーを使用して https://api.x.ai/v1 に直接アクセスします — プラットフォームのプロキシをバイパスします。サブスクリプションの使用制限が適用されます（プラットフォームのクレジット残高ではありません）。画像 / 動画モデル（grok-imagine-*）はチャットピッカーから除外されますが、画像生成ツールからアクセスできます。

---

xAI の OAuth 許可リスト — 「フロントエンドがログインを拒否した」最大の原因

重要な背景（独立した実装から検証済み、2026-05）: xAI のバックエンドは OAuth API サーフェス上に内部の許可リストを維持しており、ユーザーのサブスクリプションが有効でデバイスコードフロー自体が成功した場合でも、OAuth トークンに対して頻繁に HTTP 403 を返します。これは Hermes Agent（xAI OAuth トラブルシューティング）によって文書化されており、独立した OpenCode プラグインの作者によっても確認されています。これは当社のアダプターのバグではありません — PKCE フローに切り替えてもバイパスできません（どちらのグラントタイプも同じ許可リストに当たります）。

サブスクリプション階層 ↔ OAuth の利用可否（観測された傾向であり、保証ではありません）

サブスクリプション	価格	OAuth の典型的な結果
X Premium（X.com のみ）	$8 /月	❌ 多くの場合拒否される — 権利が不足しています
X Premium+（X アカウントを連携済み）	$16 /月	✅ 通常は動作します — xAI が X アカウント経由で自動連携します
SuperGrok（grok.com 直接）	$30 /月	⚠️ 結果が分かれる — ブロックされるユーザーもいれば、通るユーザーもいます
SuperGrok Heavy	$300 /月	✅ 確実に動作します

フローを開始する前の事前確認

ユーザーが単体の X Premium サブスクリプション（Premium+ ではない）または SuperGrok ベースのサブスクリプションを持っていて、フロントエンドで拒否されている場合は、まず次のことを順番に実行するよう伝えてください:

1. https://grok.com → Settings → Account → 「Connect your X Account」 に移動する（2 つの ID を連携し、xAI がサブスクリプションのステータスを確認できるようにします）
2. 連携する X アカウントが Premium / Premium+ のタグを持っているものであることを確認する
3. 連携後に一度 https://accounts.x.ai でサインアウトしてから再度サインインする（権利が更新されます）
4. デバイスコードフローを再試行する

報告されている「OAuth ログインが失敗する / デバイスコードが承認されない」ケースの大部分は、X アカウントの連携漏れに起因しています — 連携がないと xAI のバックエンドが Premium ステータスを確認できず、フロントエンドがデバイスコードを黙って拒否します。

事前確認後も OAuth が失敗する場合 → BYOK を推奨

コミュニティ（Hermes、OpenCode プラグインなど）での標準的な解決策は、OAuth と格闘するのをやめ、API キーに切り替えることです:

• XAI_API_KEY の経路は、OAuth の許可リストの対象外である別の xAI バックエンド（console.x.ai の従量課金）を使用します。
• ユーザーに https://console.x.ai でキーを取得するよう伝え、その後 xAI テンプレートで byok-custom-model スキルに誘導してください。セットアップは 2 分です。
• トレードオフ: BYOK はサブスクリプションのクォータを使う代わりに、別のウォレットからトークン単位で課金されます — ユーザーが意識的に選択できるよう、これを明確に説明してください。

私たちが行わないこと

• ❌ リファラーを偽装する / 別の既知のクライアント（Hermes、grok-cli など）になりすます — 権利の回避は利用規約に違反し、xAI が許可リストをさらに厳しくする可能性があります
• ❌ access_denied でデバイスコードフローを再試行する — 失敗し続けます。代わりに事前確認または BYOK を推奨してください
• ❌ ユーザーに Starchild のバグだと言う — これは私たちが覆せない xAI のアカウント制限の判断です

---

制限と BYOK フォールバック

xAI は OpenAI のように正確な 1 日あたりの上限や RPM を公開していません。OAuth 経由の Grok 利用における実際の状況は次のとおりです:

• 公開された具体的な数値はありません。 制限はフェアユースに基づきます — 短時間に大量の生成を行うと、xAI が一時的にスロットリングします。
• 階層が重要です。 Heavy（$300/月）はコンシューマー向けで最も高い上限を提供します — SuperGrok（$30）や X Premium+ を大幅に上回ります。標準的なテキスト/チャットでは、通常から高頻度の日常利用で上限に達することはめったにありません。
• 画像 / 動画 / 音声はより厳しいクォータがあります。 例えば Heavy ユーザーは 12 時間あたりおよそ 80 回以上の動画生成が可能ですが、ピーク負荷時にはこれらもスロットリングされる可能性があります。
• ソフトな上限のシグナル: ユーザーが xAI から 429 や「rate limit exceeded」のメッセージを見始めたら、その機能のフェアユース上限に達しています。待つか（制限は固定の毎日の時刻ではなく、ローリングウィンドウでリセットされます）、課金モードを切り替えてください。

BYOK への切り替えを提案すべきタイミング

ユーザーが予測可能な、支出ベースの大量アクセスを求めている場合 — または頻繁に制限に達している場合 — 通常の xAI API キーに切り替えられます:

1. https://console.x.ai でキーを取得する（従量課金、サブスクリプションとは別）
2. xAI テンプレートで byok-custom-model スキルを使用する
3. BYOK モデルはピッカーで OAuth モデルと並んで表示されます — ターンごとに切り替えられます

両方の経路は共存できます。ユーザーはリクエストごとに選択します。OAuth = サブスクリプションのクォータ（適切なデフォルト）。BYOK = より明確なレート制限 + トークン単位の課金（大量の自動化やコストの透明性を求める場合に適しています）。

エラー → アクション表

症状	原因	アクション
チャットでの 429 / 「rate limit exceeded」	OAuth のフェアユース上限に到達	ソフトリセットを待つか、このリクエストを BYOK に切り替える
OAuth 時の 403 / access_denied	xAI アカウントが制限されている	BYOK を使用する（上記のプリフライトのセクションを参照）
refresh() 後に 401 が繰り返し発生	トークンが失効 / サブスクリプションがキャンセル済み	logout() + 再起動、または BYOK に切り替える
503 / 上流の 5xx	xAI のインフラ障害	少し待って再試行する。BYOK も同じ上流を使用するため、解決にはならない

---

再認証

トークンは refresh_token を介して自動更新されます（アクセストークンの TTL は 6 時間 — Codex の 1 時間と比べて比較的余裕があります）。401 が発生した場合:

1. refresh() — 手動更新のパスを試す
2. それでも失敗する場合は、logout() + start() から再起動する

---

重要なルール

• ユーザーのために user_code を検証 URL フィールドに貼り付けないでください。 URL accounts.x.ai/oauth2/device?user_code=XXXX にはすでにコードが埋め込まれています — 単に開くだけです。
• ユーザーの明示的なリクエストなしにフローを開始しないでください。 「Grok を使いたい」には、サブスクリプションか API キーかの追加質問が必要です。「SuperGrok サブスクリプションを使う」なら十分です。
• start と poll の間はユーザーの確認を待ってください。 自動ポーリングは API 呼び出しを無駄にし、古い「pending」レスポンスを生成します。
• access_denied の際は、盲目的に再試行しないでください。 制限について説明し、BYOK へのフォールバックを提案してください。
• access_token / refresh_token をログに記録したりエコーしたりしないでください。 これらは永続的な認証情報です。エクスポートにも戻り値として含まれることはありません。