xai-grok-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🟢 xAI OAuth Onboarding

🟢 xAI OAuth 账户接入

Use any active xAI account — X Premium, X Premium+, SuperGrok, or SuperGrok Heavy — for

grok-4.3

grok-build-0.1

grok-4.20-*

and multi-agent models. No separate API key needed.

This is standard OAuth 2.0 (RFC 8628 Device Authorization Grant), not a vendor-custom flow.

可使用任何有效的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设备授权许可）流程，并非厂商自定义流程。

Tier → model access

订阅等级 → 模型权限

The JWT issued by

auth.x.ai

carries a

tier

claim; higher tiers unlock more models from

/v1/models

. Observed mapping (xAI does not publish this officially):

Tier	Subscription	Approx. model access
1	X Premium ($8/mo)	grok-4.3 baseline
2	X Premium+ ($16/mo)	+ grok-4.20-0309 variants
3	SuperGrok ($30/mo)	+ reasoning models
4	SuperGrok Heavy ($300/mo)	+ grok-build-0.1 + multi-agent

status()

reports the user's tier so they know which models will be available.

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

bash

block.

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

代码块中调用导出的函数。

When to use this skill

何时使用此技能

✅ Use when the user EXPLICITLY says one of:

"Sign in with my Grok / SuperGrok account"
"Use my SuperGrok / X Premium subscription"
"Connect SuperGrok Heavy"
"Login with xAI / Grok"
"Use my Grok Heavy subscription"

❌ Do NOT use for:

"Add Grok via API key" / "I have an xAI API key" → use
```
byok-custom-model
```
(the xAI template)
Other vendors (Anthropic, OpenAI, Gemini, Qwen, etc.) → use
```
byok-custom-model
```
"Add the Grok model" without subscription mention → ASK the user which path they want (subscription OAuth vs. API key BYOK)

The two paths are mutually exclusive billing-wise. Subscription OAuth uses the user's monthly quota; BYOK API key uses console.x.ai pay-per-token credits.

✅ 适用场景：当用户明确提及以下内容之一时：

“使用我的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 vs API密钥BYOK）

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

Critical preflight — account gate awareness

关键预检查 — 账户限制说明

xAI has a known backend gate that denies OAuth grants for some accounts even with an active SuperGrok subscription. This is upstream xAI behavior, not a client bug. Symptoms:

Verification page loads, but clicking "Approve" returns
```
access_denied
```
from the token endpoint
Hermes Agent has documented the same in issue #26847

poll()

returns

AccountAccessDenied

