跳到主要内容

通过 SSH / 远程主机进行 OAuth

部分 Kopi Agent provider(服务提供商)——Spotify 和远程 MCP 服务器(Linear、Sentry、Atlassian、Asana、Figma 等)——采用回环重定向 OAuth 流程。认证服务器会将你的浏览器重定向到 http://127.0.0.1:<port>/callback,以便由 Kopi Agent 启动的一个小型 HTTP 监听器捕获授权码。

当 Kopi Agent 和你的浏览器位于同一台机器上时,这种方式运行良好。一旦不是如此就会失效:你笔记本上的浏览器会尝试访问你笔记本上的 127.0.0.1,而监听器却绑定在远程服务器的 127.0.0.1 上。

解决办法是一行 SSH 本地端口转发。对于在交互式终端上运行的 MCP 服务器,通常也可以直接回填重定向 URL(无需隧道)。

xAI Grok OAuth (xai-oauth) 使用 OAuth 设备码,而非回环回调——在任意浏览器中打开输出的验证 URL,Kopi Agent 会持续轮询直到获得批准。不需要 SSH 隧道。参见 xAI Grok OAuth。

TL;DR​

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

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

Kopi Agent 会在 Waiting for callback on ... 那一行输出它实际绑定的端口——从那里复制即可。Spotify 默认端口为 43827。

哪些 Provider 需要这样做​

Provider回环端口是否需要隧道?
Spotify43827(默认)需要,当 Kopi Agent 位于远程时
MCP 服务器(auth: oauth)按服务器自动选取需要,当 Kopi Agent 位于远程时(或回填重定向 URL)
xai-oauth(Grok SuperGrok)不适用不需要——设备码流程
anthropic(Claude Pro/Max)不适用不需要——粘贴代码流程
openai-codex(ChatGPT Plus/Pro)不适用不需要——设备码流程
minimax、kopi-proxy不适用不需要——设备码流程

如果你的 provider 不在表中,则无需隧道。

MCP 服务器​

远程 MCP 服务器(Linear、Sentry、Atlassian、Asana、Figma 等)使用相同的回环重定向流程。Kopi Agent 会为每个服务器自动选取一个空闲端口,并在 OAuth 流程启动时输出授权 URL——无论是在启动时(当 mcp_servers: 中出现新服务器时),还是在你运行 kopi mcp login <server> 时。

你可以通过以下两种方式在远程主机上完成流程:

选项 1——回填重定向 URL(无需任何设置,任何环境都适用)。 在交互式终端上,Kopi Agent 会在运行本地监听器的同时提示你粘贴重定向 URL。在浏览器中批准后,重定向到 http://127.0.0.1:<port>/callback 会显示连接错误——这是正常现象。复制浏览器地址栏中的完整 URL,并粘贴到 Kopi Agent 的提示处:

  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 端口转发(与 Spotify 相同)。 Kopi Agent 会在 SSH 会话提示中输出它实际绑定的端口。在你的笔记本上另开一个终端:

ssh -N -L <port>:127.0.0.1:<port> user@remote-host

然后像平常一样在浏览器中打开授权 URL;重定向会经隧道传输,监听器即可接收到。当你需要无人值守地完成该流程时(例如脚本化重新认证、无法交互粘贴),请使用此方式。

陷阱——30 秒配置重载竞态。 如果你在运行中的 Kopi Agent 会话内编辑 ~/.kopi/config.yaml 来添加 OAuth MCP 服务器,CLI 会以 30 秒超时自动重载 MCP 连接。这段时间不足以完成交互式 OAuth 流程,重载会放弃。请改为从一个新终端运行 kopi mcp login <server>——它没有此限制,会完整等待 5 分钟让你回填。

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

Spotify 和大多数 MCP OAuth 服务器会根据白名单校验 redirect_uri 参数。两者都要求使用回环形式(http://127.0.0.1:<exact-port>/callback)。将监听器绑定到 0.0.0.0 或其他端口会导致认证服务器因 redirect_uri 不匹配而拒绝请求。SSH 隧道能端到端保持回环 URI 不变。

分步操作:单次 SSH 跳转​

1. 在本地机器上启动隧道​

# Spotify (port 43827)
ssh -N -L 43827:127.0.0.1:43827 user@remote-host

-N 表示"不要打开远程 shell,只需保持隧道开启"。在登录期间请保持该终端运行。

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

ssh user@remote-host
kopi auth add spotify --no-browser

Kopi Agent 会检测到 SSH 会话,跳过自动打开浏览器,并输出一个授权 URL 和一行 Waiting for callback on http://127.0.0.1:<port>/callback。

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

从远程终端复制授权 URL,并粘贴到笔记本上的浏览器中。在同意屏幕上完成批准。认证服务器会重定向到 http://127.0.0.1:<port>/callback。你的浏览器命中隧道,请求被转发到远程监听器,Kopi Agent 随即输出 Login successful!。

看到成功输出后即可拆除隧道(在第一个终端按 Ctrl+C)。

分步操作:通过跳板机​

如果你通过堡垒机/跳板机访问 Kopi Agent,请使用 SSH 内置的 -J(ProxyJump):

ssh -N -L 43827:127.0.0.1:43827 -J jump-user@jump-host user@final-host

这种方式将 SSH 连接经跳板机串联起来,而无需把回环端口暴露在跳板机本身上。你笔记本上的本地 127.0.0.1:43827 会直接隧道连通到最终远程主机上的 127.0.0.1:43827。

对于不支持 -J 的旧版 OpenSSH,等价的长写法是:

ssh -N \
-o "ProxyCommand=ssh -W %h:%p jump-user@jump-host" \
-L 43827:127.0.0.1:43827 \
user@final-host

Mosh、tmux、ssh ControlMaster​

隧道是底层 SSH 连接的属性。如果你在 mosh 会话之上的 tmux 中运行 Kopi Agent,mosh 的漫游不会携带 -L 转发。请仅为 -L 隧道另开一个独立的普通 SSH 会话——认证流程期间必须保持存活的是这条连接。你的交互式 mosh/tmux 会话可以照常继续运行 Kopi Agent。

如果你使用 ssh -o ControlMaster=auto,多路复用连接上的端口转发会与 master 共享生命周期。如果隧道没有建立,请重启 master:

ssh -O exit user@remote-host
ssh -N -L 43827:127.0.0.1:43827 user@remote-host

故障排查​

bind [127.0.0.1]:43827: Address already in use​

你的笔记本上已有其他程序占用了该端口。可能是之前的隧道没有正常关闭,也可能本地 Kopi Agent 同样在监听该端口。找到并结束占用端口的进程:

# macOS / Linux
lsof -iTCP:43827 -sTCP:LISTEN
kill <PID>

然后重试 ssh -L 命令。

授权在等待本地回调时超时​

重定向请求从未返回到远程监听端。请检查隧道是否仍然存活(ssh -N 不会显示输出,因此请查看启动它的终端),确认你使用的是最新 Waiting for callback on ... 行中显示的端口(如果首选端口被占用,Kopi Agent 可能会自动递增端口号),必要时重启隧道,然后重新运行授权命令。

Token 落入了错误的 ~/.kopi​

Token 会被写入运行 kopi auth add ... 的 Linux 用户下。如果你的 gateway / systemd 服务以其他用户身份运行(例如 root 或专用的 kopi 用户),请以该用户身份进行认证,使 Token 写入其 ~/.kopi/auth.json。sudo -u kopi -i 或等效方式。

另请参阅​