sidebar_position: 16 title: “xAI Grok OAuth (SuperGrok / X Premium+)” description: “Sign in with your SuperGrok or X Premium+ subscription to use Grok models in Hermes Agent — no API key required”

xAI Grok OAuth（SuperGrok / X Premium+）

Hermes Agent 支持通过基于浏览器的 OAuth 设备码登录流程，借助 accounts.x.ai 访问 xAI Grok。该功能适用于 SuperGrok 订阅用户（grok.com）或拥有 X Premium+ 订阅的账户（关联的 X 账户）。无需提供 XAI_API_KEY——只需登录一次，Hermes 就会自动在后台刷新您的会话。

若使用已开通 Premium+ 功能的 X 账户登录，xAI 会自动将订阅状态与您的 xAI 会话关联起来，因此其 OAuth 登录流程与直接使用 SuperGrok 订阅的用户完全相同。

该传输层复用了 codex_responses 适配器（xAI 提供了类似 Responses 风格的接口），因此推理、工具调用、流式处理以及提示词缓存等功能均无需进行任何适配器调整即可正常工作。

Hermes 中所有直接与 xAI 对接的功能——包括文本转语音、图像生成、视频生成以及文字转录——也都复用相同的 OAuth 承载令牌，因此只需登录一次即可同时使用这四项功能。

概览

先决条件

• Python 3.9 及以上版本
• 已安装 Hermes Agent
• 您的 xAI 账户拥有有效的 SuperGrok 订阅，或您登录使用的 X 账户拥有 X Premium+ 订阅（xAI 会自动关联这些订阅信息）
• 可以打开打印后的验证链接的浏览器

:::warning xAI 可能会根据订阅层级限制 OAuth API 的访问权限 xAI 的后端会对 OAuth API 设置独立的允许列表，即便应用内的订阅处于有效状态，某些普通 SuperGrok 订阅用户仍可能被拒绝访问，并返回 HTTP 403 错误（参见问题 #26847）。如果通过浏览器进行 OAuth 登录成功，但推理请求却返回 403 错误，请设置 XAI_API_KEY 并切换到 API 密钥访问路径（provider: xai）——目前该路径不受同样的访问限制。

::

快速入门

# Launch the provider and model picker
hermes model
# → Select "xAI Grok OAuth (SuperGrok / X Premium+)" from the provider list
# → Hermes opens or prints an accounts.x.ai verification URL
# → Enter the displayed code if prompted, then approve access in the browser
# → Pick a model (grok-4.6 is at the top)
# → Start chatting

hermes

首次登录后，凭证会被存储在 ~/.hermes/auth.json 文件中，并会在过期前自动刷新。

手动登录

您无需通过模型选择器即可直接触发登录操作：

hermes auth add xai-oauth

远程/无界面会话

在服务器、容器、仅支持浏览器的控制台（如 Cloud Shell、Codespaces、EC2 Instance Connect），或是 Hermes 无法在本地启动浏览器的 SSH 会话中，Hermes 会自动输出 xAI 验证网址及用户代码。您只需在笔记本电脑或云控制台中的任意浏览器中打开该网址，根据提示输入代码，Hermes 将持续轮询，直到 xAI 批准登录。此类场景无需使用 SSH 隧道或本地回调监听器。

hermes auth add xai-oauth --no-browser
# Open the printed verification URL in your browser.

无论通过网页控制台还是桌面应用程序登录，都遵循相同的设备码流程：Hermes会首先显示验证网址和用户代码，随后在后台持续轮询，直到您批准访问权限。

登录流程说明

1. Hermes向auth.x.ai请求设备码。
2. 您打开该验证网址进行登录，根据提示输入显示的代码，然后批准访问。
3. Hermes会不断向xAI发起轮询，直至获得批准，随后将令牌保存到~/.hermes/auth.json文件中。
4. 之后，Hermes会在后台自动刷新访问令牌——只要您没有执行hermes auth logout xai-oauth命令或在xAI账户设置中撤销访问权限，就会保持登录状态。

检查登录状态

hermes doctor

◆ Auth Providers 部分会显示包括 xai-oauth 在内的所有认证提供程序的当前状态。

切换模型

hermes model
# → Select "xAI Grok OAuth (SuperGrok / X Premium+)"
# → Pick from the model list (grok-4.6 is pinned to the top)

或者直接设置模型：

hermes config set model.default grok-4.6
hermes config set model.provider xai-oauth

配置参考

登录完成后，~/.hermes/config.yaml 文件中将包含以下内容：

model:
  default: grok-4.6
  provider: xai-oauth
  base_url: https://api.x.ai/v1

提供商别名

以下所有别名均对应 xai-oauth：

