chatgpt-codex-onboarding

🔐 ChatGPT / Codex OAuth オンボーディング

ユーザーが既に持っている ChatGPT または Codex のサブスクリプション を使って、API キーなしで gpt-5-codex、gpt-5、gpt-5-mini にアクセスできます。

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

関連項目

• byok-custom-model スキル — ベンダーキーによる BYOK セットアップ向け（異なる仕組みであり、OAuth ではありません）
• config/context/references/model-onboarding.md — モデル選択の全体的な概要

---

このスキルを使う場面

✅ ユーザーが次のいずれかを 明示的に 言った場合に 使用 します:

• 「自分の ChatGPT アカウントでサインインしたい」
• 「自分の Codex サブスクリプションを使いたい」
• 「自分の ChatGPT Plus / Pro / Team / Enterprise を接続したい」
• 「OpenAI / ChatGPT でログインしたい」

❌ 次の場合には 使用しないでください:

• BYOK / API キーベースのセットアップ（「OpenAI API キーを追加」「OpenAI のキーを持っている」）
• 似た響きの他ベンダー（Anthropic、Gemini、Qwen など）→ byok-custom-model を使用
• サブスクリプションの文脈がない「OpenAI モデルを追加」— まず OAuth（サブスクリプション）と BYOK（API キー）のどちらを希望するかを確認してください

⚠️ 似た響きのベンダー名（Codex、OpenAI、GPT）は、それだけで OAuth を開始する 信号にはなりません。ユーザーが「サブスクリプション / サインイン / ChatGPT でログイン」と明示的に言及した場合のみ該当します。

---

オンボーディングの流れ

1. status — 認証情報が既に存在するか確認します（再開か新規か）。
2. start — OpenAI から検証 URL と user code を取得し、ディスクに永続化します。
3. ユーザーに伝えます: ブラウザで URL を開き、自分の ChatGPT / Codex アカウントにログインして、コードを入力してください。自動ポーリングはしないでください。
4. ユーザーがデバイスを承認したことを確認するまで待ちます。
5. poll — OAuth ハンドシェイクを完了します。成功すると、新しいモデルが利用可能になります。

poll が status='pending' を返した場合、ユーザーはまだ完了していません — ユーザーを待ってから、再度 poll してください。poll を自動でループしないでください。

---

スクリプトの使用法

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/chatgpt-codex-onboarding")
from exports import status, start, poll, logout, refresh, models, usage

# Check current state
print(json.dumps(status(), indent=2))

# Start a flow
result = start()
print(f"Open: {result['verification_url']}\nCode: {result['user_code']}")
EOF

ユーザーが承認した後:

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

---

関数

関数	必須引数	目的
status()	—	現在の OAuth 状態、有効期限、モデル一覧を確認
start()	—	デバイスコードフローを開始 → verification_url + user_code
poll(pending_id=None)	—	認可を確認（ユーザーが承認を確認した後に呼び出し）
logout()	—	切断 + 認証情報を削除
refresh()	—	アクセストークンを強制的に更新（デバッグ用、通常は自動）
models(force=False)	—	OAuth エンドポイントから利用可能なモデルを一覧表示
usage(force=False)	—	サブスクリプションの使用状況

models / usage で force=True を指定すると、キャッシュの TTL をバイパスします。

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

---

接続後

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

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

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

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

• openai-codex/gpt-5-codex — プライマリ
• openai-codex/gpt-5 — フルの GPT-5
• openai-codex/gpt-5-mini — より小型 / 高速

更新後、ユーザーは /model openai-codex/gpt-5-codex またはモデルピッカー UI で切り替えます。

以降の呼び出しは OAuth トークンを使って OpenAI に直接アクセスします — プラットフォームのプロキシをバイパスします。サブスクリプションの使用制限が適用されます（プラットフォームのクレジット残高ではありません）。

---

再認証

トークンは refresh_token によって自動更新されます。401 が発生した場合:

1. refresh() — 手動更新パスを試します。
2. それでも失敗する場合は、logout() してから start() で最初からやり直します。

---

重要なルール

• verification_url に user_code を絶対に貼り付けないでください。 これらは別物です — ユーザーは URL を開いた後、コードを手動で入力する必要があります。
• ユーザーの明示的なリクエストなしにフローを開始しないでください。 「ChatGPT を使いたい」は十分ですが、「OpenAI キーを持っている」はそうではありません(それは BYOK です)。
• start と poll の間はユーザーの確認を待ってください。 自動ポーリングは API 呼び出しを無駄にし、古い「pending」レスポンスを返します。