xAI Grok OAuth（SuperGrok 订阅）

Hermes Agent 支持通过浏览器-based OAuth 登录流程对接 accounts.x.ai，使用您现有的 SuperGrok 订阅。无需 XAI_API_KEY — 只需登录一次，Hermes 会自动在后台刷新您的会话。

该传输复用了 codex_responses 适配器（xAI 提供 Responses 风格的接口），因此推理、工具调用、流式输出和提示缓存均无需任何适配器变更即可正常工作。

同一 OAuth bearer token 还被 Hermes 中所有直接对接 xAI 的功能复用 — 包括 TTS、图像生成、视频生成和语音转录 — 因此一次登录即可覆盖全部四项功能。

概览

项目	值
服务提供商 ID	xai-oauth
显示名称	xAI Grok OAuth（SuperGrok 订阅）
认证类型	浏览器 OAuth 2.0 PKCE（回环回调）
传输方式	xAI Responses API（codex_responses）
默认模型	grok-4.3
端点地址	`https://api.x.ai/v1``
认证服务器	`https://accounts.x.ai``
是否需要环境变量	否（XAI_API_KEY 不用于此服务提供商）
订阅要求	SuperGrok — 详见下方说明

前置条件

• Python 3.9+
• 已安装 Hermes Agent
• 您的 xAI 账户上拥有有效的 SuperGrok 订阅
• 本地机器上有可用的浏览器（或使用 --no-browser 处理远程会话）

xAI 可能按用户等级限制 OAuth API 访问

xAI 后端对其 OAuth API 表面实施了自有白名单策略，已有记录显示标准 SuperGrok 用户即使订阅有效，也可能被拒绝访问（参见问题 #26847）。如果浏览器中登录成功但推理返回 403 错误，请设置 XAI_API_KEY 并切换至 API Key 方式（provider: xai）—— 当前该接口不受相同限制。

快速入门

# Launch the provider and model picker
hermes model
# → Select "xAI Grok OAuth (SuperGrok Subscription)" from the provider list
# → Hermes opens your browser to accounts.x.ai
# → Approve access in the browser
# → Pick a model (grok-4.3 is at the top)
# → Start chatting

hermes

首次登录后，凭据将存储于 ~/.hermes/auth.json，并在过期前自动刷新。

手动登录

您可跳过模型选择界面直接触发登录：

hermes auth add xai-oauth

远程 / 无头会话

在服务器、容器或 SSH 会话中，若无可用浏览器，Hermes 会检测到远程环境并打印授权 URL，而非自动打开浏览器。

重要： 回环监听器仍会在远程主机上运行于 127.0.0.1:56121。xAI 的重定向必须到达该监听器，因此在笔记本电脑上打开 URL 将失败（Could not establish connection. We couldn't reach your app.），除非进行端口转发：

# In a separate terminal on your local machine:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Then in your SSH session on the remote machine:
hermes auth add xai-oauth --no-browser
# Open the printed authorize URL in your local browser.

通过跳板机/堡垒机：添加 -J jump-user@jump-host。

完整步骤请参考 OAuth over SSH / Remote Hosts，包含 ProxyJump 链、mosh/tmux 和 ControlMaster 的注意事项。

仅限浏览器的远程环境（Cloud Shell、Codespaces、EC2 Instance Connect）

若您没有常规 SSH 客户端（例如在 GCP Cloud Shell、GitHub Codespaces、AWS EC2 Instance Connect、Gitpod 或其他基于浏览器的控制台内运行 Hermes），上述 ssh -L 方法不可用。请改用 --manual-paste — Hermes 将跳过回环监听器，允许您直接从浏览器粘贴失败的回调 URL：

hermes auth add xai-oauth --manual-paste
# Or via the model picker:
hermes model --manual-paste

完整操作指南请参见 OAuth over SSH / Remote Hosts。修复回归问题 #26923。

登录流程说明

1. Hermes 在您的浏览器中打开 accounts.x.ai。
2. 您登录（或确认现有会话）并授权访问。
3. xAI 重定向回 Hermes，令牌被保存至 ~/.hermes/auth.json。
4. 之后，Hermes 会在后台自动刷新访问令牌 —— 直到您主动退出登录或在 xAI 账户设置中撤销权限前，始终保持登录状态。

检查登录状态

hermes doctor

◆ Auth Providers 部分将显示每个服务提供商的当前状态，包括 xai-oauth。

切换模型

hermes model
# → Select "xAI Grok OAuth (SuperGrok Subscription)"
# → Pick from the model list (grok-4.3 is pinned to the top)

或直接设置模型：

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

配置参考

登录后，~/.hermes/config.yaml 将包含以下内容：

