Gemini CLI 登录卡住与请求超时：认证、代理变量、出口线路三类原因怎么区分

Gemini CLI 登录超时和请求超时，为什么要先分类再动手

Gemini CLI 登录卡在 Waiting for auth、提示 Authentication timed out，或者登录成功后请求一直转圈，表面上都是「超时」，背后却是三种完全不同的原因：认证配置本身有冲突、代理变量没有被登录流程读取、出口线路对长连接不稳定。把 Gemini CLI 超时问题先归类再处理，可以避免把时间浪费在重装和换版本上。本文对照 Gemini CLI 官方文档与 GitHub 上的公开 issue 整理，查阅日期为 2026 年 9 月 20 日；CLI 更新很快，具体参数请以你本机 gemini --help 为准。

下面先看官方文档里明确写出的认证方式，再看代理变量这个最容易出错的环节，最后用一张表把三类原因和排查动作对应起来。

认证类原因：环境变量互相打架比想象中常见

官方文档列出的认证方式有四种：用 Google 账号登录、Gemini API Key、Vertex AI，以及无界面（headless）模式。前三种在使用上有一个共同点，就是依赖环境变量，而环境变量恰恰是最容易被忽略的干扰源。

为什么明明用个人账号登录，却提示需要组织订阅

官方排障文档提到，如果 shell 里设置了 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID，CLI 会认为你在走组织账号的路径，进而出现「You must be a named user on your organization's Gemini Code Assist Standard edition subscription」这类提示。个人用户的处理办法是把这两个变量从 .bashrc、.zshrc 以及各级 .env 文件里移除。之前为别的云项目设置过这个变量、后来忘了的人，遇到这个问题的概率不低。

API Key 登录时环境变量该放在哪里

使用 API Key 的写法是 export GEMINI_API_KEY="你的密钥"，然后启动 gemini 并选择使用 API Key。变量可以放在 shell 配置文件里，也可以放在 ~/.gemini/.env 中。要留意文档里的一句话：这些 .env 文件只会加载找到的第一个，不会合并。所以同时在项目目录和用户目录放了 .env 的话，后者里的变量可能根本没有生效。如果 CLI 进程拿不到密钥，最终表现出来的往往就是认证超时，而不是一条清晰的「密钥缺失」提示。

Vertex AI 路径还需要 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION，凭据可以来自 gcloud auth application-default login，也可以是 GOOGLE_APPLICATION_CREDENTIALS 指向的服务账号文件。三种子方式不要混用，一次只保留一种。

代理变量类原因：登录流程不一定走你设置的代理

这是最有迷惑性的一类。网络工具已经开着，浏览器访问一切正常，终端里 curl 也通，但 Gemini CLI 登录仍然超时，日志里出现类似下面的报错：

Failed to exchange authorization code for tokens: request to https://oauth2.googleapis.com/token failed, reason: connect ETIMEDOUT

GitHub 上编号 8616 的 issue 记录过这个现象：在 0.5.3 版本里，通过命令行参数 gemini --proxy http://localhost:7890 指定代理可以正常登录，而只把代理写进 .gemini/settings.json，登录阶段的令牌交换请求就没有走代理，最终连接超时。该 issue 已经关闭。同一个仓库里还有几个与代理相关的合并请求，涉及命令行参数、环境变量 http_proxy、https_proxy、all_proxy 的读取，说明这部分行为在不同版本之间确实有变化。

需要说明的是，我查阅的官方参考文档里没有专门的代理章节，所以本文不给出「某个版本一定怎样」的结论，而是给一个自己就能做的对照方法：

1. 先执行 gemini --help，看你当前版本有没有代理相关参数。
2. 在当前终端执行 env | grep -i proxy，确认变量名的大小写和端口正确。
3. 用 curl 测令牌交换所在的域名，任何 HTTP 状态码（比如 404 或 405）都说明域名可达，超时或没有返回才是问题：

curl -sS -o /dev/null -w "%{http_code} %{time_connect} %{time_appconnect}\n" https://oauth2.googleapis.com/token

4. 如果 curl 通而 CLI 不通，换一种方式再试：用命令行参数指定代理，或者用 gemini -d 打开调试日志，看请求实际停在了哪个域名。

公司网络下的证书错误是另一回事

如果日志里出现的是 UNABLE_TO_GET_ISSUER_CERT_LOCALLY，通常说明网络设备对 TLS 做了中间检查，Node.js 不认识那张证书。官方文档给了两种处理方式：设置 NODE_USE_SYSTEM_CA=1 让 Node 使用系统证书库，或者用 export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt 指向根证书文件（示例路径需要替换成实际路径）。这类报错和「超时」不同，属于握手能完成但证书链验证失败。

出口线路类原因：登录能过，用着用着就慢或断

前两类原因排除之后，如果登录成功但会话中请求偏慢、偶尔中断，就要看出口线路。Gemini CLI 的一次对话通常是持续的流式响应，线路在几秒内的丢包或路径切换，对单个 curl 请求几乎没有影响，却会让长响应中途断掉。验证思路和前面一样，用你自己环境里的记录说话：

• 同一台机器上，每分钟执行一次上面的 curl 耗时命令，连续记录半小时以上。
• 把办公网络、手机热点、家庭宽带分别测一轮，比较 time_connect 的波动，而不是只看平均值。
• 波动大且集中在某个网络环境，就说明问题在这条出口上，换工具版本并不会改善。

如果记录显示线路确实不稳定，可以给终端换一条更合适的出口。NasaCode 的 AI 智能路由面向 AI 平台的访问场景，同一套出口也用于 Claude Code、Cursor 等开发工具，适合想统一处理多个 CLI 工具连接问题的开发者。是否有效，仍建议先用上面的记录法做前后对照，用数据判断。

原因与排查动作对照表

类别	典型表现	首查动作
认证配置冲突	提示需要组织订阅；API Key 登录后仍超时	检查 GOOGLE_CLOUD_PROJECT、GEMINI_API_KEY 是否被正确加载，注意 .env 只取第一个文件
代理变量未生效	浏览器和 curl 正常，令牌交换阶段 ETIMEDOUT	gemini --help 查代理参数，用命令行参数对照，gemini -d 看日志
证书链验证失败	UNABLE_TO_GET_ISSUER_CERT_LOCALLY	设置 NODE_USE_SYSTEM_CA=1 或 NODE_EXTRA_CA_CERTS
出口线路不稳定	登录正常，流式响应中途断开	多时段记录 curl 耗时，换网络环境对照

表里第三行严格说不是超时，但很多人会把它和超时混在一起排查，所以单独列出。Gemini CLI 的认证方式、参数和文档结构会随版本调整，本文内容以 2026 年 9 月 20 日查阅的官方文档和公开 issue 为准。排查时保留每一步的命令输出，比记住结论更有用，下次遇到类似问题可以直接拿出来对照。

延伸阅读

• Codex CLI 连接超时与登录失败怎么排查：认证、网络、出口线路三层定位
• Claude Code CLI 在 CI/CD 流水线总超时?自动化调用排查指南