无图形界面服务器登录 Gemini CLI：SSH 端口转发解决 OAuth 回调
远程服务器没有浏览器，Gemini CLI 的 OAuth 登录会卡在回调地址连不上这一步。本文拆解登录流程的原理，给出三条可操作路径：SSH 本地端口转发、把回调 URL 复制到服务器用 curl 完成、改用 API Key 免交互登录，并附上端口排查清单与凭据安全提醒。
在一台没有桌面环境的远程服务器上跑 AI 命令行工具，第一步往往就卡住：工具要求用浏览器完成账号授权，而服务器上既没有浏览器，也打不开图形界面。
典型现象是：把终端打印出来的登录链接复制到本地浏览器，账号选完、权限也同意了，页面却跳到一个 localhost:某端口 的地址并提示无法连接，与此同时远程终端一直停在「等待授权」不动。这不是账号或网络的问题，而是 OAuth 回调打到了错误的机器上。下面把原理和几种可行做法讲清楚。
问题本质：回调落在了错误的机器
这类 CLI 走的是标准的 OAuth 授权码流程：启动登录时，程序会在本机回环地址上临时起一个 HTTP 服务监听某个端口，并生成一个授权链接，其中 redirect_uri 指向 http://localhost:端口/...。用户在浏览器里同意授权后，授权服务器会把浏览器重定向回这个地址，并带上一次性的 code；CLI 拿到 code 再换取访问令牌。
服务器上没有浏览器，链接只能拿到本地电脑上打开。于是浏览器的重定向目标是「本地电脑的 localhost:端口」——那个端口上什么都没有，请求自然被拒绝，而远程的 CLI 一直等不到 code。
所以所有方案都围绕同一件事：让这条回调落到 CLI 正在监听的那个端口上。
第一步：拿到授权链接和回调端口
无论走哪种方案，都得先知道这两个信息：
- 授权链接：启动时加上调试参数（例如
--debug），程序会打印本次会话的登录 URL；URL 里的redirect_uri参数通常就写明了端口号。 - 监听端口：另开一个 SSH 会话直接观察，比猜更可靠。
# 查看本机正在监听的 TCP 端口
ss -ltnp | grep -i node
# 老系统可以用
netstat -ltnp | grep LISTEN
记下端口和完整链接。此时先别急着点授权——先点也能补救，只是要多一步复制粘贴。
方案一：SSH 本地端口转发（推荐）
思路很直接：把本地电脑的某个端口转发到远程的回调端口，浏览器访问本地端口时，实际应答的是远程的 CLI。
ssh -N -L 8080:127.0.0.1:8080 user@your-server
-N表示只做转发、不开 shell；左边是本地端口，右边是远程回环地址加端口。- 建议让本地端口与远程端口保持一致。因为
redirect_uri里写死了端口，浏览器跳转的目标端口必须与转发出来的本地端口相同，端口不一致时浏览器会打到别的服务上。 - 本地端口被占用就换一个，但换完要确认链接里的端口也跟着对得上。
操作顺序：
- 先在本地终端建立隧道，窗口保持不关；
- 在本地浏览器打开授权链接，选账号并同意；
- 浏览器跳到
http://localhost:端口/...，这次能连上，请求经隧道送到远程，CLI 收到 code，终端提示登录成功。
如果用的是 VS Code Remote-SSH、JetBrains Gateway 这类远程开发工具，直接在端口面板里转发同一个端口，效果一样且更好管理。
顺序上先建隧道再授权最顺；如果先授权了，浏览器报「无法连接」也不一定要从头再来，地址栏里那条完整回调 URL 依然可用，见方案二。
方案二：把回调 URL 拿到服务器上 curl
不想开隧道，或者已经拿到了那条带 code 的回调地址，可以直接在远程机器上发起请求：
curl -i 'http://127.0.0.1:端口/oauth2callback?code=XXXX&state=YYYY'
几个细节：
- 整条 URL 必须用单引号包住，否则
&会被 shell 当作后台执行符号截断； - 路径和参数名按浏览器地址栏里的原样复制，不要自己改写；
code是一次性的，且有效期很短，拿到就立刻用，失败就重新发起一次登录；state不匹配通常意味着用了上一次会话的链接。
这条路径不需要额外终端窗口，适合一次性操作；缺点是凭据会进入 shell 历史记录，事后记得清理，或使用不写历史的方式执行。
方案三：改用 API Key 免去交互登录
如果目的只是让 CLI 在无人值守的环境里跑起来，长期凭据往往更省事：
export GEMINI_API_KEY="你的密钥"
可以写进 ~/.bashrc、~/.zshrc，或通过 systemd 的 EnvironmentFile、容器的 secret 机制注入。具体的变量名、优先级、以及是否支持这种鉴权方式，务必以官方文档和 --help 输出为准，不同版本之间可能调整。
| 方式 | 适用场景 | 代价与限制 |
|---|---|---|
| 浏览器 OAuth 登录 | 个人日常使用，希望用账号自带的额度或订阅权益 | 需要浏览器配合，令牌过期后要重新授权 |
| API Key | CI、脚本、长期无人值守的服务 | 独立计量与配额，密钥需要妥善保管，泄露即等于账号被用 |
不要把密钥提交进 Git 仓库，也不要在共享机器上写进全局 profile。
常见坑与排查清单
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 每次端口都不一样 | 回调端口是随机分配的，不要假设固定值 | 每次按第一步重新查一遍再转发 |
| 转发了仍然连接被拒 | 目标写成了 localhost 而服务只监听 127.0.0.1（或反过来解析到 IPv6 的 ::1） |
统一写成 127.0.0.1，并确认隧道进程还活着 |
| 多层跳板或容器环境 | 回调端口只在最内层可见 | 逐层转发，或用跳板参数一次连到目标机；容器内监听回环地址时，端口需要能从宿主机映射出来 |
| 浏览器一直转圈 | 公司代理拦截了 localhost 请求 | 临时让 localhost 绕过代理，或改用 curl 方案 |
| 登录成功但很快失效 | 系统时间漂移导致令牌校验失败 | 检查 NTP 同步状态 |
安全与合规提醒
回调 URL 里带的授权码等同于临时凭据，不要贴到公开的聊天群、issue 或录屏里。请始终使用自己的账号在自己的设备上完成授权，不要买卖或共享账号，也不要为了绕过地区限制去借用他人的凭据——这类做法违反服务条款，凭据被回收时受影响的是自己的工作进度。企业环境下，密钥的申请与存放通常有审批流程，先问清楚再动手。
小结
核心只有一句话：让浏览器的回调落到 CLI 正在监听的端口上。三条路径各自成立——用 ssh -L 本地端口:127.0.0.1:远程端口 把回调搬过去，最适合个人临时使用；把回调 URL 复制到服务器上 curl，适合不想开第二个终端的人；改用 API Key，则适合需要长期无人值守运行的场景。
如果任务本身需要长时间挂着跑，而本地电脑休眠、断网会打断会话，也可以把运行环境放到一台常驻机房、可长期在线运行的远程 Mac 上，通过 SSH 或远程桌面连接使用，登录环节同样按上面的端口转发方式处理即可。动手前建议先确认所用工具当前版本的参数与鉴权方式，以官方最新说明为准。
