通过 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-oauth	56121	需要 SSH 转发或 manual paste
Spotify	43827	需要 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

参考链接

• 官方原文：OAuth over SSH / Remote Hosts
• xAI Grok OAuth