model:
  default: grok-4.3
  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 的工具（TTS / 图像 / 视频 / 转录 / X 搜索）

一旦通过 OAuth 登录，所有直接对接 xAI 的工具将自动复用相同的 bearer token —— 无需额外配置，除非您更倾向于使用 API Key。

为每项工具选择后端：

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 Subscription)"

若已存储 OAuth 令牌，选择器会确认状态并跳过凭据提示。若既未设置 OAuth 也未设置 XAI_API_KEY，选择器将提供三选一菜单：OAuth 登录、粘贴 API Key 或跳过。

视频生成默认关闭

video_gen 工具集默认禁用。请在 hermes tools → 🎬 Video Generation（按空格键）中启用，否则代理可能回退至内置 ComfyUI 技能（同样标记为支持视频生成）。

X 搜索默认关闭

x_search 工具集默认禁用。请在 hermes tools → 🐦 X (Twitter) Search（按空格键）中启用，代理才能调用 x_search。该工具通过 xAI 内置的 x_search Responses API 路由 —— 无论使用您的 SuperGrok OAuth 登录还是付费 XAI_API_KEY 均可工作，并且当两者都配置时优先使用 OAuth（使用订阅额度而非 API 消耗）。当未配置 xAI 凭据时，无论工具集是否启用，其 schema 均对模型隐藏。

模型列表

工具	模型	说明
对话	grok-4.3	默认；通过 OAuth 登录时自动选择
对话	grok-4.20-0309-reasoning	推理增强版
对话	grok-4.20-0309-non-reasoning	非推理版
对话	grok-4.20-multi-agent-0309	多代理版
图像	grok-imagine-image	默认；约 5–10 秒
图像	grok-imagine-image-quality	更高保真度；约 10–20 秒
视频	grok-imagine-video	文本到视频及图像到视频；最多支持 7 张参考图
TTS	（默认语音）	xAI /v1/tts 端点

对话模型目录实时从磁盘上的 models.dev 缓存中提取；新版本 xAI 发布后，一旦缓存更新即自动出现。grok-4.3 始终位于列表顶部。

环境变量

变量	作用
XAI_BASE_URL	覆盖默认 https://api.x.ai/v1 端点（极少需要）
HERMES_INFERENCE_PROVIDER	运行时强制指定活动服务提供商，例如 HERMES_INFERENCE_PROVIDER=xai-oauth hermes

故障排除

令牌过期 — 无法自动重新登录

Hermes 在每次会话开始前以及收到 401 错误时都会尝试刷新令牌。若刷新失败并返回 invalid_grant（刷新令牌被撤销或账户已更换），Hermes 会抛出结构化重认证消息，而非崩溃。

修复方法： 再次运行 hermes auth add xai-oauth 以启动全新登录流程。

授权超时

回环监听器具有有限的有效期窗口（默认 180 秒）。若未及时批准登录，Hermes 将抛出超时错误。

修复方法： 重新运行 hermes auth add xai-oauth（或 hermes model），流程将重新开始。

状态不匹配（可能存在 CSRF 问题）

Hermes 检测到认证服务器返回的 state 值与发送的不一致。

修复方法： 重新运行登录流程。若问题持续存在，请检查是否存在修改 OAuth 响应的代理或重定向。

从远程服务器登录

在 SSH 或容器会话中，Hermes 会打印授权 URL 而非打开浏览器。回环回调监听器仍在远程主机上绑定于 127.0.0.1:56121 —— 若无 SSH 本地转发，您的笔记本浏览器无法访问该监听器：

# Local machine, separate terminal:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Remote machine:
hermes auth add xai-oauth --no-browser
```完整操作指南（跳板机、mosh/tmux、端口冲突）：[OAuth 通过 SSH / 远程主机](./oauth-over-ssh.md)

### 成功登录后出现 HTTP 403 错误（权限等级 / 使用权限）

在浏览器中完成 OAuth 登录，令牌已保存，但执行推理或刷新令牌时返回 `HTTP 403`，提示类似 *"调用方没有权限执行指定操作"*。

这**不是**过期令牌问题 —— 重新运行 `hermes model` 不会解决此问题。已有观察表明，xAI 后端会限制 OAuth API 访问权限，仅对特定 SuperGrok 套餐开放，即使应用内订阅状态正常（参见问题 [#26847](https://github.com/NousResearch/hermes-agent/issues/26847)）。

**解决方案：** 设置 `XAI_API_KEY` 并切换至 API 密钥路径：

```bash
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 可查看当前所有条目）。

参考资料

• OAuth 通过 SSH / 远程主机 —— 若 Hermes 与您的浏览器不在同一台机器上，此为必读内容
• AI 服务提供商参考
• 环境变量
• 配置
• 语音与 TTS