使用 Gemini CLI 时出现连接超时、登录失败、请求一直卡住，未必是 Gemini 服务本身故障。对于 Clash 用户来说，问题可能发生在节点不可用、代理模式不正确、规则没有命中、DNS 解析异常、TUN 未接管命令行流量，甚至是系统环境变量残留等多个环节。本文以 Gemini CLI 的典型请求流程为线索，整理一套从简单到复杂的排查方法，帮助你判断到底是本机配置、Clash 规则、代理节点，还是机场服务端出现了问题。

先判断超时发生在哪个环节

Gemini CLI 的一次请求通常要经过域名解析、建立 TCP 或 TLS 连接、完成身份验证、发送 API 请求和等待服务端响应几个阶段。不同阶段的错误，处理方法完全不同。不要一看到 timeout 就立即更换一大堆配置，否则很容易把原本简单的问题变得更复杂。

  • 启动后立即提示无法连接：优先检查 Node.js、网络环境、代理环境变量以及 Clash 是否正在运行。
  • 登录页面打不开或回调失败：重点检查浏览器代理、回调地址、系统代理和 TUN 接管情况。
  • 登录成功但 API 请求超时：重点检查实际访问的 Gemini 或 Google API 域名是否命中代理规则。
  • 偶尔成功、偶尔超时：通常与节点质量、策略组自动切换、DNS 不稳定或连接复用有关。
  • 所有境外服务都无法访问：不要只盯着 Gemini CLI，应先验证 Clash 核心、节点和系统代理是否整体正常。

第一步建议打开 Clash 的 Dashboard，进入「连接」或「Connections」页面，然后重新执行一次 Gemini CLI 命令。观察是否出现新的连接记录。如果完全没有记录，说明流量没有进入 Clash；如果出现连接但命中 DIRECT，说明规则或模式有问题；如果命中代理策略组但连接失败，则应继续检查节点和 DNS。

最快的定位方法：先用浏览器访问 Gemini 相关网页，再用命令行测试同一网络。如果浏览器可以访问而 Gemini CLI 超时，问题大概率在命令行没有使用系统代理，或者终端中的 HTTP_PROXY、HTTPS_PROXY 配置不正确。

检查节点与代理模式

Gemini CLI 依赖稳定的境外连接。Clash 中显示节点延迟，并不代表该节点一定可以正常访问 Gemini。延迟测试通常只验证节点是否能连接测速地址，而不会验证目标站点是否可用。因此，排查时必须进行实际目标测试，不能只根据 Dashboard 中的绿色延迟数字下结论。

先在 Clash Dashboard 中手动选择一个确认可用的节点，不要一开始使用复杂的 url-test、fallback 或自动选择策略组。自动策略组可能根据测速地址选择了延迟最低的节点，但该节点到 Google 服务的路由质量并不好。手动固定节点后重新测试，可以排除自动切换造成的干扰。

  1. 确认 Clash 核心处于运行状态，并且订阅配置已经成功加载。
  2. 在代理策略组中手动选择一个稳定的日本、新加坡、美国或其他可用节点。
  3. 暂时关闭连接复用或复杂的链式代理，避免多跳链路增加故障点。
  4. 通过浏览器访问 Gemini 网页，确认该节点确实能打开目标服务。
  5. 保持该节点不变，再执行 Gemini CLI，比较浏览器与命令行的结果。

代理模式也会影响命令行请求。规则模式适合日常使用，但前提是规则列表包含 Gemini CLI 实际访问的域名；全局代理模式适合短时间测试，可以快速判断是否为规则问题；直连模式则会绕过代理，境外请求通常会出现连接失败或长时间等待。

测试方式 适合目的 结果如何判断
全局代理 排除规则匹配问题 全局可用而规则模式不可用，说明规则需要调整
规则模式 验证日常配置 观察 Gemini 域名是否命中代理策略组
直连模式 确认本地网络是否支持直连 直连失败但代理成功，属于正常的代理需求场景

确认命令行是否真正经过 Clash

很多用户认为打开了 Clash 的系统代理，所有程序就都会自动走代理。实际上，系统代理主要影响遵循操作系统代理设置的浏览器和桌面应用，命令行工具是否使用它，取决于具体运行时和程序实现。Gemini CLI 使用 Node.js 发起网络请求时，可能读取环境变量，也可能由内部 HTTP 客户端决定是否支持系统代理。

先查看当前终端是否存在代理环境变量。Windows PowerShell 可以执行：

Windows PowerShell 检查代理变量
Get-ChildItem Env:HTTP_PROXY
Get-ChildItem Env:HTTPS_PROXY
Get-ChildItem Env:ALL_PROXY
Get-ChildItem Env:NO_PROXY

macOS、Linux 或 Windows 的 Git Bash 可以执行：

终端检查代理变量
env | grep -i proxy

