<!-- Source: https://hermesbible.com/docs/guides/oauth-over-ssh -->

某些 Hermes 供應商 — xAI Grok OAuth、Spotify 和遠端 MCP 伺服器（Linear、Sentry、Atlassian、Asana、Figma、…） — 使用迴圈重新導向 OAuth 流程。認證伺服器將你的瀏覽器重新導向到 http://127.0.0.1:<port>/callback，讓 Hermes 啟動的微型 HTTP 監聽器可以取得授權碼。

當 Hermes 和你的瀏覽器在同一台機器上時，這運作得很完美。當它們不在同一台機器上時就會中斷：你筆記型電腦的瀏覽器嘗試到達你的筆記型電腦上的 127.0.0.1，但監聽器綁定在遠端伺服器上的 127.0.0.1。

修正方法是一行 SSH 本地轉發 — 或者，當你沒有真正的 SSH 用戶端時（GCP Cloud Shell、GitHub Codespaces、EC2 Instance Connect、Gitpod、基於瀏覽器的 Web IDE），使用在 #26923 中引入的新的 --manual-paste 參數。

摘要

# 在你的本機機器（筆記型電腦）上，在另一個終端機中：
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/callback，隧道轉發
#   請求到遠端監聽器，登入完成。

xAI OAuth 使用的連接埠是 56121。對於 Spotify，將其替換為 43827。Hermes 在 Waiting for callback on ... 行上列出它綁定的確切連接埠 — 從那裡複製它。

僅瀏覽器遠端（Cloud Shell / Codespaces / EC2 Instance Connect）

如果你沒有普通的 SSH 用戶端 — 例如因為你在 GCP Cloud Shell、GitHub Codespaces、AWS EC2 Instance Connect、Gitpod 或其他基於瀏覽器的控制台中運行 Hermes — 上述 SSH 隧道不可用。改用 --manual-paste：

hermes auth add xai-oauth --manual-paste
# → Hermes 列印一個授權 URL。在你的筆記型電腦瀏覽器中開啟它。
# → 在瀏覽器中批准。重新導向到 127.0.0.1:56121/callback 無法
#   載入 — 這是預期的。
# → 從失敗頁面的位址列複製完整 URL。
# → 將其貼回到終端機的「Callback URL:」提示處。

相同的參數適用於 hermes model --manual-paste 用於整合式模型選擇器。Hermes 三種回呼貼上形式可以互換使用：完整 URL、裸的 ?code=...&state=... 查詢片段，或 — 當上游同意頁面在頁面上呈現授權碼而非重新導向時（xAI 在基於瀏覽器的控制台上目前的行為） — 僅僅是裸的代碼值本身。

Hermes 為兩條路徑使用相同的 PKCE 驗證者、狀態和 nonce，因此上游 OAuth 流程是位元組相同的 — --manual-paste 純粹是回呼跳的傳輸變更，不是安全性降級。

哪些供應商需要此功能

如果你的供應商不在表格中，你不需要隧道。

MCP 伺服器

遠端 MCP 伺服器（Linear、Sentry、Atlassian、Asana、Figma 等）使用相同的迴圈重新導向流程。Hermes 為每個伺服器自動選擇一個空閒連接埠，並在 OAuth 流程啟動時列印授權 URL — 要麼在啟動時（當 mcp_servers: 中出現新伺服器時），要麼在你執行 hermes mcp login <server> 時。

你有兩種方式從遠端主機完成它：

選項 1 — 將重新導向 URL 貼回（無需設定，任何地方都能用）。 在互動式終端機上，Hermes 在運行本地監聽器的同時提示你貼上重新導向 URL。在瀏覽器中批准後，重新導向到 http://127.0.0.1:<port>/callback 會顯示連線錯誤 — 這是預期的。從瀏覽器位址列複製完整 URL 並貼到 Hermes 提示處：

  MCP OAuth: authorization required.
  Open this URL in your browser:

    https://mcp.linear.app/authorize?response_type=code&...

  Or paste the redirect URL here (or the ?code=...&state=... portion) and press Enter:
> https://mcp.linear.app/callback?code=abc123&state=xyz
  Got authorization code from paste — completing flow.

裸的 ?code=...&state=... 查詢字串也會被接受。這適用於任何具有 auth: oauth 的 MCP 伺服器，不需要 SSH 設定變更。

選項 2 — SSH 連接埠轉發（與 xAI / Spotify 相同）。 Hermes 在 SSH 工作階段提示中列出它綁定的確切連接埠。在你的筆記型電腦上開啟另一個終端機：

ssh -N -L <port>:127.0.0.1:<port> user@remote-host

然後在瀏覽器中正常開啟授權 URL；重新導向透過隧道傳輸，監聽器接收它。當你需要流程自動完成時（例如無法互動式貼上的腳本化重新認證），使用此方法。

