xAI Grok OAuth（SuperGrok / X Premium+）
Hermes Agent 通过基于浏览器的 OAuth 登录流程支持 xAI Grok，认证服务器为 accounts.x.ai，支持 SuperGrok 订阅（grok.com）或 X Premium+ 订阅（已关联的 X 账号）。无需 XAI_API_KEY——登录一次后，Hermes 会在后台自动刷新会话。
当你使用拥有 Premium+ 的 X 账号登录时，xAI 会自动将订阅状态关联到你的 xAI 会话，因此 OAuth 流程与直接 SuperGrok 订阅者的体验完全相同。
该传输层复用 codex_responses 适配器（xAI 暴露了 Responses 风格的端点），因此推理、工具调用、流式传输和 prompt（提示词）缓存无需任何适配器改动即可正常工作。
同一 OAuth bearer token 也会被 Hermes 中所有直连 xAI 的功能复用——TTS、图像生成、视频生成和转录——因此单次登录即可覆盖全部四项功能。
概览
| 项目 | 值 |
|---|---|
| Provider ID | xai-oauth |
| 显示名称 | xAI Grok OAuth (SuperGrok / X Premium+) |
| 认证类型 | 浏览器 OAuth 2.0 设备代码 |
| 传输层 | xAI Responses API（codex_responses） |
| 默认模型 | grok-build-0.1 |
| 端点 | https://api.x.ai/v1 |
| 认证服务器 | https://accounts.x.ai |
| 需要环境变量 | 否（此 provider 不使用 XAI_API_KEY） |
| 订阅要求 | SuperGrok 或 X Premium+——见下方说明 |
前提条件
- Python 3.9+
- 已安装 Hermes Agent
- 你的 xAI 账号拥有有效的 SuperGrok 订阅，或你登录所用的 X 账号拥有 X Premium+ 订阅（xAI 会自动关联订阅）
- 任意可打开打印出的验证 URL 的浏览器
xAI 的后端对 OAuth API 接口维护自己的白名单，已有记录显示即使应用内订阅处于激活状态，标准 SuperGrok 订阅者也会收到 HTTP 403（见 issue #26847）。如果浏览器中 OAuth 登录成功但推理返回 403，请设置 XAI_API_KEY 并切换到 API 密钥路径（provider: xai）——该接口目前不受相同限制。
快速开始
# 启动 provider 和模型选择器
hermes model
# → 从 provider 列表中选择 "xAI Grok OAuth (SuperGrok / X Premium+)"
# → Hermes 打开或打印 accounts.x.ai 验证 URL
# → 如有提示，输入显示的代码，然后在浏览器中批准访问
# → 选择模型（grok-build-0.1 在列表顶部）
# → 开始对话
hermes
首次登录后，凭据存储在 ~/.hermes/auth.json 中，并在过期前自动刷新。
手动登录
你可以不经过模型选择器直接触发登录：
hermes auth add xai-oauth
远程 / 无头会话
在没有浏览器的服务器、容器、仅限浏览器的远程控制台（Cloud Shell、Codespaces、EC2 Instance Connect）或 SSH 会话中，Hermes 会打印 xAI 验证 URL 和用户代码。在笔记本电脑或云控制台的任意浏览器中打开该 URL，如有提示则输入代码，Hermes 会持续轮询直到 xAI 批准登录。无需 SSH 隧道或本地回调监听器。
hermes auth add xai-oauth --no-browser
# 在浏览器中打开打印出的验证 URL。
Web 仪表盘和桌面应用使用相同的设备代码流程：显示验证 URL 和用户代码，并在你批准访问后在后台轮询。
登录流程说明
- Hermes 向
auth.x.ai请求设备代码。 - 你打开验证 URL，登录，如有提示则输入显示的代码，并批准访问。
- Hermes 轮询 xAI 直到批准，然后将 token 保存到
~/.hermes/auth.json。 - 此后，Hermes 在后台刷新 access token——你将保持登录状态，直到执行
hermes auth logout xai-oauth或在 xAI 账号设置中撤销访问。
检查登录状态
hermes doctor
◆ Auth Providers 部分将显示每个 provider 的当前状态，包括 xai-oauth。
切换模型
hermes model
# → 选择 "xAI Grok OAuth (SuperGrok / X Premium+)"
# → 从模型列表中选择（grok-build-0.1 固定在顶部）
或直接设置模型：
hermes config set model.default grok-build-0.1
hermes config set model.provider xai-oauth
配置参考
登录后，~/.hermes/config.yaml 将包含：
model:
default: grok-build-0.1
provider: xai-oauth
base_url: https://api.x.ai/v1
Provider 别名
以下所有别名均解析为 xai-oauth：
hermes --provider xai-oauth # 规范名称
hermes --provider grok-oauth # 别名
hermes --provider x-ai-oauth # 别名
hermes --provider xai-grok-oauth # 别名
直连 xAI 工具（TTS / 图像 / 视频 / 转录 / X 搜索）
通过 OAuth 登录后，每个直连 xAI 的工具都会自动复用同一 bearer token——无需单独配置，除非你更倾向于使用 API 密钥。
为每个工具选择后端：
hermes tools
# → Text-to-Speech → "xAI TTS"
# → Image Generation → "xAI Grok Imagine (image)"
# → Video Generation → "xAI Grok Imagine"
# → X (Twitter) Search → "xAI Grok OAuth (SuperGrok / X Premium+)"
如果 OAuth token 已存储，选择器会确认并跳过凭据提示。如果既没有 OAuth 也没有设置 XAI_API_KEY，选择器会提供三选一菜单：OAuth 登录、粘贴 API 密钥或跳过。
video_gen 工具集默认禁用。在 hermes tools → 🎬 Video Generation（按空格键）中启用后，agent 才能调用 video_generate。否则 agent 可能回退到内置的 ComfyUI 技能，该技能同样标记为视频生成。
只要配置了 xAI 凭据（SuperGrok / X Premium+ OAuth token 或 XAI_API_KEY），x_search 工具集就会自动启用。如不需要，请通过 hermes tools → 🐦 X (Twitter) Search（按空格键）显式禁用。该工具通过 xAI 内置的 x_search Responses API 路由——支持 SuperGrok / X Premium+ OAuth 登录或付费 XAI_API_KEY，两者同时配置时优先使用 OAuth（消耗订阅配额而非 API 费用）。未配置任何 xAI 凭据时，无论工具集是否启用，工具 schema 都对模型隐藏。
模型
| 工具 | 模型 | 说明 |
|---|---|---|
| 对话 | grok-build-0.1 | 默认；通过 OAuth 登录时自动选择 |
| 对话 | grok-4.3 | 之前的默认 |
| 对话 | grok-4.20-0309-reasoning | 推理变体 |
| 对话 | grok-4.20-0309-non-reasoning | 非推理变体 |
| 对话 | grok-4.20-multi-agent-0309 | 多 agent 变体 |
| 图像 | grok-imagine-image | 默认；约 5–10 秒 |
| 图像 | grok-imagine-image-quality | 更高保真度；约 10–20 秒 |
| 视频 | grok-imagine-video | 文本转视频 |
| 视频 | grok-imagine-video-1.5-preview | 图像转视频；日期别名 grok-imagine-video-1.5-2026-05-30 |
| TTS | （默认音色） | xAI /v1/tts 端点 |
对话模型目录从磁盘上的 models.dev 缓存实时获取；缓存刷新后，新的 xAI 模型会自动出现。grok-build-0.1 始终固定在列表顶部。
环境变量
| 变量 | 作用 |
|---|---|
XAI_BASE_URL | 覆盖默认的 https://api.x.ai/v1 端点（极少需要）。 |
要将 xAI 设为活跃 provider，请在 config.yaml 中设置 model.provider: xai-oauth（使用 hermes setup 进行引导配置），或在单次调用时传入 --provider xai-oauth。
故障排查
Token 过期——未自动重新登录
Hermes 在每次会话前刷新 token，并在收到 401 时响应式地再次刷新。如果刷新因 invalid_grant 失败（刷新 token 被撤销或账号已轮换），Hermes 会显示类型化的重新认证消息，而不是崩溃。
当刷新失败是终态时（HTTP 4xx、invalid_grant、授权被撤销等），Hermes 将刷新 token 标记为失效并在本地隔离——后续调用跳过注定失败的刷新尝试，而不是反复重放同一个 401。agent 显示一条"需要重新认证"消息，并在你再次登录前保持等待。
修复方法： 再次运行 hermes auth add xai-oauth 开始全新登录。下次成功交换后隔离状态自动清除。
授权超时
设备代码批准有有限的过期窗口（xAI 在设备代码响应中设置 expires_in，通常为数十分钟量级）。如果你未在时限内批准登录，Hermes 会抛出超时错误。
修复方法： 重新运行 hermes auth add xai-oauth（或 hermes model）。流程重新开始。
从远程服务器登录
在 SSH 或容器会话中，Hermes 打印验证 URL 和用户代码，而不是打开浏览器。在笔记本电脑或云控制台的浏览器中打开该 URL——xAI Grok OAuth 无需 SSH 端口转发。
hermes auth add xai-oauth --no-browser
回环重定向类 provider（Spotify、MCP 服务器）请参阅 OAuth over SSH / Remote Hosts。
登录成功后 HTTP 403（套餐 / 权限问题）
浏览器中 OAuth 完成，token 已保存，但推理或 token 刷新返回 HTTP 403，消息类似于 "The caller does not have permission to execute the specified operation"。
这不是 token 过期问题——重新运行 hermes model 不会改变结果。xAI 的后端已被观察到将 OAuth API 访问限制在特定 SuperGrok 套餐，即使应用内订阅处于激活状态（issue #26847）。
修复方法： 设置 XAI_API_KEY 并切换到 API 密钥路径：
export XAI_API_KEY=xai-...
hermes config set model.provider xai
或在 x.ai/grok 升级订阅（如果必须使用 OAuth 路径）。
运行时出现"No xAI credentials found"错误
auth 存储中没有 xai-oauth 条目，也未设置 XAI_API_KEY。你尚未登录，或凭据文件已被删除。
修复方法： 运行 hermes model 并选择 xAI Grok OAuth provider，或运行 hermes auth add xai-oauth。
退出登录
删除所有已存储的 xAI Grok OAuth 凭据：
hermes auth logout xai-oauth
这会清除 auth.json 中的单例 OAuth 条目以及 xai-oauth 的所有凭据池行。如果只想删除单个池条目，请使用 hermes auth remove xai-oauth <index|id|label>（运行 hermes auth list xai-oauth 查看列表）。
另请参阅
- OAuth over SSH / Remote Hosts — 如果 Hermes 与浏览器不在同一台机器上，必读
- AI Providers 参考
- 环境变量
- 配置
- 语音与 TTS