hermes教程-通过SSH/远程主机进行OAuth

通过SSH/远程主机进行OAuth

某些 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 标志。

TL;DR

## 在你的本地机器（笔记本电脑）上，另开一个终端：
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，隧道将请求转发到远程监听器，登录完成。

端口 56121 是 xAI OAuth 使用的。对于 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 在基于浏览器的控制台上的当前行为）— 仅裸的 code 值本身。

Hermes 对两种路径使用相同的 PKCE verifier、state 和 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:<exact-port>/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 转发。请打开一个单独的纯 SSH 会话，仅用于 -L 隧道 — 这是必须在认证流程期间保持活动的连接。你的交互式 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 (Running over SSH)
• Native MCP client (OAuth section)
• SSH -J / ProxyJump (man page)