Grok OAuth Skill

August 16, 2026 · View on GitHub

这是一个中文 AI skill 与最小 Python reference implementation，用来解释和演示：本地程序如何打开浏览器完成 SuperGrok / X Premium+ subscription OAuth，如何理解和刷新 token，以及如何用 subscription credential 发出一次 Chat Completions 请求，让模型讲一个短笑话。

它不需要 XAI_API_KEY，也没有前端。Python CLI 在 127.0.0.1:56121 临时监听 OAuth callback，授权完成后把 token 明文写入：

~/.grok_oauth/token.json

这是故意采用的教学设计，不是生产安全建议。文件权限设为 0600，但 token 内容仍是明文。生产系统应改用 OS Keychain、encrypted secret store 或 application-level envelope encryption。

重要边界

本项目不是 xAI 官方 SDK。它复用公开的 Grok CLI / Grok Build public client identity，以及若干 MIT-licensed compatibility implementation。xAI 可以改变 endpoint、模型、header 或授权行为。只应将它用于个人学习、兼容性验证和 owner-controlled tooling，不应直接扩展成多用户 SaaS。

部分 SuperGrok 档位能完成浏览器登录，但推理仍返回 HTTP 403。这时应换官方 API key，而不是继续重试这个 unofficial surface。

安装

git clone https://github.com/grapeot/grok-oauth-skill grok_oauth
cd grok_oauth
uv venv .venv
uv pip install --python .venv/bin/python -e '.[dev]'

最短 Demo

.venv/bin/grok-oauth demo

CLI 会：

  1. 明确提示 token 将以明文保存及其绝对路径。
  2. 启动 http://127.0.0.1:56121/callback。
  3. 打开系统浏览器，让用户在 xAI 页面授权。
  4. 校验 OAuth state，使用 PKCE verifier 换取 token。
  5. 将完整 token bundle 写入 ~/.grok_oauth/token.json，权限设为 0600。
  6. 必要时 refresh access token，然后调用 xAI Chat Completions，要求模型讲一个很短的笑话。

也可以拆开运行：

.venv/bin/grok-oauth login
.venv/bin/grok-oauth status
.venv/bin/grok-oauth request --prompt '请讲一个很短的笑话，只输出笑话本身。'
.venv/bin/grok-oauth logout

如果不希望 CLI 自动打开浏览器：

.venv/bin/grok-oauth login --no-open

SSH / 容器环境可以改用 device code：

.venv/bin/grok-oauth login --device

Token 文件

明文 JSON 包含：

{
  "schema_version": 1,
  "access_token": "<redacted>",
  "refresh_token": "<redacted>",
  "id_token": "<redacted>",
  "expires_at": 1780000000,
  "scope": "openid profile email offline_access grok-cli:access api:access",
  "subject": "<redacted>"
}
  • access_token：短期 bearer credential。只放在请求的 Authorization header，不能当用户 ID。
  • refresh_token：在 access token 过期时换取新 token。它通常寿命更长、权限更敏感，而且可能每次 refresh 都旋转；保存新值时必须原子替换旧值。
  • id_token：OIDC 身份声明 JWT。reference implementation 只从中提取 sub，不把它当 API bearer token。
  • expires_at：CLI 根据 expires_in 计算的本地 Unix timestamp，不是 OAuth server 直接返回的 token。
  • subject：可选身份标记。xAI Chat Completions 不需要额外 account header。
  • scope：授权范围记录。它描述 consent，不替代服务端权限检查。

OAuth authorization code、PKCE verifier 和 state 只在单次登录过程中存在，不写入 token 文件。

给 AI Agent 安装 Skill

把 https://github.com/grapeot/grok-oauth-skill 交给 Codex、Claude Code、Cursor、OpenCode 或其他 coding agent，并要求它：

  1. 先阅读目标 workspace 的 AGENTS.md、CLAUDE.md 或 routing 文档。
  2. 将 skills/grok_oauth.md 放入该 workspace 的 skill discovery chain。
  3. 如果 workspace 有 skills/INDEX.md 或 rules/skills/INDEX.md，添加一个指向 root skill 的条目；否则在 AGENTS.md 或 CLAUDE.md 中添加短指针。

只暴露这一个 root skill。reference implementation、RFC 和测试继续留在 repo 内，由 root skill 按需引用。

开发与验证

.venv/bin/python -m pytest -v
.venv/bin/ruff check .
.venv/bin/python scripts/check_public.py

默认测试完全离线，不访问 xAI，也不读取真实 token 文件。真实 OAuth 和 Chat Completions request 只通过人工运行 grok-oauth demo 验收。

架构与生产边界见 docs/rfc.md，Agent 使用 contract 见 skills/grok_oauth.md。