<!-- Source: https://hermesbible.com/docs/guides/xai-grok-oauth -->

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 承載代碼也被 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 會失敗（Could not establish connection. We couldn't reach your app.），除非你轉發連接埠：

# 在你的本機機器上的另一個終端機：
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 陷阱，請參見 OAuth over SSH / 遠端主機。

僅瀏覽器遠端（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

完整的逐步說明請參見 OAuth over SSH / 遠端主機。#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 的工具都會自動重用相同的承載代碼 — 除非你偏好使用 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-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、連接埠衝突）：OAuth over SSH / 遠端主機。

成功登入後出現 HTTP 403（層級/資格）

OAuth 在瀏覽器中完成，代碼已儲存，但推論或代碼重新整理傳回 HTTP 403，訊息類似於 「The caller does not have permission to execute the specified operation」。

這不是過時代碼的問題 — 重新執行 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 升級你的訂閱。

運行時出現「No xAI credentials found」錯誤

認證儲存中沒有 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 over SSH / 遠端主機 — 如果 Hermes 在與你的瀏覽器不同的機器上，必讀
• AI 供應商參考
• 環境變數
• 設定
• 語音和 TTS

---

---

貢獻