Back to Details

chatgpt-codex-onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

🔐 ChatGPT / Codex OAuth Onboarding

🔐 ChatGPT/Codex OAuth接入流程

Use the user's existing ChatGPT or Codex subscription for 
gpt-5-codex
, 
gpt-5
, 
gpt-5-mini
access — without an API key.
The 
openai_oauth
tool stays built-in. This SKILL.md is the reference doc.
使用用户已有的ChatGPT或Codex订阅来访问
gpt-5-codex
、
gpt-5
、
gpt-5-mini
——无需API密钥。
openai_oauth
工具已内置，本SKILL.md为参考文档。

See also

另请参阅

  • skills/byok-custom-model/SKILL.md
    — for vendor-key BYOK setup (DIFFERENT mechanism, NOT OAuth)
  • config/context/references/model-onboarding.md
    — overall model-selection landscape
  • skills/byok-custom-model/SKILL.md
    — 基于供应商密钥的BYOK设置（机制不同，非OAuth方式）
  • config/context/references/model-onboarding.md
    — 整体模型选择概览

When to use this tool

何时使用此工具

✅ 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 
    custom_models
  • "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 request to sign in with their ChatGPT/Codex subscription triggers this flow.
✅ 适用场景：当用户明确说出以下任一表述时：
  • "使用我的ChatGPT账户登录"
  • "使用我的Codex订阅"
  • "连接我的ChatGPT Plus/Pro/团队版/企业版"
  • "使用OpenAI/ChatGPT登录"
❌ 请勿使用：
  • BYOK/基于API密钥的设置（"添加OpenAI API密钥"、"我有OpenAI密钥"）
  • 其他名称相似的供应商（Anthropic、Gemini、Qwen等）→ 使用
    custom_models
  • 无订阅上下文的"添加OpenAI模型"请求——先询问用户是想要OAuth（订阅）还是BYOK（API密钥）方式
⚠️ 名称相似的供应商（Codex、OpenAI、GPT）不能单独作为触发OAuth流程的信号。只有当用户明确请求使用其ChatGPT/Codex订阅登录时，才启动此流程。

Connect flow

连接流程

  1. Pre-check: call 
    openai_oauth(action="status")
    . If already connected, tell the user and stop.
  2. Start: call 
    openai_oauth(action="start")
    . The response contains: 
    • verification_url
      — show this to the user
    • user_code
      — show this to the user
    • pending_id
      — keep for the next step
  3. Display to user (both fields, clearly labeled): 
    Open this URL in your browser:
  <verification_url>
And enter this code:
  <user_code>
  4. Wait for the user to confirm they approved in the browser. Don't auto-loop on 
    poll
    — let the user say "I'm done" / "approved" first.
  5. Poll once: 
    openai_oauth(action="poll", pending_id=<id from step 2>)
    .
    • Success → 
      openai-codex/gpt-5-codex
      , 
      openai-codex/gpt-5
      , 
      openai-codex/gpt-5-mini
      appear in the model selector.
    • Pending → ask the user if they completed the browser step; poll again only on confirmation.
    • Failed → start over from step 2.
  6. Confirm to user: "Connected as <email>. You can switch with 
    /model openai-codex/gpt-5-codex
    ."
  1. 预检查：调用
    openai_oauth(action="status")
    。若已连接，告知用户并停止流程。
  2. 启动：调用
    openai_oauth(action="start")
    。返回结果包含： 
    • verification_url
      — 展示给用户
    • user_code
      — 展示给用户
    • pending_id
      — 留作下一步使用
  3. 展示给用户（两个字段需清晰标注）： 
    在浏览器中打开此链接：
  <verification_url>
并输入此验证码：
  <user_code>
  4. 等待用户确认他们已在浏览器中完成授权。不要自动循环调用
    poll
    ——需等用户说"我完成了"/"已授权"后再进行下一步。
  5. 轮询一次：
    openai_oauth(action="poll", pending_id=<步骤2中的id>)
    。
    • 成功 → 
      openai-codex/gpt-5-codex
      、
      openai-codex/gpt-5
      、
      openai-codex/gpt-5-mini
      会出现在模型选择器中。
    • 待处理 → 询问用户是否已完成浏览器端操作；仅在用户确认后再次轮询。
    • 失败 → 从步骤2重新开始。
  6. 向用户确认："已以<邮箱>身份连接。您可以通过
    /model openai-codex/gpt-5-codex
    切换模型。"

Actions reference

操作参考

actionrequiredpurpose
status
—Current state, email, account_id, token expiry
start
—Begin device-code flow → returns 
verification_url
+ 
user_code
+ 
pending_id
poll
pending_id
Check authorization status (call after user confirms approval)
logout
—Disconnect + remove credentials
refresh
—Force-refresh access token (debug; normally automatic)
models
(optional 
force
)		List available models from the OAuth endpoint
usage
(optional 
force
)		Subscription usage stats
force=true
on 
models
/ 
usage
bypasses the cache TTL.
action必填项用途
status
—查询当前状态、邮箱、账户ID、令牌过期时间
start
—启动设备码流程 → 返回
verification_url
+ 
user_code
+ 
pending_id
poll
pending_id
检查授权状态（用户确认授权后调用）
logout
—断开连接并移除凭证
refresh
—强制刷新访问令牌（用于调试；通常自动刷新）
models
（可选
force
）		列出OAuth端点提供的可用模型
usage
（可选
force
）		查询订阅使用统计数据
在
models
/
usage
中设置
force=true
会绕过缓存的生存时间（TTL）。

After connecting

连接后

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
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).
模型会以
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——绕过平台代理。订阅使用限制适用（而非平台的信用余额）。

Reauth

重新授权

Tokens auto-refresh via 
refresh_token
. If a 401 surfaces:
  1. openai_oauth(action="refresh")
    — try the manual refresh path.
  2. If still failing, 
    openai_oauth(action="logout")
    + restart from 
    start
    .
令牌会通过
refresh_token
自动刷新。若出现401错误：
  1. openai_oauth(action="refresh")
    — 尝试手动刷新路径。
  2. 若仍失败，执行
    openai_oauth(action="logout")
    + 从
    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.
  • 切勿将user_code粘贴到verification_url中。两者是分开的——用户必须在打开链接后手动输入验证码。
  • 切勿在无明确用户请求时启动流程。"我想使用ChatGPT"是可行的触发条件；"我有OpenAI密钥"则不行（这属于BYOK方式）。
  • 在start和poll步骤之间等待用户确认。自动轮询会浪费API调用并返回过时的"待处理"响应。