跳到主要內容
HERMES DOCUMENTATIONDOCS / CURRENT

通過 SSH 完成 OAuth

有些 Hermes provider 會使用 loopback redirect OAuth，例如 xAI Grok OAuth、Spotify，以及 Linear、Sentry、Atlassian、Asana、Figma 等遠程 MCP server。它們會把瀏覽器重定向到類似 http://127.0.0.1:<port>/callback 的地址，讓 Hermes 啟動的小 HTTP listener 接收授權碼。

當 Hermes 和瀏覽器在同一臺機器上時，這很簡單。問題出在遠程機器：你的瀏覽器訪問的是本地電腦的 127.0.0.1，但 listener 其實在遠程服務器上。

SSH 端口轉發​

解決方法是做本地端口轉發。以 xAI OAuth 的默認端口 56121 為例：

# 在本地電腦新開一個終端
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# 在已經登錄的遠程 SSH 會話中運行
hermes auth add xai-oauth --no-browser

Hermes 會打印授權 URL。把它複製到本地瀏覽器打開，瀏覽器回調到本地 127.0.0.1:56121 後，SSH 隧道會把請求轉發給遠程 Hermes listener。

Spotify 常用端口是 43827。MCP server 可能自動選擇端口，實際端口以 Hermes 輸出的 Waiting for callback on ... 為準。

沒有 SSH 客戶端怎麼辦？​

如果你在 GCP Cloud Shell、GitHub Codespaces、EC2 Instance Connect、Gitpod 或瀏覽器 Web IDE 裡操作，可能沒有可用的本地 SSH 客戶端。這時使用 --manual-paste：

hermes auth add xai-oauth --manual-paste

流程是：

  1. Hermes 打印授權 URL；
  2. 你在本地瀏覽器打開並授權；
  3. 瀏覽器跳轉到 127.0.0.1 失敗，這是正常現象；
  4. 從瀏覽器地址欄複製完整回調 URL；
  5. 粘貼回 Hermes 的 Callback URL: 提示處。

Hermes 接受完整 URL、?code=...&state=... 查詢片段，或上游頁面直接展示的 code。這個方式只是改變回調傳輸方式，不降低 OAuth 本身的 PKCE、state 和 nonce 校驗。

哪些 provider 需要這樣做？​

Provider常見端口遠程運行時是否需要處理
xai-oauth56121需要 SSH 轉發或 manual paste
Spotify43827需要 SSH 轉發或 manual paste
OAuth MCP server自動選擇需要 SSH 轉發或 paste 回調 URL
Anthropic Claude Pro / Max不適用不需要，使用 paste code
OpenAI Codex / ChatGPT Plus / Pro不適用不需要，使用 device code
MiniMax、Nous Portal不適用不需要，使用 device code

參考鏈接​