chatgpt-codex-onboarding

Q: How do I install chatgpt-codex-onboarding?

Run npx skills add https://github.com/starchild-ai-agent/official-skills --skill chatgpt-codex-onboarding in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/chatgpt-codex-onboarding/ (personal) or .claude/skills/chatgpt-codex-onboarding/ (project).

by starchild-ai-agentBackend & APIs

Connect a ChatGPT or Codex subscription via OAuth device-code login. Use when the user wants to sign in with their ChatGPT Plus, Pro, or Team account (e.g. "use my Codex subscription", "log in with ChatGPT").

Installs: 2.5K
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/starchild-ai-agent/official-skills --skill chatgpt-codex-onboarding

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads chatgpt-codex-onboarding automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

🔐 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.

FAQ

What does the chatgpt-codex-onboarding skill do?

How do I install chatgpt-codex-onboarding?

Run npx skills add https://github.com/starchild-ai-agent/official-skills --skill chatgpt-codex-onboarding in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/chatgpt-codex-onboarding/ (personal) or .claude/skills/chatgpt-codex-onboarding/ (project).

Which AI agents can use chatgpt-codex-onboarding?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is chatgpt-codex-onboarding safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains chatgpt-codex-onboarding?

It is published by starchild-ai-agent in starchild-ai-agent/official-skills. It has 2,521 recorded installs.