xai-grok-onboarding

🟢 xAI OAuth 接入

使用任意有效的 xAI 账号——X Premium、X Premium+、SuperGrok 或 SuperGrok Heavy——即可使用 grok-4.3、grok-build-0.1、grok-4.20-* 和多 Agent 模型。无需单独的 API 密钥。

这是标准的 OAuth 2.0（RFC 8628 设备授权许可），并非供应商自定义流程。

等级 → 模型访问权限

auth.x.ai 签发的 JWT 携带 tier 声明；等级越高，可从 /v1/models 访问的模型越多。以下是观察到的对应关系（xAI 未正式公布）：

等级	订阅	大致模型访问权限
1	X Premium（$8/月）	grok-4.3 基础版
2	X Premium+（$16/月）	+ grok-4.20-0309 变体
3	SuperGrok（$30/月）	+ 推理模型
4	SuperGrok Heavy（$300/月）	+ grok-build-0.1 + 多 Agent

status() 会报告用户的等级，让用户了解哪些模型可用。

这是一个脚本模式技能——未注册任何工具。读取此文件，然后从 bash 代码块中调用导出项。

另请参阅

• byok-custom-model 技能——用于使用供应商密钥的 BYOK 配置（来自 console.x.ai 的 xAI API 密钥，机制不同——按 token 计费，并非由订阅支持）
• chatgpt-codex-onboarding 技能——用于 ChatGPT/Codex 订阅的相同模式
• config/context/references/model-onboarding.md——模型选择全景概览

后端兼容性

此技能依赖平台镜像中的 core.xai_grok Python 包（随 2026-05-22 版本发布）。在较旧的镜像上，技能可以正常加载，但所有公共函数都会返回：

{
  "ok": false,
  "error": "xai_oauth_backend_unavailable",
  "detail": "ModuleNotFoundError: core.xai_grok not found in any of: [/app, /data/workspace/starchild-clawd]",
  "hint": "Update the platform image OR fall back to byok-custom-model with an xAI API key."
}

如果看到此响应，请勿重试——需要更新的是平台本身。请等待镜像刷新，或引导用户使用来自 console.x.ai 的 API 密钥配置 byok-custom-model。

---

何时使用此技能

✅ 在以下情况下使用：

• “使用我的 Grok / SuperGrok 账号登录”
• “使用我的 SuperGrok / X Premium 订阅”
• “连接 SuperGrok Heavy”
• “使用 xAI / Grok 登录”
• “使用我的 Grok Heavy 订阅”

❌ 以下情况请勿使用：

• “通过 API 密钥添加 Grok”/“我有 xAI API 密钥” → 使用 byok-custom-model（xAI 模板）
• 其他供应商（Anthropic、OpenAI、Gemini、Qwen 等）→ 使用 byok-custom-model
• 未提及订阅的“添加 Grok 模型”→ 询问用户希望选择哪种方式（订阅 OAuth 还是 API 密钥 BYOK）

这两种方式的计费互不兼容。订阅 OAuth 使用用户的月度额度；BYOK API 密钥使用 console.x.ai 的按 token 计费额度。

---

关键预检——留意账号限制

已知 xAI 后端存在限制，即使部分账号拥有有效的 SuperGrok 订阅，也会被拒绝 OAuth 授权。这是 xAI 上游行为，并非客户端错误。症状如下：

• 验证页面可以加载，但点击“批准”后，token 端点会返回 access_denied
• Hermes Agent 在 issue #26847 中也记录了相同问题

如果 poll() 返回 AccountAccessDenied：

1. 确认用户的 SuperGrok 订阅处于有效状态（grok.com / 设置）
2. 建议用户在已登录的浏览器中打开验证 URL（不要使用全新的无痕窗口）
3. 如果仍然被拒绝 → 改用 BYOK API 密钥方式（byok-custom-model 技能、xAI 模板，以及来自 https://console.x.ai 的密钥）

请勿悄悄重试——此限制对每个账号都是确定性的，重试只会浪费时间。

---

流程

整个流程包含 4 个用户可见步骤。按以下方式引导：

1. start() — 生成验证 URL

python3 - <<'EOF'
import json, sys
sys.path.insert(0, '/data/workspace/skills/xai-grok-onboarding')
from exports import start
print(json.dumps(start(), indent=2))
EOF

返回 verification_url_with_code——告知用户在浏览器中打开该链接、登录（如有需要），然后点击“批准”。

⚠️ 请等待用户明确确认后再调用 poll()。 过早轮询会浪费 token，反复得到“仍在等待”的状态。

2. poll() — 确认授权（用户表示“完成”后）

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

三种最终结果：

