跳到主要内容

通过 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

参考链接​