陷阱 — 30 秒設定重載競態。 如果你從運行中的 Hermes 工作階段內部編輯 ~/.hermes/config.yaml 以新增 OAuth MCP 伺服器，CLI 會以 30 秒逾時自動重載 MCP 連線。這時間不足以完成互動式 OAuth 流程，重載會放棄。改用從新終端機執行 hermes mcp login <server> — 它沒有此上限，會等待完整的 5 分鐘讓你貼回。

為什麼監聽器不能綁定 0.0.0.0

xAI 和 Spotify 都對 redirect_uri 參數驗證允許清單。兩者都需要迴圈形式（http://127.0.0.1:<確切連接埠>/callback）。將監聽器綁定到 0.0.0.0 或不同連接埠會導致認證伺服器因 redirect_uri 不匹配而拒絕請求。SSH 隧道保持迴圈 URI 端到端完整。

逐步指引：單一 SSH 跳

1. 從你的本機機器啟動隧道

# xAI Grok OAuth（連接埠 56121）
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# 或用於 Spotify（連接埠 43827）
ssh -N -L 43827:127.0.0.1:43827 user@remote-host

-N 表示「不開啟遠端 shell，只保持隧道開啟。」在登入期間保持此終端機運行。

2. 在另一個 SSH 工作階段中，執行認證指令

ssh user@remote-host
hermes auth add xai-oauth --no-browser
# 或用於 Spotify：
# hermes auth add spotify --no-browser

Hermes 偵測 SSH 工作階段，跳過瀏覽器自動開啟，並列印授權 URL 加上 Waiting for callback on http://127.0.0.1:<port>/callback 行。

3. 在你的本機瀏覽器中開啟 URL

從遠端終端機複製授權 URL 並貼到你筆記型電腦的瀏覽器中。批准同意畫面。認證伺服器重新導向到 http://127.0.0.1:<port>/callback。你的瀏覽器命中隧道，請求被轉發到遠端監聽器，Hermes 列印 Login successful!。

一旦你看到成功行，就可以拆除隧道（在第一個終端機中按 Ctrl+C）。

逐步指引：透過跳板機

如果你透過堡壘/跳板主機到達 Hermes，使用 SSH 內建的 -J（ProxyJump）：

ssh -N -L 56121:127.0.0.1:56121 -J jump-user@jump-host user@final-host

這透過跳板主機串接 SSH 連線，而不將迴圈連接埠放在跳板機上。你筆記型電腦上的本地 127.0.0.1:56121 直接隧道到最終遠端主機上的 127.0.0.1:56121。

對於不支援 -J 的較舊 OpenSSH，長格式是：

ssh -N \
    -o "ProxyCommand=ssh -W %h:%p jump-user@jump-host" \
    -L 56121:127.0.0.1:56121 \
    user@final-host

Mosh、tmux、ssh ControlMaster

隧道是底層 SSH 連線的屬性。如果你在 mosh 工作階段上透過 tmux 運行 Hermes，mosh 漫遊不會攜帶 -L 轉發。僅為 -L 隧道開啟一個獨立的純 SSH 工作階段 — 那是在認證流程期間必須保持存活的連線。你的互動式 mosh/tmux 工作階段可以繼續正常運行 Hermes。

如果你使用 ssh -o ControlMaster=auto，多重連線連線上的連接埠轉發共享主控端的存活期。如果隧道未啟動，請重啟主控端：

ssh -O exit user@remote-host
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

疑難排解

bind [127.0.0.1]:56121: Address already in use

你筆記型電腦上某些東西已經在使用該連接埠。可能是先前的隧道未正常關閉，或本地 Hermes 也在監聽它。找出並終止它：

# macOS / Linux
lsof -iTCP:56121 -sTCP:LISTEN
kill <PID>

然後重試 ssh -L 指令。

「Could not establish connection. We couldn't reach your app.」（xAI）

xAI 的授權頁面在重新導向到 127.0.0.1:<port>/callback 未到達監聽器時顯示此訊息。可能是隧道未運行、連接埠錯誤，或你使用的是 Hermes 先前執行時列出的連接埠（如果首選連接埠忙碌，連接埠可能會自動提升 — 務必讀取最新的 Waiting for callback on ... 行）。

xAI authorization timed out waiting for the local callback

與上述相同的根本原因 — 重新導向從未返回。檢查隧道是否仍然存活（ssh -N 不顯示輸出，因此查看你啟動它的終端機），必要時重啟，並重新執行 hermes auth add xai-oauth --no-browser。

權杖落入錯誤的 ~/.hermes

權杖寫入執行 hermes auth add ... 的 Linux 使用者下。如果你的閘道 / systemd 服務以不同使用者（例如 root 或專用的 hermes 使用者）運行，請以該使用者身分認證，以便權杖落入其 ~/.hermes/auth.json。sudo -u hermes -i 或等效指令。

另請參閱

• xAI Grok OAuth
• Spotify（透過 SSH 運行）
• 原生 MCP 用戶端（OAuth 部分）
• SSH -J / ProxyJump（手冊頁）

---

---

操作 Teams 會議管線