OAuth 通过 SSH / 远程主机
某些 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 本地转发命令。
快速总结（TL;DR）
ssh -L `56121`:localhost:`56121` user@host
端口 56121 是 xAI OAuth 使用的。对于 Spotify，请替换为 43827。Hermes 在 Waiting for callback on ... 行中打印了它实际绑定的端口——请从那里复制该端口号。
哪些提供方需要此操作
| 提供方 | 回环端口 | 是否需要隧道？ |
|---|---|---|
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 或其他端口，认证服务器会因重定向地址不匹配而拒绝请求。SSH 隧道能确保整个流程中的回环 URI 完整无损。
分步指南：单跳 SSH
1. 从本地机器启动隧道
ssh -L `56121`:localhost:`56121` user@host -N
-N 表示“不要打开远程 shell，仅保持隧道开启”。请在此终端中保持该命令运行，直到登录完成。
2. 在另一个 SSH 会话中运行认证命令
hermes auth --provider=xai-grok
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）。
分步指南：通过跳板机（Jump Host）
如果你通过堡垒机/跳板机访问 Hermes，可使用 SSH 内置的 ProxyJump 功能：
ssh -L `56121`:localhost:`56121` -o ProxyJump=user@jump-host user@final-host
这会在不将回环端口暴露于跳板机的情况下，建立一条通过跳板机的 SSH 连接。你本地的 127.0.0.1:56121 会直接穿透到最终远程主机的 127.0.0.1:56121。
对于较旧版本的 OpenSSH（不支持 ProxyJump），可使用长格式：
ssh -L `56121`:localhost:`56121` -o "ProxyCommand=ssh user@jump-host -W %h:%p" user@final-host
Mosh、tmux、SSH ControlMaster
隧道是底层 SSH 连接的属性。如果你在 mosh 会话中运行 Hermes，mhos 的漫游功能不会携带 -L 转发。因此，请单独开启一个普通的 SSH 会话，仅用于 -L 隧道——这个连接必须在整个认证流程期间保持活跃。你正常的 mosh/tmux 交互会话可以继续运行 Hermes。
如果你使用 ControlMaster，多路复用连接上的端口转发共享主连接的生命周期。如果隧道未正常启动，请重启主连接：
ssh -S /tmp/ssh-control -O exit user@host
故障排除
Address already in use（端口已被占用）
你笔记本电脑上的某个进程已占用了该端口。可能是之前的隧道未正确关闭，或本地运行的 Hermes 也在监听该端口。查找并终止相关进程：
lsof -i :`56121`
# 或
netstat -tuln | grep `56121`
然后重新运行 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 ... 行为准）。
No response from listener（监听器无响应）
根本原因与上述相同——重定向未成功返回。检查隧道是否仍在运行（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 username hermes auth 或等效方式。