1. 把 OAuth 登录拆成四个阶段
| 阶段 | 失败表现 | 检查重点 |
|---|---|---|
| 生成授权地址 | CLI 未输出 URL | 版本与终端模式 |
| 浏览器授权 | 页面拒绝或账号受限 | 账号与区域策略 |
| Token 交换 | Premature close | VPS 出网、代理、CLI HTTP 栈 |
| 缓存凭据 | 下次仍要求登录 | HOME、权限与缓存文件 |
2. 在 VPS 上直接验证 OAuth 端点
下面的探针预期返回 HTTP 响应，即使是 400 也说明 TLS、DNS 和远端可达。不要向探针提交真实授权码。
只验证连通性
curl -I https://oauth2.googleapis.com/
node -e "fetch('https://oauth2.googleapis.com/').then(r=>console.log(r.status)).catch(console.error)"curl 与原生 Node fetch 都成功，但 CLI 仍在 Token 交换时报 Premature close，更可能是特定 CLI 版本的 HTTP 路径问题。
3. 无浏览器模式仍需要 VPS 完成 Token 交换
NO_BROWSER=true 只改变用户如何打开授权页面，不会把后续 Token 请求移到本地电脑。授权完成后，VPS 仍需访问 OAuth 服务，因此防火墙、IPv6、代理和 TLS 中间层都可能影响结果。
4. 服务器自动化优先使用 API Key
持续运行的服务器任务更适合使用 API Key，而不是依赖交互式 OAuth 刷新。将密钥放入受限的环境变量或 Secret 管理器，限制文件权限并设置预算。
当前会话占位示例
export GEMINI_API_KEY="API_KEY"
gemini --prompt "ping"5. OAuth 必须保留时的修复顺序
- 记录 CLI、Node、Linux 发行版和 shell。
- 确认系统时间与 CA 证书正常。
- 检查大小写代理变量及 DNS 解析。
- 升级当前稳定版后重新执行设备码流程。
- 仅在确认版本回归时临时回退，并保留升级检查。
- 检查 HOME 与凭据目录是否属于当前 SSH 用户。
6. 不要手工复制长期 OAuth 凭据
避免把 oauth_creds.json 在机器间复制客户端可能重新验证或刷新凭据，文件也包含敏感信息。优先使用受支持的登录流程或面向服务端的 API Key，并在排查后撤销临时凭据。
7. 常见问题
浏览器显示授权成功，为什么 VPS 仍然失败？
浏览器授权只是前半段。VPS 还需要用授权结果交换 Token，Premature close 往往发生在这条服务器出网链路。
NO_BROWSER=true 会让本地电脑交换 Token 吗？
不会。它主要改变打开授权页面的方式，后续网络请求仍由运行 Gemini CLI 的 VPS 发起。
VPS 使用 OAuth 还是 API Key 更合适？
无人值守和自动化任务通常更适合 API Key，并配合 Secret 管理、额度限制与定期轮换。
curl 成功是否证明 Gemini CLI 一定能登录？
只能证明基础网络可达。CLI 可能使用不同 HTTP 栈，因此还需结合 Node fetch、CLI 版本和日志判断。
配置教程Gemini CLI API 与 Base URL相关排查Gemini CLI 常见网络与认证问题错误总览AI API 401、429 与 5xx相关排查Gemini CLI 代理 Agent 报错相关排查Gemini CLI Base URL 认证错误
* 本文由 island AI Coding 技术团队根据官方文档与公开问题记录原创整理。公开 issue 描述的是特定版本和环境，修复状态可能变化；操作前请记录版本并保留回滚路径。更新时间：2026-09-01。