用途:让用户用现有 xAI 订阅账号(X Premium、X Premium+、SuperGrok、SuperGrok Heavy)以 OAuth 2.0 设备码授权方式(RFC 8628)登录,从而使用 grok-4.3、grok-build-0.1、grok-4.20-* 及多智能体模型,无需单独 API Key。仅当用户明确提到用 Grok/SuperGrok 订阅登录时使用;若用户说“用 API Key 添加 Grok”或用其他厂商模型,应改用 byok-custom-model。
主要能力:提供 status、start、poll、logout、refresh、models 等函数。start() 返回 verification_url_with_code,用户打开并点击 Approve;poll() 返回 connected、pending 或失败。连接后模型以 xai-grok/ 前缀出现,默认 xai-grok/grok-4.3,可用 /model 或选择器切换。订阅层级影响可用模型,status() 会报告用户层级。多智能体模型走 /v1/responses,其余走兼容 OpenAI 的 /v1/chat/completions,调用方可传标准 messages。
使用方式:脚本模式,无注册工具。例如在 bash 中执行 python3,把技能目录加入 sys.path,import exports 后调用函数。start 与 poll 之间须等待用户明确确认,不要自动轮询。连接成功务必提示用户手动刷新浏览器页面,否则模型选择器不会更新。成功后说默认模型 id,切换用 /model xai-grok/grok-4.3。
限制:依赖平台镜像内的 core.xai_grok 包(2026-05-22 起提供),旧镜像所有函数返回 xai_oauth_backend_unavailable,此时不要重试,应更新镜像或改用 API Key。xAI 后端对 OAuth 有内部允许清单,部分账号即使订阅有效也会返回 403 / access_denied,属上游账号门控,不是客户端缺陷,切换 PKCE 也无法绕过。遇到该情况可先按顺序做预检(在 grok.com 关联 X 账号、确认 Premium 标签、在 accounts.x.ai 重新登录)后重试;仍失败则改用 https://console.x.ai 的 API Key 走 byok-custom-model(按 token 计费,与订阅额度互斥)。OAuth 限流为公平使用制,无公开硬性数值,出现 429 需等待滚动窗口重置或改用 BYOK。切勿打印 access_token / refresh_token,也不要把 user_code 手动填入验证 URL。