Verify the user's SuperGrok subscription is active (grok.com / settings)
Suggest they try the verification URL in their already-logged-in browser (not a fresh incognito)
If still denied → fall back to BYOK API key path (
```
byok-custom-model
```
skill, xAI template, key from https://console.x.ai)

Do NOT silently retry — the gate is deterministic per account, retrying wastes time.

xAI存在一个已知的后端限制，即使账户拥有有效的SuperGrok订阅，部分账户仍会被拒绝OAuth授权。这是xAI上游的行为，并非客户端bug。常见症状：

验证页面加载正常，但点击“批准”后，令牌端点返回
```
access_denied
```
Hermes Agent已在issue #26847中记录此问题

如果

poll()

AccountAccessDenied

：

确认用户的SuperGrok订阅处于活跃状态（访问grok.com / 设置页面）
建议用户在已登录的浏览器中打开验证链接（不要使用全新的隐身窗口）
若仍被拒绝 → 切换到BYOK API密钥方式（
```
byok-custom-model
```
技能，xAI模板，密钥来自https://console.x.ai）

请勿静默重试——该限制对每个账户是确定性的，重试只会浪费时间。

Flow

流程

The flow has 4 user-visible steps. Drive it like this:

该流程包含4个用户可见步骤，操作方式如下：

1. start() — generate the verification URL

1. start() — 生成验证链接

bash

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

Returns

verification_url_with_code

— tell the user to open it in their browser, log in (if needed), and click Approve.

⚠️ Wait for explicit user confirmation before calling poll(). Polling too eagerly burns tokens for a "still pending" state.

bash

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()前，请等待用户明确确认。 过早轮询会消耗令牌，返回“仍待处理”状态。

2. poll() — confirm approval (after the user says "done")

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

bash

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

Three terminal outcomes:

```
status="connected"
```
→ success; show the user
```
default_model_id
```
to switch to
```
status="pending"
```
→ user hasn't approved yet; ask them to confirm before re-polling
```
ok=false
```
with
```
access_denied
```
→ see "account gate" section above
```
ok=false
```
with
```
expired
```
→ device code timed out (15 min); call
```
start()
```
again

bash

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分钟）；重新调用
```
start()
```

3. After successful connect — tell the user

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

The frontend model picker refreshes after connect. The default model is

xai-grok/grok-4.3

. Other available models depend on the subscription tier (SuperGrok Heavy unlocks

grok-build-0.1

To switch:

/model xai-grok/grok-4.3

or use the picker.

连接成功后，前端模型选择器会刷新。默认模型为

xai-grok/grok-4.3

。其他可用模型取决于订阅等级（SuperGrok Heavy可解锁

grok-build-0.1

）。

切换模型：使用

/model xai-grok/grok-4.3

命令或模型选择器。

Function reference

函数参考

Function	Args	Returns
`status()`	—	Current credential state + available models + expiry
`start()`	—	Device code prompt: `{verification_url_with_code, user_code, expires_in_seconds}`
`poll(pending_id=None)`	optional `pending_id`	`{status: connected/pending}` + credential info
`logout()`	—	Delete credential + flush agent cache
`refresh()`	—	Force-refresh access token (debug; normally automatic)
`models(force=False)`	—	List available models from the OAuth endpoint

force=True

models

bypasses the cache TTL.

All functions return a dict with

ok: True

on success or

ok: False, error: "..."

on failure.

函数	参数	返回值
`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: "..."

。

After connecting

连接成功后

Models surface with the

xai-grok/

prefix:

```
xai-grok/grok-4.3
```
— primary chat model (default)
```
xai-grok/grok-build-0.1
```
— Grok Build coding model (SuperGrok Heavy tier only)
```
xai-grok/grok-4.20-0309-reasoning
```
— reasoning variant
```
xai-grok/grok-4.20-0309-non-reasoning
```
— faster, no reasoning
```
xai-grok/grok-4.20-multi-agent-0309
```
— multi-agent variant (uses /v1/responses internally)

User switches via

/model xai-grok/grok-4.3

or the model picker UI.

模型会以

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切换模型。

Lane routing (transparent)

路由自动分配（透明化）

The provider auto-routes based on model id:

Multi-agent models →
```
https://api.x.ai/v1/responses
```
(Responses API)
All other Grok models →
```
https://api.x.ai/v1/chat/completions
```
(OpenAI-compatible)

Users do not need to know which dialect each model speaks — passing the standard

messages=[...]

shape works for both. For multi-agent, an optional

thinking={"effort": "low"|"medium"|"high"}

controls how many agents collaborate.

Subsequent chat calls hit

https://api.x.ai/v1

directly using the OAuth bearer — bypasses the platform proxy. Subscription usage limits apply (not the platform credit balance). Image / video models (

grok-imagine-*

) are filtered out of the chat picker but accessible via image generation tools.

提供商会根据模型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令牌访问

https://api.x.ai/v1

——绕过平台代理。订阅使用限制适用（而非平台信用余额）。图像/视频模型（

grok-imagine-*

）会从聊天选择器中过滤，但可通过图像生成工具访问。

Limits & BYOK fallback

限制与BYOK备选方案

xAI does not publish exact daily caps or RPM the way OpenAI does. Practical reality for OAuth-backed Grok usage:

No published hard numbers. Limits are fair-use based — xAI throttles temporarily if you generate massive volume in a short window.
Tier matters. Heavy ($300/mo) gives the highest consumer ceiling — significantly above SuperGrok ($30) or X Premium+. Standard text/chat rarely hits the cap for normal-to-heavy daily use.
Image / video / voice have tighter quotas. E.g. Heavy users get roughly ~80+ video generations per 12 hours, but these can still throttle during peak load.
Soft ceiling signal: if the user starts seeing
```
429
```
or "rate limit exceeded" messages from xAI, they've hit the fair-use ceiling for that feature. Wait it out (limits reset on a rolling window, not a fixed daily clock) or switch billing modes.

xAI并未像OpenAI那样公布确切的每日限额或请求速率（RPM）。基于OAuth的Grok使用实际情况：

无公开硬限制。限制基于公平使用原则——如果短时间内生成大量内容，xAI会暂时限流。
等级至关重要。Heavy等级（300美元/月）的使用上限最高——显著高于SuperGrok（30美元/月）或X Premium+。对于正常到高频的日常使用，标准文本/聊天功能很少会触及上限。
图像/视频/语音功能的配额更严格。例如，Heavy等级用户每12小时约可生成80+个视频，但在高峰时段仍可能被限流。
软上限信号：如果用户开始收到xAI返回的
```
429
```
或“请求速率超出限制”消息，说明已触及该功能的公平使用上限。等待限制重置（限制按滚动窗口重置，而非固定每日时间）或切换计费方式。

When to suggest switching to BYOK

何时建议切换到BYOK

If the user wants predictable, spend-based high-volume access — or if they're hitting limits often — they can switch to a regular xAI API key:

Get a key at https://console.x.ai (pay-per-token, separate from subscription)
Use
```
byok-custom-model
```
skill with the xAI template
BYOK models appear alongside OAuth models in the picker — switch per turn

Both paths can coexist; the user picks per request. OAuth = subscription quota (good default). BYOK = clearer rate limits + per-token billing (good for heavy automation or when you want cost transparency).

如果用户需要可预测、基于消费的高容量访问——或经常触及限制——可切换到常规xAI API密钥：

在https://console.x.ai获取密钥（按token计费，与订阅分离）
使用
```
byok-custom-model
```
技能及xAI模板
BYOK模型会与OAuth模型一同出现在选择器中——可按请求切换

两种方式可共存；用户可按需选择。OAuth = 订阅配额（推荐默认）。BYOK = 更清晰的速率限制 + 按token计费（适合高负载自动化或需要成本透明的场景）。

Error → action table

错误→操作对照表

Symptom	Cause	Action
`429` / "rate limit exceeded" on chat	OAuth fair-use ceiling hit	Wait for soft reset, or switch this request to BYOK
`403` / `access_denied` at OAuth time	xAI account gated	Use BYOK (see preflight section above)
Repeated `401` after `refresh()`	Token revoked / subscription canceled	`logout()` + restart, or switch to BYOK
`503` / 5xx upstream	xAI infra issue	Retry shortly. BYOK uses the same upstream, won't help

症状	原因	操作
聊天时返回 `429` /“请求速率超出限制”	触及OAuth公平使用上限	等待软重置，或切换到BYOK方式处理该请求
OAuth阶段返回 `403` / `access_denied`	xAI账户被限制	使用BYOK方式（参考上述预检查部分）
调用 `refresh()` 后仍反复返回 `401`	令牌被撤销/订阅已取消	`logout()` + 从 `start()` 重新开始，或切换到BYOK方式
返回 `503` /5xx上游错误	xAI基础设施问题	稍后重试。BYOK使用相同上游服务，无法解决此问题

Reauth

重新授权

Tokens auto-refresh via

refresh_token

(6h access token TTL — relatively generous vs Codex's 1h). If a 401 surfaces:

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

令牌会通过

refresh_token

自动刷新（访问令牌TTL为6小时——相比Codex的1小时更为宽松）。如果出现401错误：

调用
```
refresh()
```
——尝试手动刷新令牌
若仍失败，执行
```
logout()
```
+ 从
```
start()
```
重新开始

Critical rules

关键规则

Never paste user_code into the verification URL field for the user. The URL
```
accounts.x.ai/oauth2/device?user_code=XXXX
```
already embeds the code — just open it.
Never start the flow without explicit user request. "I want to use Grok" needs a follow-up question about subscription vs. API key; "use my SuperGrok subscription" is enough.
Wait for user confirmation between
start
and
poll
. Auto-polling wastes API calls and produces stale "pending" responses.
On
access_denied
, do NOT retry blindly. Explain the gate, suggest BYOK fallback.
Never log or echo the access_token / refresh_token. They're persistent credentials. The exports never include them in return values either.

切勿为用户将user_code粘贴到验证链接的输入框中。链接
```
accounts.x.ai/oauth2/device?user_code=XXXX
```
已嵌入代码——直接打开即可。
切勿在未得到用户明确请求时启动流程。“我想使用Grok”需要进一步询问用户是采用订阅还是API密钥方式；“使用我的SuperGrok订阅”则足够明确。
在
start
和
poll
之间等待用户确认。自动轮询会浪费API调用并返回过时的“待处理”响应。
出现
access_denied
时，切勿盲目重试。向用户说明限制情况，建议使用BYOK备选方案。
切勿记录或回显access_token/refresh_token。它们是持久凭证。导出函数也不会在返回值中包含这些内容。

xai-grok-onboarding

Original

Translation

🟢 xAI OAuth Onboarding

🟢 xAI OAuth 账户接入

Tier → model access

订阅等级 → 模型权限

See also

相关参考

When to use this skill

何时使用此技能

Critical preflight — account gate awareness

关键预检查 — 账户限制说明

Flow

流程

1. start() — generate the verification URL

1. start() — 生成验证链接

2. poll() — confirm approval (after the user says "done")

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

3. After successful connect — tell the user

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

Function reference

函数参考

After connecting

连接成功后

Lane routing (transparent)

路由自动分配（透明化）

Limits & BYOK fallback

限制与BYOK备选方案

When to suggest switching to BYOK

何时建议切换到BYOK

Error → action table

错误→操作对照表

Reauth

重新授权

Critical rules

关键规则