前言：为什么 Gemini CLI 会连接超时？
在终端中使用 Gemini CLI 时，最常见的问题并不是命令本身写错，而是请求没有按照预期经过 Clash。你可能会看到 ETIMEDOUT、ECONNRESET、fetch failed、Unable to connect，也可能在登录流程中长时间停留在浏览器授权页面，最后提示请求失败。
Gemini CLI 的一次完整请求，通常会涉及身份验证、API 服务、模型端点以及 Google 相关域名。浏览器能够打开网页，并不代表终端程序一定能正常访问这些服务，因为浏览器通常会自动读取系统代理，而 Node.js、Python 或其他命令行程序可能只读取环境变量，甚至完全不使用系统代理。另一方面，Clash 处于规则模式时，如果域名规则不完整，某些请求可能被错误地分配到 DIRECT，最终表现为超时。
本文按照“先确认现象，再检查代理，最后调整 DNS、TUN 和规则”的顺序，帮助你定位问题。建议每完成一个步骤就重新执行一次 Gemini CLI 命令，不要一开始同时修改多个模块，否则很难判断究竟是哪项设置发挥了作用。
排查目标
确认 Gemini CLI 使用了正确的代理端口、相关域名命中了代理规则、DNS 没有污染，并使用一个稳定且支持 Google 服务的节点完成请求。
1先判断：是 CLI、代理还是节点的问题
排查连接超时时，第一步不是立刻重装客户端，而是把问题拆成三个层级。这样可以快速缩小范围，避免把配置文件改得越来越复杂。
| 现象 | 更可能的原因 | 优先检查项 |
|---|---|---|
| 浏览器打不开 Gemini，CLI 也超时 | 节点不可用、代理未启动或网络阻断 | Clash 状态、节点延迟、系统代理 |
| 浏览器正常，CLI 超时 | 终端没有读取代理环境变量 | HTTP_PROXY、HTTPS_PROXY、端口 |
| 登录页能打开，授权后失败 | 认证域名分流不完整、回调被拦截 | Google 登录域名、规则模式、TUN |
| 偶尔成功，随后频繁失败 | 节点拥堵、IP 信誉差或 DNS 不稳定 | 更换节点、固定策略组、检查 DNS |
如果终端提示的是 401 或 403，通常属于账号、权限、API Key 或地区策略问题，不应简单当作网络超时处理；如果提示 ENOTFOUND，则更接近 DNS 解析失败；如果是 ECONNREFUSED，往往意味着填写了错误的本地代理端口，或者 Clash 的混合端口没有监听。
2检查 Clash：模式、端口与节点
打开 Clash Verge Rev 或其他 Clash 图形客户端，先确认核心处于运行状态，并且当前配置文件已经成功加载。很多“超时”其实发生在配置文件过期、订阅失效或策略组没有可用节点之后。观察 Clash 面板中的请求记录，如果执行 Gemini CLI 时完全没有出现新的连接记录，说明流量根本没有进入 Clash。
确认代理模式与策略组
排查阶段建议暂时使用 Rule（规则）模式，并在主策略组中手动选择一个稳定节点。不要一开始使用自动测速、负载均衡或大量节点的复杂策略组，因为自动切换可能让登录过程中的不同请求使用不同出口 IP，从而触发认证异常。若规则模式仍然无法判断，也可以短暂切换到 Global（全局）模式进行对比测试。
测试结论
全局模式可以连接、规则模式不能连接，基本可以确定是域名规则或规则顺序问题；两种模式都不能连接，则应优先检查节点、端口、DNS 或网络本身。
确认本地代理端口
Clash 常见的混合端口可能是 7890，但不同客户端或用户配置可能使用 7897、7898 或其他端口。必须以 Clash 设置页面实际显示的端口为准。可以在终端执行以下命令测试本地代理是否能够建立连接：
如果返回 HTTP 响应，说明本地端口至少能够接收请求；如果出现 Connection refused，请更换为实际端口，或开启 Clash 的混合端口。测试时不要把订阅链接、节点密码或完整配置文件发布到公开论坛。
3让 Gemini CLI 明确使用 Clash 代理
终端程序是否使用代理，取决于它自身的实现。最稳妥的做法是在启动 Gemini CLI 前显式设置代理环境变量。对于 HTTP、HTTPS 请求，可以先在当前终端窗口临时设置：
如果你的 Clash 只开启了 SOCKS 端口，就不要把 HTTP 代理地址写成 SOCKS 端口；反过来也一样。优先使用 Clash 的混合端口，因为它通常同时兼容 HTTP 和 SOCKS5。设置后可以用以下命令确认变量是否生效：
- 先启动 Clash，并手动选择一个已确认可用的节点。
- 确认混合端口，例如
7890，然后在终端设置HTTP_PROXY和HTTPS_PROXY。 - 使用
curl请求 Gemini 相关域名，观察 Clash 的连接记录是否出现对应请求。 - 确认测试成功后，再启动 Gemini CLI；不要在多个终端窗口中混用不同端口。
注意
环境变量只对当前终端会话有效。若你通过 IDE、桌面快捷方式或脚本启动 CLI，需要在对应的运行环境中单独配置代理。
4补齐规则并处理 DNS 解析异常
Gemini CLI 不只访问一个域名。登录、API 调用、配置读取和安全验证可能涉及不同的 Google 服务。如果只给某一个域名添加代理规则，仍然可能出现登录成功但模型请求超时的情况。建议把相关规则放在自定义规则或规则集的靠前位置，确保不会被后面的兜底规则覆盖。
上面的策略组名称 Gemini 必须与配置文件中真实存在的策略组一致。如果你的配置使用的是 PROXY、🚀 节点选择 或其他名称，请替换为实际名称。规则顺序同样重要：自定义域名规则应放在 GEOIP,CN,DIRECT 或 MATCH,DIRECT 之前。
DNS 方面，建议在 Clash 中启用 DNS 模块，并根据客户端能力使用 fake-ip 或 redir-host。如果开启 fake-ip 后某些本地程序异常，可以将局域网域名、本地设备名加入过滤列表，不要为了修复一个应用而完全关闭 Clash DNS。
修改 DNS 后要清理系统缓存并重新启动 CLI。Windows 可以执行 ipconfig /flushdns；macOS 可重启网络服务或直接重启系统；Linux 则需要根据使用的 systemd-resolved、NetworkManager 等组件清理缓存。
5仍然超时：启用 TUN 模式接管系统流量
如果显式设置环境变量后仍然没有请求记录，或者 Gemini CLI 使用的运行时不支持标准代理变量，可以尝试开启 TUN 模式。TUN 会在系统中创建虚拟网卡，让 Clash 在网络层接管更多应用流量，不再完全依赖应用是否支持 HTTP 代理。
- 在 Clash 客户端中打开 TUN 设置，启用 TUN 服务或增强模式。
- 按系统提示授予网络扩展、管理员或虚拟网卡权限。
- 打开“自动路由”或同类选项，让系统流量进入 Clash。
- 保持 Rule 模式，并确认 Gemini 相关域名命中
Gemini策略组。 - 重新运行 CLI，观察连接记录、DNS 查询和策略组命中情况。
TUN 使用提醒
TUN 模式需要较高系统权限，可能与其他 VPN、虚拟机网卡、公司安全软件或网络加速器冲突。测试时请先关闭同类软件；如果出现所有网络都变慢，应立即关闭 TUN 并恢复原来的网络设置。
在 Windows 上，如果 Clash 提示无法创建网卡，通常与服务权限、Wintun 驱动或其他 VPN 占用有关；在 macOS 上则要检查系统网络扩展是否允许；Linux 用户还需要确认内核权限、路由表和防火墙设置。TUN 并不是节点质量的替代品，它只能解决“流量没有被接管”的问题。
6节点、认证与最终验证
当代理端口、规则和 DNS 都正常后，如果仍然出现请求失败，就要把重点放到节点质量和认证状态上。Gemini CLI 的登录或 API 请求对连接稳定性比较敏感，节点即使能够打开普通网页，也可能在长连接、TLS 握手或持续请求时频繁断开。
- 更换节点区域：尝试美国、日本或其他服务支持良好的节点，并避免频繁切换出口。
- 观察延迟之外的指标：测速低不代表稳定，重点查看丢包、握手时间和连续请求是否中断。
- 固定策略组：登录和测试期间不要使用每次请求都可能更换节点的负载均衡组。
- 检查账号权限：确认登录的是正确的 Google 账号，API Key、项目权限和配额没有过期或耗尽。
- 清理旧认证：如果浏览器回调反复失败，可以退出 CLI 后重新进行授权，但不要随意删除仍在其他工具中使用的凭据文件。
最后可以按照下面的顺序做一次完整验证：先用代理访问 Google 登录页，再用 curl 测试 API 域名，确认 Clash 日志显示正确策略组，然后运行 Gemini CLI 发起一个简短请求。如果只有最后一步失败，应查看 CLI 自身的版本、运行时和认证日志；如果 curl 也失败，则继续处理节点或 Clash 配置。
推荐的稳定组合
Clash 使用 Rule 模式，Gemini 相关域名固定走稳定策略组；终端显式设置混合端口；DNS 由 Clash 接管；必要时开启 TUN，并在登录期间避免自动切换节点。
总的来说，Gemini CLI 超时并不等于账号失效。只要按照“节点可用性—Clash 端口—终端代理—规则分流—DNS—TUN—认证权限”的顺序逐项验证，绝大多数问题都能被定位。修改配置后记得保留一份原始备份，确认稳定运行后再逐步精简规则，便于今后升级订阅或更换客户端。