hermes教程-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 风格的端点），因此推理、工具调用、流式传输和提示缓存无需任何适配器更改即可工作。

同一个 OAuth bearer 令牌也会被 Hermes 中所有直接面向 xAI 的表面复用 — TTS、图像生成、视频生成和转录 — 因此一次登录即可覆盖所有四项功能。

概览

前提条件

• Python 3.9+
• 已安装 Hermes Agent
• 你的 xAI 账户上有一个有效的 SuperGrok 订阅，或者你登录的 X 账户上有一个 X Premium+ 订阅（xAI 会自动关联订阅）
• 本地机器上有一个可用的浏览器（或使用 --no-browser 进行远程会话）

警告 — xAI 可能按层级限制 OAuth API 访问

xAI 的后端在 OAuth API 表面上执行自己的允许列表，并且已被观察到拒绝标准 SuperGrok 订阅者，返回 HTTP 403（参见 issue #26847），即使应用内订阅是激活的。如果 OAuth 登录在浏览器中成功，但推理返回 403，请设置 XAI_API_KEY 并切换到 API 密钥路径（provider: xai）— 该表面目前不受相同限制。

快速开始

## 启动提供者和模型选择器
hermes model
## → 从提供者列表中选择 "xAI Grok OAuth (SuperGrok / X Premium+)"
## → Hermes 会在浏览器中打开 accounts.x.ai
## → 在浏览器中批准访问
## → 选择一个模型（grok-build-0.1 在顶部）
## → 开始聊天

hermes

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

手动登录

你可以不通过模型选择器触发登录：

hermes auth add xai-oauth

远程 / 无头会话

在服务器、容器或 SSH 会话中，如果没有可用的浏览器，Hermes 会检测到远程环境并打印授权 URL，而不是打开浏览器。

重要提示： 环回监听器仍然在远程机器的 127.0.0.1:56121 上运行。xAI 的重定向需要到达那个监听器，因此在你本地笔记本电脑上打开 URL 会失败（无法建立连接。我们无法到达你的应用。），除非你转发端口：

## 在本地机器的另一个终端中：
ssh -N -L 56121:127.0.0.1:56121 user@remote-host
## 然后在远程机器的 SSH 会话中：
hermes auth add xai-oauth --no-browser
## 在本地浏览器中打开打印的授权 URL。

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

有关完整的分步指南，包括 ProxyJump 链、mosh/tmux 和 ControlMaster 陷阱，请参见 通过 SSH / 远程主机的 OAuth。

仅浏览器远程（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
## 或者通过模型选择器：
hermes model --manual-paste

有关完整演练，请参见 通过 SSH / 远程主机的 OAuth。针对 #26923 的回归修复。

如果同意页面直接在页面上呈现授权代码（xAI 在基于浏览器的控制台上的当前行为），而不是重定向到你的 127.0.0.1:56121/callback，请在 Callback URL: 提示符处粘贴仅裸代码值 — Hermes 可以互换接受完整 URL、裸 ?code=...&state=... 查询片段或裸代码。

登录工作原理

1. Hermes 在你的浏览器中打开 accounts.x.ai。
2. 你登录（或确认现有会话）并批准访问。
3. xAI 重定向回 Hermes，令牌保存到 ~/.hermes/auth.json。
4. 此后，Hermes 在后台刷新访问令牌 — 你将保持登录状态，直到你运行 hermes auth remove xai-oauth 或从你的 xAI 账户设置中撤销访问权限。

检查登录状态

hermes doctor

◆ Auth Providers 部分将显示每个提供者的当前状态，包括 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

提供者别名

以下所有内容都解析为 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 令牌 — 除非你更愿意使用 API 密钥，否则无需单独设置。

为每个工具选择后端：

hermes tools
## → 文本转语音       → "xAI TTS"
## → 图像生成         → "xAI Grok Imagine (image)"
## → 视频生成         → "xAI Grok Imagine"
## → X (Twitter) 搜索 → "xAI Grok OAuth (SuperGrok / X Premium+)"

如果 OAuth 令牌已存储，选择器会确认并跳过凭据提示。如果既未设置 OAuth 也未设置 XAI_API_KEY，选择器会提供一个 3 选项菜单：OAuth 登录、粘贴 API 密钥或跳过。

注意 — 视频生成默认关闭

video_gen 工具集默认禁用。在 hermes tools → 🎬 Video Generation 中启用（按空格键），然后代理才能调用 video_generate。否则，代理可能会回退到捆绑的 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-build-0.1 始终固定在列表顶部。

环境变量

要选择 xAI 作为活动提供者，请在 config.yaml 中设置 model.provider: xai-oauth（使用 hermes setup 进行引导流程）或为单次调用传递 --provider xai-oauth。

故障排除

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

Hermes 在每个会话之前刷新令牌，并在收到 401 时再次反应性刷新。如果刷新失败并返回 invalid_grant（刷新令牌已被撤销，或账户已轮换），Hermes 会显示一条类型化的重新认证消息，而不是崩溃。

当刷新失败是终局性的（HTTP 4xx、invalid_grant、已撤销授权等）时，Hermes 会将刷新令牌标记为失效并在本地隔离 — 后续调用会跳过注定失败的刷新尝试，而不是一遍又一遍地重放相同的 401。代理会显示一条“需要重新认证”的消息，并在你再次登录之前保持不干扰。

修复： 再次运行 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 本地转发：

## 本地机器，另一个终端：
ssh -N -L 56121:127.0.0.1:56121 user@remote-host
## 远程机器：
hermes auth add xai-oauth --no-browser

完整演练（跳板机、mosh/tmux、端口冲突）：通过 SSH / 远程主机的 OAuth。

成功登录后出现 HTTP 403（层级 / 权限）

OAuth 在浏览器中完成，令牌已保存，但推理或令牌刷新返回 HTTP 403，并显示类似“调用者无权执行指定操作”的消息。

这不是令牌过期问题 — 重新运行 hermes model 不会改变它。xAI 的后端已被观察到将 OAuth API 访问限制到特定的 SuperGrok 层级，尽管应用内订阅是激活的（issue #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 — 如果 Hermes 与你的浏览器不在同一台机器上，则必读
• AI 提供者参考
• 环境变量
• 配置
• 语音和 TTS