如果 Clash 的 HTTP 代理端口是 7890，SOCKS5 端口是 7891，可以在当前终端临时设置代理进行测试。端口必须以你自己的 Clash 配置为准，不能直接照搬。

macOS、Linux 临时设置代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891

gemini
Windows PowerShell 临时设置代理
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7891"

gemini

如果设置环境变量后 Gemini CLI 可以工作，说明 Clash 节点大概率没有根本故障，之前的问题是命令行没有继承系统代理。需要注意的是，某些程序对 ALL_PROXY、HTTP_PROXY 和 HTTPS_PROXY 的支持方式不同。可以先只设置 HTTP 代理，确认有效后再添加 SOCKS5，避免多个变量相互覆盖。

注意代理变量残留：如果你曾经使用过其他代理软件，旧的 HTTP_PROXY 或 HTTPS_PROXY 可能仍然指向已经关闭的端口。此时即使 Clash 正常运行，Gemini CLI 也会连接到错误地址。排查前应清理旧变量，或在新终端中重新设置。

检查规则与相关域名

规则模式下，Gemini CLI 不一定只访问一个域名。登录、账户验证、API 请求、遥测、证书校验或模型服务可能使用不同的主域名和子域名。只添加一个网页域名，往往无法覆盖完整请求链路。实际域名会随 CLI 版本和服务端调整而变化，因此最可靠的方法不是盲目复制网络列表，而是通过 Clash 的连接记录查看真实请求。

在 Dashboard 中重新运行命令，重点观察以下信息：

  • 目标域名是否为 Gemini、Google API 或相关身份验证域名。
  • 连接是否命中 DIRECT、REJECT 或预期的代理策略组。
  • 是否出现大量连接失败、TLS 握手失败或 DNS 错误。
  • 同一域名是否在不同节点之间反复切换。
  • 请求是否被某个广告拦截、隐私保护或自定义拒绝规则拦截。

如果确认目标域名被错误地直连，可以在自定义规则中加入更明确的域名规则，并确保这些规则位于宽泛规则之前。例如：

将 Gemini 相关域名交给代理策略组
rules:
  - DOMAIN-SUFFIX,gemini.google.com,PROXY
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,PROXY
  - DOMAIN-SUFFIX,googleapis.com,PROXY
  - DOMAIN-SUFFIX,google.com,PROXY
  - MATCH,规则总开关

上面的 PROXY 和「规则总开关」只是示例名称，必须替换成配置中真实存在的策略组名称。规则是从上到下匹配的，如果前面已经有一个覆盖范围很大的 GEOIP,CN,DIRECT、DOMAIN-SUFFIX,google.com,DIRECT 或拒绝规则，后面的代理规则可能永远不会执行。

规则调整后的验证方法

修改配置后，不要只点击保存。根据客户端实现，可能需要重新加载配置、更新规则集，或者重启 Clash 核心。然后清理旧连接，再运行一次 Gemini CLI。观察新连接的命中规则是否已经变成代理策略组。只有连接记录发生变化，才能证明规则修改真正生效。

排查 DNS 与 TUN 接管

DNS 异常是 Gemini CLI 超时中非常常见、也容易被忽略的一类问题。浏览器可能启用了自己的安全 DNS，而命令行则使用系统 DNS，因此二者表现不一致。若系统 DNS 无法正确解析目标域名，CLI 甚至还没有机会连接到代理节点。

使用 fake-ip 模式时，Clash 可以根据域名规则处理请求，通常更适合需要精确分流的环境。但如果 fake-ip 过滤列表、DNS 劫持或本地网络配置不完整，也可能造成某些命令行程序无法建立连接。排查时可以依次尝试以下方法：

  1. 确认 Clash DNS 功能已启用，并查看 Dashboard 是否有 DNS 错误日志。
  2. 临时切换到全局代理，观察是否仍然超时。
  3. 清理系统 DNS 缓存，再重新启动终端和 Clash。
  4. 检查目标域名是否被本地 DNS 解析成异常地址。
  5. 如果使用 fake-ip，确认没有把 Gemini 或 Google API 域名错误加入 fake-ip-filter。

如果 Gemini CLI 运行在 Docker、WSL、虚拟机、远程终端或独立开发环境中，系统代理通常不会自动传递进去。此时仅打开 Clash 的桌面系统代理并不够，需要让对应环境能够访问宿主机的代理端口，或者启用 TUN 模式接管更底层的流量。

TUN 模式能够接管不读取系统代理变量的应用，但它也不是万能开关。启用后应确认虚拟网卡已经创建、自动路由已打开，并且 Clash 具有管理员或系统权限。若开启 TUN 后网络整体变慢或所有请求异常，可以先关闭 TUN，使用明确的环境变量测试，避免同时引入多个变量。

建议的判断顺序：浏览器验证节点 → 全局模式验证 Clash → 环境变量验证 CLI → 规则模式验证分流 → 最后再处理 DNS 和 TUN。每次只改变一个条件，结果才具有参考价值。

