5ef0b8acb0
Replace the loopback/PKCE-callback server and manual-paste fallback with the RFC 8628 device-code flow as the only xAI Grok OAuth login path. The flow works in headless/SSH/container sessions with no 127.0.0.1 listener, shrinking the local attack surface. - Poll the token endpoint with server-provided interval, honoring slow_down and expires_in; store tokens with auth_mode oauth_device_code. - Adaptive proactive refresh skew for short-lived device-code JWTs; rotated tokens sync back to auth.json, the global root store, and the credential pool (no refresh-token replay). - Clear source suppression on successful re-login (CLI + dashboard) and drop the duplicate dashboard pool entry so exactly one seeded device_code entry exists. - Use the shared device_code source name for consistency with the nous/codex device-code providers. - Desktop: remove the loopback OAuth flow states and dead type variants; pkce providers' sign-in URL selection is unchanged. - Docs (EN + zh-Hans) rewritten for device-code login; drop the deleted --manual-paste flag from documented commands.
4.5 KiB
| sidebar_position | title | description |
|---|---|---|
| 17 | SSH / 远程主机上的 OAuth | 当 Hermes 运行在远程机器、容器或跳板机后面时，如何完成基于浏览器的 OAuth（Spotify、MCP 服务器） |
SSH / 远程主机上的 OAuth
部分 Hermes 提供商——Spotify 和 远程 MCP 服务器（Linear、Sentry、Atlassian、Asana、Figma 等）——使用回环重定向（loopback redirect） OAuth 流程。认证服务器将浏览器重定向到 http://127.0.0.1:<port>/callback，由 Hermes 启动的小型 HTTP 监听器获取授权码。
当 Hermes 和浏览器在同一台机器上时，这一切运行正常。一旦两者不在同一台机器上就会出问题：你笔记本上的浏览器试图访问你笔记本上的 127.0.0.1，但监听器绑定的是远程服务器上的 127.0.0.1。
解决方法是一行 SSH 本地端口转发。对于交互式终端上的 MCP 服务器，通常也可以直接粘贴重定向 URL（无需隧道）。
xAI Grok OAuth（xai-oauth）使用 OAuth 设备代码，不是回环回调——在任意浏览器中打开打印的验证 URL，Hermes 轮询直到批准即可，无需 SSH 隧道。请参阅 xAI Grok OAuth。
快速概览
# 在你的本地机器（笔记本）上，另开一个终端：
ssh -N -L 43827:127.0.0.1:43827 user@remote-host
# 在远程机器的现有 SSH 会话中：
hermes auth add spotify --no-browser
# → Hermes 打印授权 URL，在笔记本的浏览器中打开。
# → 浏览器重定向到 127.0.0.1:43827/callback，隧道转发到远程监听器，登录完成。
Hermes 会在 Waiting for callback on ... 一行打印实际绑定的端口——从那里复制。Spotify 默认端口为 43827。
哪些提供商需要此操作
| 提供商 | 回环端口 | 需要隧道？ |
|---|---|---|
| Spotify | 43827（默认） |
是，当 Hermes 在远程时 |
MCP 服务器（auth: oauth） |
每台服务器自动选择 | 是（或粘贴重定向 URL） |
xai-oauth（Grok SuperGrok） |
不适用 | 否——设备代码流程 |
anthropic（Claude Pro/Max） |
不适用 | 否——粘贴代码流程 |
openai-codex（ChatGPT Plus/Pro） |
不适用 | 否——设备码流程 |
minimax、nous-portal |
不适用 | 否——设备码流程 |
如果你的提供商不在表中，则不需要隧道。
为什么监听器不能直接绑定 0.0.0.0
Spotify 和大多数 MCP OAuth 服务器会根据白名单验证 redirect_uri 参数，并要求回环形式（http://127.0.0.1:<精确端口>/callback）。将监听器绑定到 0.0.0.0 或使用不同端口会导致认证服务器以 redirect_uri 不匹配为由拒绝请求。SSH 隧道可以端到端保持回环 URI 不变。
分步操作：单次 SSH 跳转
1. 从本地机器启动隧道
# 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 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 43827:127.0.0.1:43827 -J jump-user@jump-host user@final-host
故障排除
bind [127.0.0.1]:43827: Address already in use
笔记本上已有进程占用该端口。结束占用进程后重试 ssh -L。
等待本地回调超时
重定向未到达远程监听器。确认隧道仍在运行，并使用最新一次 Waiting for callback on ... 中的端口（首选端口被占用时 Hermes 可能自动递增）。
另请参阅
- xAI Grok OAuth——设备代码；无需 SSH 隧道
- Spotify（SSH 上运行）
- 原生 MCP 客户端（OAuth 部分）