hermes --provider xai-oauth        # canonical
hermes --provider grok-oauth       # alias
hermes --provider x-ai-oauth       # alias
hermes --provider xai-grok-oauth   # alias

直连 xAI 工具（文本转语音 / 图像处理 / 视频处理 / 文本转写 / X 搜索）

通过 OAuth 登录后，所有直连 xAI 的工具都会自动复用同一个承载令牌——无需进行额外设置，除非您希望使用 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 令牌，选择器会予以确认并跳过凭证输入步骤。若既未设置 OAuth 令牌也未设置 XAI_API_KEY，选择器将提供三个选项：通过 OAuth 登录、粘贴 API 密钥或直接跳过。

::注意 视频生成功能默认处于关闭状态 video_gen 工具集默认是禁用的。在代理能够调用 video_generate 函数之前，需先通过 hermes tools → 🎬 Video Generation（按空格键）将其启用。否则，代理可能会回退到内置的 ComfyUI 功能，该功能同样具备视频生成能力。

::

::注意 当配置了 xAI 凭证时，X 搜索功能会自动启用 一旦配置了 xAI 凭证（SuperGrok/X Premium+ OAuth 令牌或 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 凭证，模型也将无法看到该工具的架构信息。

::

模型

聊天功能所使用的模型列表会实时从磁盘上的 models.dev 缓存中获取；一旦该缓存更新，新的 xAI 模型便会自动出现。grok-4.6 始终会被固定在列表的最顶部。

环境变量

若要将 xAI 设为默认服务提供方，请在 config.yaml 中设置 model.provider: xai-oauth（可通过 hermes setup 进行引导式配置），或针对单次调用传递 --provider xai-oauth 参数。

故障排除

令牌已过期——未自动重新登录

Hermes会在每次会话开始前刷新令牌，而在遇到401错误时也会主动进行刷新。如果刷新失败且原因是invalid_grant（即刷新令牌已被撤销或账户已更换），Hermes会显示一条结构化的重新认证提示，而不会崩溃。

当刷新失败为不可恢复的情况时（如HTTP 4xx错误、invalid_grant错误、令牌已被撤销等），Hermes会将该刷新令牌标记为无效并在本地将其隔离——后续请求将跳过这次失败的刷新尝试，从而避免反复出现相同的401错误。此时，Agent只会显示一条“需要重新认证”的提示，直到您再次登录为止。

解决方法： 重新运行hermes auth add xai-oauth以开始新的登录流程。一旦下次成功完成授权交换，该被隔离的令牌就会被清除。

授权超时

设备码授权具有固定的有效期（xAI会在设备码响应中设置expires_in字段，通常为数十分钟）。如果您未能及时批准登录，Hermes就会抛出超时错误。

解决方法： 重新运行hermes auth add xai-oauth（或hermes model）即可，这样流程将重新开始。

从远程服务器登录

在SSH会话或容器环境中，Hermes会直接输出验证网址和用户码，而不会自动打开浏览器。您可以在笔记本电脑的浏览器或云控制台中打开该网址——对于xAI Grok OAuth而言，无需进行SSH端口转发。

hermes auth add xai-oauth --no-browser

对于回环重定向型提供方（如 Spotify、MCP 服务器），请参阅 通过 SSH/远程主机进行 OAuth 认证。

成功登录后出现 HTTP 403 错误（权限/资格问题）

在浏览器中完成 OAuth 认证并保存了令牌，但在执行推理或刷新令牌时却会返回 HTTP 403 错误，错误信息类似“调用者无权执行该操作”。

这并非令牌过期的问题——重新运行 hermes model 也无法解决该问题。有反馈指出，即使应用内的订阅处于有效状态，xAI 的后端仍会限制特定 SuperGrok 级别用户访问 OAuth API（问题编号 #26847）。

解决方案： 设置 XAI_API_KEY 并切换至基于 API 密钥的访问路径。

export XAI_API_KEY=xai-...
hermes config set model.provider xai

如果需要通过 OAuth 方式登录，则可在 x.ai/grok 上升级您的订阅套餐。

运行时出现“未找到 xAI 凭据”的错误

认证存储中不存在 xai-oauth 条目，且也未设置 XAI_API_KEY。可能是因为您尚未登录，或者凭据文件已被删除。

解决方法： 运行 hermes model 并选择 xAI Grok OAuth 提供商，或执行 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 查看这些条目）。

参考资料

• 通过 SSH/远程主机进行 OAuth 认证 —— 用于循环重定向提供方（如 Spotify、MCP）的 SSH 隧道；而 xAI 使用设备码，无需此类隧道
• AI 提供方参考手册
• 环境变量
• 配置设置
• 语音与文本转语音功能