Hermes Agent OAuth 远程登录指南：SSH 端口转发与远程服务器配置

当 Hermes Agent 运行在远程服务器或容器中时，基于浏览器的 OAuth 登录流程（如 xAI Grok、Spotify）会因为 loopback 重定向而中断——你的浏览器访问的是本地 127.0.0.1，而监听器却在远程机器上。本文介绍如何通过 SSH 本地端口转发打通这条链路，覆盖单跳、ProxyJump 跳板机、mosh/tmux 会话及常见排错场景。

速览

# On your local machine (laptop), in a separate terminal:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# In your existing SSH session on the remote machine:
hermes auth add xai-oauth --no-browser
# → Hermes prints an authorize URL. Open it in a browser on your laptop.
# → Your browser redirects to 127.0.0.1:56121/callback, the tunnel forwards
#   the request to the remote listener, login completes.

端口 56121 是 xAI OAuth 使用的端口。Spotify 则使用 43827。Hermes 会在 Waiting for callback on ... 行打印实际绑定的端口——从那里复制即可。

哪些 Provider 需要端口转发

如果你的 Provider 不在表中，则不需要隧道。

为什么监听器不能绑定 0.0.0.0

xAI 和 Spotify 都会根据白名单校验 redirect_uri 参数，两者都要求使用 loopback 形式（http://127.0.0.1:<exact-port>/callback）。如果将监听器绑定到 0.0.0.0 或使用不同端口，认证服务器会因 redirect_uri 不匹配而拒绝请求。SSH 隧道保证了 loopback URI 端到端不变。

分步指南：单跳 SSH

1. 从本地机器启动隧道

# xAI Grok OAuth (port 56121)
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Or for Spotify (port 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
# or for 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 连接，而不会在跳板机上暴露 loopback 端口。本地 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。

Token 写入了错误的 ~/.hermes

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

相关文档

• xAI Grok OAuth
• Spotify (Running over SSH)
• SSH -J / ProxyJump (man page)