用日志区分节点问题与配置问题

当基础检查完成后，可以把 Clash 日志级别临时调整为 info 或 debug，重新执行一次命令。不同错误信息通常对应不同方向：

  • connection refused：本地代理端口没有监听、端口填写错误，或代理程序没有运行。
  • i/o timeout：节点无法到达目标地址、链路丢包严重，或目标端口被阻断。
  • DNS lookup failed：DNS 上游不可用、域名解析被拦截，或 TUN/DNS 劫持配置异常。
  • TLS handshake timeout：节点线路质量差、SNI 或证书配置不匹配，也可能是服务端主动丢弃连接。
  • 401、403 或登录相关错误：网络可能已经连通，应转向检查账户、API 权限、登录状态和 CLI 版本。
  • 429：通常是请求频率或配额问题，不属于 Clash 节点超时，应检查账户使用量。

可以使用简单的 HTTP 测试确认本地代理端口是否工作。以下命令仅用于验证代理链路，具体目标地址应根据当前服务可访问性选择：

通过 HTTP 代理测试连接
curl -I -x http://127.0.0.1:7890 https://gemini.google.com

如果该命令也超时，优先检查节点、代理端口、规则和 DNS；如果 curl 可以返回 HTTP 响应，而 Gemini CLI 仍然失败，则重点检查 CLI 使用的代理变量、Node.js 运行环境、认证状态和版本兼容性。不要因为返回 403 或 401 就误判为网络失败，这至少说明请求已经抵达服务端。

什么时候应该更换节点或联系机场

经过全局模式、固定节点和命令行代理变量测试后，仍然无法连接，才有必要判断节点或机场服务问题。建议至少测试两个不同地区、不同线路的节点。如果只有某一个节点失败，而其他节点均正常，通常是该节点出口 IP 被限制、线路故障、服务器负载过高或服务端策略变化。

如果所有节点都失败，但浏览器和其他境外服务也无法访问，可能是机场订阅失效、节点整体过期、服务器端端口故障，或者当前网络对相关协议进行了限制。此时继续修改本地 YAML 的收益很低，应保存必要信息后联系服务商。

联系机场客服时，尽量提供可复现且不包含隐私的资料：

  • 失败时间和所在网络类型，例如家庭宽带、校园网或企业网络。
  • 使用的节点名称、地区和协议类型。
  • Clash 或 Mihomo 版本，以及操作系统信息。
  • 错误类型和关键日志，例如连接超时、TLS 超时或 DNS 失败。
  • 是否尝试过全局模式，以及其他节点是否正常。
不要发送完整订阅链接、UUID、密码或 API Key。排障截图应遮挡节点密码、订阅令牌、账户令牌和本地文件路径。服务商通常只需要节点名称、错误时间和脱敏后的日志。

常见问题

Gemini CLI 必须开启 TUN 吗？

不一定。如果 CLI 能正确读取 HTTP_PROXY、HTTPS_PROXY 或其他受支持的代理变量，就可以通过本地 HTTP 或 SOCKS5 端口访问 Clash，不需要开启 TUN。TUN 更适合无法配置代理的程序、容器或需要统一接管系统流量的场景。建议先用环境变量完成最小化测试，再决定是否启用 TUN。

浏览器能打开 Gemini，但命令行仍然超时怎么办？

首先检查当前终端的代理变量是否为空、是否指向旧端口，随后确认 Gemini CLI 所在环境是否与浏览器使用同一网络。如果命令行运行在 WSL、Docker 或远程服务器中，还要确认该环境能访问宿主机的 Clash 端口。最后在 Clash Dashboard 中观察执行命令时是否有连接记录。

全局模式可以，规则模式不行，说明什么？

这通常说明节点本身可用，但规则没有覆盖 Gemini CLI 实际访问的域名，或者规则顺序被其他规则提前截断。查看连接记录中的真实域名和命中规则，补充必要的 DOMAIN-SUFFIX 规则，并将其放在宽泛规则之前，然后重新加载配置。

换了多个节点仍然超时，是否就是机场故障？

不一定，还可能是命令行没有经过 Clash、DNS 配置异常、账户认证失败或 CLI 版本问题。应先用全局模式和明确的代理环境变量进行对照测试。如果多个节点、多个终端环境和其他境外服务都同时失败，才更像是订阅或机场侧故障。

排查 Gemini CLI 的关键，不是反复重装 Clash，而是把请求链路拆开验证：先确认节点，再确认代理端口，接着确认 CLI 是否使用代理，之后检查规则、DNS 和 TUN。每一步都记录结果，通常可以在几分钟内确定问题属于本机配置还是服务端线路。完成修复后，建议固定一个稳定节点并保留一组备用节点，避免策略组频繁切换影响登录状态和 API 请求。