🔐 ChatGPT / Codex OAuth Onboarding

Use the user's existing ChatGPT or Codex subscription for gpt-5-codex, gpt-5, gpt-5-mini access — without an API key.

This is a script-mode skill — no tools registered. Read this file, then call the exports from a bash block.

When to use this skill

✅ Use when the user EXPLICITLY says one of:

"Sign in with my ChatGPT account"
"Use my Codex subscription"
"Connect my ChatGPT Plus / Pro / Team / Enterprise"
"Login with OpenAI / ChatGPT"

❌ Do NOT use for:

BYOK / API-key-based setup ("Add OpenAI API key", "I have an OpenAI key")
Other vendors that sound similar (Anthropic, Gemini, Qwen, etc.) → use byok-custom-model
"Add the OpenAI model" without subscription context — ASK first whether they want OAuth (subscription) or BYOK (API key)

⚠️ Vendor names that sound similar (Codex, OpenAI, GPT) are NOT a signal to start OAuth on their own. Only an explicit user mention of "subscription / sign in / login with ChatGPT" qualifies.

---

Onboarding flow

status — check if a credential already exists (resume vs fresh).
start — get a verification URL + user code from OpenAI; persisted to disk.
Tell the user: open the URL in a browser, log in to their ChatGPT / Codex account, and enter the code. Do NOT auto-poll.
Wait for the user to confirm they approved the device.
poll — finalize the OAuth handshake; on success, the new model becomes available.

If poll returns status='pending', the user hasn't finished yet — wait for them, then poll again. Don't loop poll automatically.

---

Script usage

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

After the user approves:

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

---

Functions

Function	Required args	Purpose
`status()`	—	Inspect current OAuth state, expiry, model list
`start()`	—	Begin device-code flow → verification_url + user_code
`poll(pending_id=None)`	—	Check authorization (call after user confirms approval)
`logout()`	—	Disconnect + remove credentials
`refresh()`	—	Force-refresh access token (debug; normally automatic)
`models(force=False)`	—	List available models from the OAuth endpoint
`usage(force=False)`	—	Subscription usage stats

force=True on models / usage bypasses the cache TTL.

All functions return a dict with ok: True on success or ok: False, error: "..." on failure.

---

After connecting

When poll() returns status='connected', the first thing you must do is tell the user:

"Connection successful. Please refresh your browser page — once it reloads, the new openai-codex/* models will appear in the model picker."

The web frontend caches the model list client-side and does not auto-refresh after an OAuth connect completes. Without a manual page refresh the user will not see their newly available models and will think the connection failed. Always include this instruction in your reply — do not assume the picker updates on its own.

Models appear with the openai-codex/ prefix:

openai-codex/gpt-5-codex — primary
openai-codex/gpt-5 — full GPT-5
openai-codex/gpt-5-mini — smaller / faster

After refresh, the user switches via /model openai-codex/gpt-5-codex or the model picker UI.

Subsequent calls hit OpenAI directly using the OAuth token — bypasses the platform proxy. Subscription usage limits apply (not the platform's credit balance).

---

Reauth

Tokens auto-refresh via refresh_token. If a 401 surfaces:

refresh() — try the manual refresh path.
If still failing, logout() + restart from start().

---

Critical rules

Never paste user_code in the verification_url. They're separate — user must enter the code manually after opening the URL.
Never start the flow without explicit user request. "I want to use ChatGPT" is enough; "I have an OpenAI key" is NOT (that's BYOK).
Wait for user confirmation between start and poll. Auto-polling wastes API calls and gives stale "pending" responses.