• status="connected" → 成功；向用户显示可供切换的 default_model_id
• status="pending" → 用户尚未授权；请他们确认后再重新轮询
• ok=false 且为 access_denied → 参见上文“账户门槛”部分
• ok=false 且为 expired → 设备码已超时（15 min）；再次调用 start()

3. 成功连接后 — 告知用户

当 poll() 返回 status='connected' 时，你必须首先告知用户：

“连接成功。请刷新浏览器页面——页面重新加载后，模型选择器中就会显示新的 xai-grok/* 模型。”

Web 前端会在客户端缓存模型列表，并且 OAuth 连接完成后不会自动刷新。如果用户不手动刷新页面，就看不到新开放的模型，并会以为连接失败。回复时务必包含这条说明——不要假设模型选择器会自行更新。

刷新后，默认模型为 xai-grok/grok-4.3。其他可用模型取决于订阅层级（SuperGrok Heavy 可解锁 grok-build-0.1）。

切换模型：/model xai-grok/grok-4.3，或使用模型选择器。

---

函数参考

函数	参数	返回值
status()	—	当前凭证状态 + 可用模型 + 过期时间
start()	—	设备码提示：{verification_url_with_code, user_code, expires_in_seconds}
poll(pending_id=None)	可选的 pending_id	{status: connected/pending} + 凭证信息
logout()	—	删除凭证 + 清空 Agent 缓存
refresh()	—	强制刷新访问令牌（用于调试；通常会自动刷新）
models(force=False)	—	列出 OAuth 端点中的可用模型

对 models 设置 force=True 会绕过缓存 TTL。

所有函数成功时都会返回包含 ok: True 的字典；失败时则返回包含 ok: False, error: "..." 的字典。

---

连接后

模型会以 xai-grok/ 为前缀显示：

• xai-grok/grok-4.3 — 主要聊天模型（默认）
• xai-grok/grok-build-0.1 — Grok Build 编码模型（仅限 SuperGrok Heavy 层级）
• xai-grok/grok-4.20-0309-reasoning — 推理变体
• xai-grok/grok-4.20-0309-non-reasoning — 速度更快，不进行推理
• xai-grok/grok-4.20-multi-agent-0309 — 多 Agent 变体（内部使用 /v1/responses）

用户可通过 /model xai-grok/grok-4.3 或模型选择器 UI 切换模型。

通道路由（透明处理）

提供程序会根据模型 ID 自动路由：

• 多 Agent 模型 → https://api.x.ai/v1/responses（Responses API）
• 所有其他 Grok 模型 → https://api.x.ai/v1/chat/completions（兼容 OpenAI）

用户无需了解各模型使用哪种方言——两者都可以使用标准的 messages=[...] 格式。对于多 Agent 模型，可选的 thinking={"effort": "low"|"medium"|"high"} 参数用于控制协作的 Agent 数量。

后续聊天调用会直接通过 OAuth bearer 访问 https://api.x.ai/v1，绕过平台代理。订阅用量限制适用（不受平台额度余额限制）。图像／视频模型（grok-imagine-*）会从聊天选择器中过滤掉，但仍可通过图像生成工具访问。

---

xAI 的 OAuth 允许列表 — 导致“前端拒绝我的登录”的首要原因

重要背景（经独立实现验证，2026-05）： xAI 后端在 OAuth API 接口上维护一个内部允许列表，即使用户订阅处于有效状态且设备码流程本身已成功，也经常会向 OAuth 令牌返回 HTTP 403。Hermes Agent 已对此进行记录（他们的 xAI OAuth 故障排除指南），独立 OpenCode 插件作者也已确认这一点。这不是我们适配器的 bug——切换到 PKCE 流程无法绕过该限制（两种授权类型都会经过同一个允许列表）。

订阅套餐 ↔ OAuth 可用性（基于观察，不作保证）

订阅	价格	OAuth 典型结果
X Premium（仅限 X.com）	$8 /mo	❌ 经常被拒绝 — 权益不足
X Premium+（已关联 X 账号）	$16 /mo	✅ 通常可用 — xAI 会通过 X 账号自动关联
SuperGrok（直接通过 grok.com 订阅）	$30 /mo	⚠️ 情况不一 — 部分用户被拦截，部分用户通过
SuperGrok Heavy	$300 /mo	✅ 稳定可用

开始流程前的预检

如果用户订阅的是独立的 X Premium（而非 Premium+）或基础版 SuperGrok，并遇到前端拒绝，请按以下顺序让他们先执行这些操作：

1. 前往 https://grok.com → Settings → Account → "Connect your X Account"（关联两个身份，以便 xAI 验证订阅状态）
2. 确认关联的 X 账号带有 Premium / Premium+ 标记
3. 关联后，在 https://accounts.x.ai 退出登录再重新登录一次（刷新权益状态）
4. 重试设备码流程

据报告，许多“OAuth 登录失败 / 设备码始终无法通过”的情况都源于未关联 X 账号 — 如果没有关联，xAI 后端无法验证 Premium 状态，而前端入口会静默拒绝设备码。

预检后 OAuth 仍然失败 → 建议使用 BYOK

社区中的常见解决方法（Hermes、OpenCode 插件等）是不要再折腾 OAuth，改用 API 密钥：

• XAI_API_KEY 路径使用不同的 xAI 后端（console.x.ai 按 Token 计费），不受 OAuth 允许列表限制。
• 让用户前往 https://console.x.ai 获取密钥，然后引导他们使用 byok-custom-model 技能和 xAI 模板。设置只需两分钟。
• 权衡之处：BYOK 从独立的钱包按 Token 计费，而不是使用订阅额度 — 请清楚说明这一点，让用户自行决定。

我们不会做的事

• ❌ 伪造来源标头 / 假装成其他已知客户端（Hermes、grok-cli 等）— 绕过权益检查违反服务条款（ToS），而且 xAI 可能会进一步收紧允许列表
• ❌ 在 access_denied 时重试设备码流程 — 仍会失败；建议改做预检或使用 BYOK
• ❌ 告诉用户这是 Starchild 的问题 — 这是我们无法更改的 xAI 账号访问限制决定

---

限制与 BYOK 备用方案

xAI 没有像 OpenAI 那样公布确切的每日上限或每分钟请求数（RPM）。OAuth 支持的 Grok 使用情况大致如下：

• 没有公布的硬性数值。 限制基于公平使用 — 如果你在短时间内生成大量内容，xAI 会暂时限流。
• 套餐等级很重要。 Heavy（$300/mo）提供最高的消费者使用上限 — 明显高于 SuperGrok（$30）或 X Premium+。正常到较重的日常文本 / 聊天使用很少会触及上限。
• 图片 / 视频 / 语音的配额更严格。 例如，Heavy 用户每 12 小时大约可以生成 80+ 个视频，但在负载高峰期间仍可能被限流。
• 软性上限信号： 如果用户开始看到 xAI 返回的 429 或“rate limit exceeded”消息，说明该功能已触及公平使用上限。等待限制重置（限制按滚动时间窗口重置，而非固定的每日时钟）或切换计费方式。

何时建议切换到 BYOK

如果用户希望获得可预测、按支出计费的大量访问权限 — 或者经常触及使用限制 — 可以切换到常规 xAI API 密钥：

1. 前往 https://console.x.ai 获取密钥（按 Token 计费，与订阅分开）
2. 使用 byok-custom-model 技能和 xAI 模板
3. BYOK 模型会与 OAuth 模型一同显示在选择器中 — 可按轮次切换

两种方式可以共存；用户可以针对每个请求自行选择。OAuth = 订阅额度（适合作为默认方式）。BYOK = 更明确的速率限制 + 按 Token 计费（适合大量自动化，或希望清楚了解成本的情况）。

错误 → 操作对照表

症状	原因	操作
聊天时出现 429 / "rate limit exceeded"	触及 OAuth 公平使用上限	等待限制自动解除，或将此请求切换为 BYOK
OAuth 授权时出现 403 / access_denied	xAI 账户受到限制	使用 BYOK（参见上面的预检查部分）
refresh() 后反复出现 401	令牌已撤销 / 订阅已取消	调用 logout() 并重启，或切换为 BYOK
上游出现 503 / 5xx	xAI 基础设施问题	稍后重试。BYOK 使用相同的上游服务，无法解决问题

---

重新授权

令牌会通过 refresh_token 自动刷新（访问令牌 TTL 为 6h——相比 Codex 的 1h 相当宽裕）。如果出现 401：

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

---

关键规则

• 绝不要替用户将 user_code 粘贴到验证 URL 输入框中。 URL accounts.x.ai/oauth2/device?user_code=XXXX 已包含该代码——直接打开即可。
• 未经用户明确请求，绝不要启动此流程。“我想使用 Grok”还需要追问用户选择订阅还是 API 密钥；“使用我的 SuperGrok 订阅”则已足够。
• 在 start 和 poll 之间等待用户确认。 自动轮询会浪费 API 调用，并产生过时的“pending”响应。
• 遇到 access_denied 时，切勿盲目重试。 说明账户限制，并建议使用 BYOK 作为替代方案。
• 绝不要记录或回显 access_token / refresh_token。 它们是持久凭证。导出函数的返回值也绝不会包含它们。