chatgpt-codex-onboarding

🔐 ChatGPT / Codex OAuth 接入指南

使用用户现有的 ChatGPT 或 Codex 订阅，访问 gpt-5-codex、gpt-5、gpt-5-mini，无需 API 密钥。

这是一个脚本模式技能——未注册任何工具。阅读此文件，然后在 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 登录 / 登录 ChatGPT”才符合条件。

---

接入流程

1. status——检查凭据是否已存在（继续现有流程还是重新开始）。
2. start——从 OpenAI 获取验证 URL 和用户代码；信息会保存到磁盘。
3. 告知用户：在浏览器中打开该 URL，登录 ChatGPT / Codex 账号，然后输入代码。不要自动轮询。
4. 等待用户确认已批准此设备。
5. poll——完成 OAuth 握手；成功后，新模型即可使用。

如果 poll 返回 status='pending'，表示用户尚未完成操作——等待用户完成，然后再次轮询。不要自动循环轮询。

---

脚本用法

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: "..."。

---

连接后

当 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 或模型选择器界面切换模型。

后续调用会使用 OAuth 令牌直接访问 OpenAI，绕过平台代理。适用订阅用量限制（而非平台的额度余额）。

---

重新授权

令牌会通过 refresh_token 自动刷新。如果出现 401：

1. refresh()——尝试手动刷新。
2. 如果仍然失败，运行 logout()，然后从 start() 重新开始。

---

关键规则

• 绝不要将 user_code 粘贴到 verification_url 中。 两者是分开的——用户打开 URL 后必须手动输入代码。
• 未经用户明确请求，绝不要启动流程。“我想使用 ChatGPT”就足够了；“我有 OpenAI 密钥”不算（这是 BYOK）。
• 在 start 和 poll 之间等待用户确认。 自动轮询会浪费 API 调用，并返回过时的“待处理”响应。