Hermes Agent 接入 xAI Grok OAuth：用 SuperGrok 订阅驱动 AI Agent

本文介绍 Hermes Agent 如何通过浏览器 OAuth 登录接入 xAI Grok，无需 API Key 即可使用 SuperGrok 订阅驱动 AI Agent，并自动复用 Token 实现 TTS、图像生成、视频生成和 X 搜索等全功能支持。

概述

Hermes Agent 支持通过浏览器 OAuth 登录流程接入 xAI Grok，使用现有的 SuperGrok 订阅即可，无需 XAI_API_KEY。登录一次后，Hermes 会在后台自动刷新会话。

传输层复用了 codex_responses 适配器（xAI 暴露了 Responses 风格的端点），因此推理、工具调用、流式传输和提示缓存均可正常工作，无需任何适配器更改。

同一 OAuth Bearer Token 还会被 Hermes 中所有直接调用 xAI 的功能复用——TTS、图像生成、视频生成和转录——因此一次登录即可覆盖全部四项功能。

核心信息

前置要求

• Python 3.9+
• Hermes Agent 已安装
• 拥有活跃的 SuperGrok 订阅
• 本机有可用的浏览器（远程会话可使用 --no-browser）

快速开始

# 启动 provider 和模型选择器
hermes model
# → 从 provider 列表中选择 "xAI Grok OAuth (SuperGrok Subscription)"
# → Hermes 会在浏览器中打开 accounts.x.ai
# → 在浏览器中批准访问
# → 选择模型（grok-4.3 位于顶部）
# → 开始对话

hermes

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

手动登录

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

hermes auth add xai-oauth

远程 / 无浏览器会话

在服务器、容器或 SSH 会话中，Hermes 检测到远程环境后会打印授权 URL，而不是打开浏览器。

重要：loopback 监听器仍在远程机器的 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。

登录工作流程

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

检查登录状态

hermes doctor

◆ Auth Providers 部分会显示所有 provider 的当前状态，包括 xai-oauth。

切换模型

hermes model
# → 选择 "xAI Grok OAuth (SuperGrok Subscription)"
# → 从模型列表中选择（grok-4.3 固定在顶部）

或直接设置模型：

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

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 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 Token 已存储，选择器会确认并跳过凭据提示。如果既没有 OAuth 也没有 XAI_API_KEY，选择器会提供三选一菜单：OAuth 登录、粘贴 API Key 或跳过。

视频生成默认关闭

video_gen 工具集默认禁用。在 hermes tools → 🎬 Video Generation（按空格键）中启用，Agent 才能调用 video_generate。否则 Agent 可能回退到内置的 ComfyUI skill。

X 搜索默认关闭

x_search 工具集默认禁用。在 hermes tools → 🐦 X (Twitter) Search（按空格键）中启用。该工具通过 xAI 内置的 x_search Responses API 路由——支持 SuperGrok OAuth 登录或付费 XAI_API_KEY，两者都配置时优先使用 OAuth（使用订阅配额而非 API 支出）。

可用模型

聊天模型目录从磁盘上的 models.dev 缓存实时派生；新的 xAI 发布会在该缓存刷新后自动出现。grok-4.3 始终固定在列表顶部。

环境变量

故障排查

Token 过期 — 未自动重新登录

Hermes 在每次会话前刷新 Token，并在收到 401 时再次刷新。如果刷新因 invalid_grant 失败（Refresh Token 被撤销或账户已轮换），Hermes 会显示类型化的重新认证消息，而不是崩溃。

修复：再次运行 hermes auth add xai-oauth 开始新的登录。

授权超时

Loopback 监听器有有限的过期窗口（默认 180 秒）。如果未及时批准登录，Hermes 会抛出超时错误。

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

State 不匹配（可能的 CSRF）

Hermes 检测到授权服务器返回的 state 值与发送的不匹配。

修复：重新运行登录。如果持续出现，检查是否有代理或重定向修改了 OAuth 响应。

从远程服务器登录

在 SSH 或容器会话中，Hermes 打印授权 URL 而不是打开浏览器。Loopback 回调监听器仍绑定在远程主机的 127.0.0.1:56121——笔记本电脑的浏览器无法在没有 SSH 本地转发的情况下访问它。

修复：建立 SSH 端口转发后重新登录。

"No xAI credentials found" 运行时错误

Auth store 中没有 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 查看）。

项目链接

• 官方文档：https://hermes-agent.dev/docs/integrations/xai-grok-oauth
• GitHub 仓库：https://github.com/nous-research/hermes