SSH / 远程主机上的 OAuth

部分 Hermes 提供商——目前是 xAI Grok OAuth 和 Spotify——使用回环重定向（loopback redirect） OAuth 流程。认证服务器（xAI、Spotify）将浏览器重定向到 http://127.0.0.1:<port>/callback，由 hermes auth ... 命令启动的一个小型 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 标志。

快速概览

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 model --manual-paste。如果不想粘贴完整 URL，也可以只接受裸的 ?code=...&state=... 查询片段。

Hermes 对两种路径使用相同的 PKCE verifier、state 和 nonce，因此上游 OAuth 流程在字节层面完全一致——--manual-paste 纯粹是回调跳转的传输方式变更，不会降低安全性。

哪些提供商需要此操作

提供商	回环端口	需要隧道？
`xai-oauth`（Grok SuperGrok）	`56121`	是，当 Hermes 在远程时
Spotify	`43827`	是，当 Hermes 在远程时
`anthropic`（Claude Pro/Max）	不适用	否——粘贴代码流程
`openai-codex`（ChatGPT Plus/Pro）	不适用	否——设备码流程
`minimax`、`nous-portal`	不适用	否——设备码流程

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

为什么监听器不能直接绑定 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. 从本地机器启动隧道

-N 表示"不打开远程 shell，只保持隧道开启"。在登录期间保持此终端运行。

2. 在另一个 SSH 会话中运行认证命令

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 连接，而不会将回环端口暴露在跳板机上。你笔记本上的本地 127.0.0.1:56121 直接隧道到最终远程主机上的 127.0.0.1:56121。

对于不支持 -J 的旧版 OpenSSH，完整写法为：

Mosh、tmux、ssh ControlMaster

隧道是底层 SSH 连接的属性。如果你在 mosh 会话中的 tmux 里运行 Hermes，mosh 的漫游不会携带 -L 转发。单独开一个普通 SSH 会话仅用于 -L 隧道——这个连接必须在整个认证流程期间保持存活。你的交互式 mosh/tmux 会话可以继续正常运行 Hermes。

如果你使用 ssh -o ControlMaster=auto，多路复用连接上的端口转发共享主连接的生命周期。如果隧道未能建立，重启主连接：

故障排查

`bind [127.0.0.1]:56121: Address already in use`

你笔记本上已有某个程序占用了该端口。可能是上一个隧道没有正常关闭，或者本地也有一个 Hermes 在监听。找到并终止占用进程：

然后重试 ssh -L 命令。

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

当 xAI 重定向到 127.0.0.1:<port>/callback 未能到达监听器时，xAI 的授权页面会显示此错误。可能是隧道未运行、端口错误，或者你使用的是 Hermes 上一次运行时打印的端口（如果首选端口被占用，端口可能会自动递增——始终以最新的 Waiting for callback on ... 行为准）。

`xAI authorization timed out waiting for the local callback`

与上述原因相同——重定向从未返回。检查隧道是否仍然存活（ssh -N 不显示输出，查看启动它的终端），必要时重启，然后重新运行 hermes auth add xai-oauth --no-browser。

Token 写入了错误的 `~/.hermes`

Token 写入运行 hermes auth add ... 的 Linux 用户目录下。如果你的网关 / systemd 服务以不同用户（如 root 或专用的 hermes 用户）运行，请以该用户身份进行认证，使 token 写入其 ~/.hermes/auth.json。使用 sudo -u hermes -i 或等效命令。

另请参阅

xAI Grok OAuth

Spotify（通过 SSH 运行）

SSH -J / ProxyJump（man 手册）

"SSH / 远程主机上的 OAuth"

SSH / 远程主机上的 OAuth#

快速概览#

仅限浏览器的远程环境（Cloud Shell / Codespaces / EC2 Instance Connect）#

哪些提供商需要此操作#

为什么监听器不能直接绑定 0.0.0.0#

分步说明：单跳 SSH#

1. 从本地机器启动隧道#

2. 在另一个 SSH 会话中运行认证命令#

3. 在本地浏览器中打开 URL#

分步说明：通过跳板机#

Mosh、tmux、ssh ControlMaster#

故障排查#

bind [127.0.0.1]:56121: Address already in use#

"Could not establish connection. We couldn't reach your app."（xAI）#

xAI authorization timed out waiting for the local callback#

Token 写入了错误的 ~/.hermes#

另请参阅#