Gemini CLI 连接超时怎么办？
Clash 配置排查与修复指南

先判断：到底是哪一种超时？

Gemini CLI 出现连接超时时，很多用户第一反应是更换节点，或者反复重新安装命令行工具。但这类问题不一定出在节点本身。Gemini CLI 是运行在终端中的程序，它与浏览器使用的是两套可能完全不同的代理路径：浏览器通常会自动读取系统代理，而 Node.js、Python、Go 或其他运行时启动的命令行程序，可能完全忽略桌面客户端中的系统代理设置。

因此，第一步不是修改配置，而是观察错误表现。若命令执行后长时间没有任何输出，最后出现 ETIMEDOUT、timeout 或连接建立失败，通常表示 TCP 连接没有在规定时间内完成。若提示 ENOTFOUND、getaddrinfo 或类似 DNS 错误，则重点应放在域名解析。若能成功连接但返回 401、403 或 API 配额错误，说明网络链路大概率已经打通，应转向检查 API Key、账号权限和服务区域，而不是继续调整 Clash。

还要区分“Gemini CLI 可以启动”和“Gemini CLI 可以访问 API”这两个概念。程序本地启动只说明 Node.js、配置文件和命令入口正常，并不能证明它能够访问 Google 的 API 服务器。即便浏览器可以打开搜索页面，也不能直接推断终端请求已经经过代理，因为浏览器与终端的代理变量、DNS 解析器和证书环境都可能不同。

第一步：确认 Clash 本身可用

在调整 Gemini CLI 之前，先确认 Clash 客户端正在运行，并且当前配置文件已经成功激活。打开 Clash Verge Rev 或其他 Mihomo 图形客户端，检查主页上的运行状态、当前模式和代理端口。常见的 HTTP 代理端口是 7890，SOCKS5 端口常见为 7891，但实际端口以客户端设置页显示的值为准，不要盲目照抄示例。

检查配置文件与代理节点

进入“配置”或“Profiles”页面，确认当前配置文件处于激活状态，并且配置中的代理组能够选择节点。如果订阅已经过期、配置文件为空、节点全部显示超时，终端自然无法建立连接。此时应先更新订阅并进行节点测速，选择一个延迟较低、状态正常的节点作为测试对象。

接着打开 Clash 的“代理”页面，临时不要使用复杂的自动选择组。可以直接选择一个确定可用的节点，减少代理组故障转移、测速策略或健康检查对排查结果的影响。测试成功后，再恢复原来的自动选择策略。对于 Gemini API 这类持续连接的请求，节点的稳定性通常比瞬时延迟更重要，延迟稍高但不丢包的节点往往更适合命令行调用。

确认本地端口正在监听

如果客户端界面显示运行中，但本地端口实际没有监听，终端设置代理后仍会失败。Windows 可以在 PowerShell 中执行以下命令查看端口状态：

Test-NetConnection 127.0.0.1 -Port 7890

如果结果中的 TcpTestSucceeded 为 True，说明端口可以访问。macOS 或 Linux 可以使用：

curl -I -x http://127.0.0.1:7890 https://www.google.com

这个命令的目的不是验证 Gemini API 本身，而是确认“终端通过 Clash HTTP 端口发送 HTTPS 请求”这条最基础的链路。如果这里就出现拒绝连接，优先检查 Clash 是否退出、端口是否写错，或是否有其他软件占用了相同端口。

第二步：让终端明确使用 Clash 代理

命令行工具最常见的问题是没有继承桌面系统代理。解决方法是为当前终端设置代理环境变量。对于绝大多数支持标准代理变量的程序，至少应设置 HTTP_PROXY 和 HTTPS_PROXY。变量名称通常不区分大小写，但为了兼容不同运行时，建议大小写版本同时设置。

Windows PowerShell 设置方法

在 PowerShell 中，可以先设置当前窗口临时生效的环境变量：

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:http_proxy="http://127.0.0.1:7890"
$env:https_proxy="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1"

这里使用的是 Clash 的 HTTP 代理端口。HTTPS 请求并不意味着必须填写一个以 https:// 开头的代理地址；在常见配置中，客户端通过 HTTP CONNECT 方法建立 HTTPS 隧道，因此 http://127.0.0.1:7890 是正常写法。设置完成后，可以在同一个窗口中使用 echo $env:HTTPS_PROXY 检查变量是否存在。

如果你使用的是 Windows 命令提示符 CMD，写法不同：

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
set http_proxy=http://127.0.0.1:7890
set https_proxy=http://127.0.0.1:7890
set NO_PROXY=localhost,127.0.0.1

上述方式只对当前窗口有效，关闭窗口后会失效。如果确认配置正确，希望以后每次打开终端都自动使用，可以通过 Windows 的“系统属性 → 高级 → 环境变量”添加用户变量。但不建议一开始就永久设置，因为某些内网、公司网络或本地开发服务不需要代理，永久代理可能造成额外干扰。

macOS 与 Linux 设置方法

macOS、Linux 以及大多数类 Unix Shell 使用 export 命令：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

如果 Clash 使用的是 SOCKS5 端口，也可以设置 ALL_PROXY：

export ALL_PROXY=socks5://127.0.0.1:7891
export all_proxy=socks5://127.0.0.1:7891

需要注意，SOCKS5 代理对 DNS 的处理方式取决于客户端和运行时是否支持远程解析。若使用 socks5:// 后仍然出现域名解析错误，可以尝试 socks5h://127.0.0.1:7891，其中末尾的 h 表示尽量让代理端解析域名。不过不同程序对该格式的支持并不完全一致，最稳妥的基础测试仍然是使用 Clash HTTP 端口。

如果希望每次启动 Shell 自动加载变量，可以将配置追加到 ~/.zshrc、~/.bashrc 或对应 Shell 的启动文件中：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

保存后执行 source ~/.zshrc 或重新打开终端。对于开发工作较多的用户，更推荐编写一个可随时开启和关闭的脚本，而不是无条件永久代理。这样可以根据网络环境切换，避免访问内网 Git、公司服务或本地容器时出现不必要的绕行。

第三步：分层测试代理链路

设置环境变量后，不要直接反复运行 Gemini CLI。正确方法是从简单到复杂进行分层测试：先测试本地端口，再测试普通 HTTPS 请求，最后测试 Google API 相关域名。每一层都成功，才能说明下一层值得继续排查。

可以使用以下命令查看详细连接过程：

curl -v -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com

-v 会输出连接细节。正常情况下，你应当看到 curl 先连接 127.0.0.1:7890，随后通过代理建立到目标站点的 CONNECT 隧道。如果输出显示它直接连接目标域名，说明命令没有使用指定代理；如果显示连接本地端口被拒绝，则是 Clash 监听问题；如果本地端口连接成功但隧道建立后长时间没有响应，则可能是节点、规则或远端网络问题。

测试接口返回 401 或 404 并不一定代表网络失败。对于没有携带 API Key 的请求，服务器返回权限错误是很常见的，反而说明请求已经到达远端。排查时应重点看“是否建立连接”和“是否收到服务器响应”，不要把所有非 200 状态码都理解为代理故障。

第四步：检查 Clash 规则是否命中

Clash 的规则分流决定一条请求最终是直连、代理还是拒绝。即使终端已经设置了代理变量，Clash 仍可能根据规则将 Google API 域名判定为 DIRECT，于是请求绕过代理并发生超时。打开 Clash 的连接日志，重新运行一次 Gemini CLI，搜索 googleapis.com、generativelanguage.googleapis.com 或相关请求记录，查看它使用了哪个策略。

如果日志显示目标请求走了 DIRECT，需要检查规则顺序。Clash 规则是从上到下匹配的，前面命中的规则会停止继续判断。因此，一条范围过大的直连规则可能在 Google 域名规则之前生效。可以在自定义规则的靠前位置加入针对 API 域名的代理规则：

rules:
  - DOMAIN-SUFFIX,googleapis.com,PROXY
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,PROXY
  - MATCH,DIRECT

其中 PROXY 必须替换为你配置文件中实际存在的代理组名称，例如 节点选择、Proxy 或 🚀 节点选择。不能直接假设所有配置都使用同一个策略名。如果配置由订阅服务商生成，建议通过客户端提供的覆写功能添加规则，不要直接修改每次更新都会被覆盖的原始订阅文件。

有些配置会使用规则集（rule-providers）而不是大量手写域名。此时要确认 Google 或代理规则集已经成功下载并处于更新时间范围内。如果规则集请求本身失败，Clash 可能暂时使用旧文件，甚至因为配置错误而加载失败。检查配置页面中的规则集状态，必要时手动更新规则集，再重新测试。

第五步：排查 DNS 解析异常

DNS 是 Gemini CLI 超时排查中容易被忽略的一环。程序首先需要把域名解析为 IP 地址，之后才能建立 TCP 或 TLS 连接。如果终端使用的是运营商 DNS，而该 DNS 无法正确解析 Google API 域名，表现可能是解析失败、解析到不可达地址，或者解析过程长时间没有返回。

先在终端执行基础解析命令：

nslookup generativelanguage.googleapis.com

macOS 和 Linux 也可以使用：

dig generativelanguage.googleapis.com

如果结果为空、耗时异常，或者不同网络下返回结果差异极大，就需要检查 DNS。Mihomo 支持在配置文件中启用内置 DNS，并通过 fake-ip 或 redir-host 等模式处理域名。具体模式没有绝对的优劣：fake-ip 对规则匹配和透明代理较方便，redir-host 与部分特殊应用的兼容性可能更好。不要在不了解现有配置的情况下同时叠加多个 DNS 插件或系统代理软件，否则容易产生端口冲突和解析回环。

使用 TUN 模式时，可以开启 DNS 劫持，让系统 DNS 请求进入 Clash 内置 DNS。若仅使用系统代理，则 DNS 请求仍可能由系统或应用自行处理，HTTP 请求虽然经过 Clash，域名解析却可能发生在代理之外。对于 Gemini CLI 这类依赖多个 Google 域名的工具，DNS 路径不一致尤其容易造成偶发超时。

识别 DNS 泄漏与解析回环

DNS 泄漏并不一定意味着请求完全无法访问，但它会让域名查询绕过预期的代理路径，暴露查询记录或返回不适合当前网络环境的地址。更严重的情况是 DNS 请求被 Clash 接管后又被配置转发回本机监听端口，形成解析回环，导致所有域名查询都卡住。

检查 DNS 配置时，应确认上游服务器可达、监听端口没有与系统服务冲突，并查看 Clash 日志中是否持续出现 DNS timeout、fallback failed 或 loop 等错误。修改 DNS 后，重新启动终端并清理系统 DNS 缓存，再进行测试。Windows 可以执行 ipconfig /flushdns；macOS 和 Linux 的清理方式取决于系统使用的 resolver 服务，不建议直接套用不适用于当前发行版的命令。

第六步：显式代理无效时启用 TUN 模式

环境变量并不能让所有程序都走代理。有些运行时、第三方 SDK 或底层网络库会忽略 HTTP_PROXY、HTTPS_PROXY 和 ALL_PROXY，直接创建网络连接。此时即使 curl 能通过代理成功，Gemini CLI 仍然可能超时。TUN 模式可以在更底层接管系统流量，作为显式代理之外的补充方案。

在 Clash Verge Rev 中，通常可以在“设置”或“内核”页面找到 TUN 开关。首次启用时，系统可能请求管理员权限，因为客户端需要创建虚拟网卡、修改路由或安装网络组件。授权后，建议先使用“规则”模式，而不是一开始就使用全局代理。这样国内网站和本地地址仍可按照规则直连，只有需要代理的域名进入节点。

启用 TUN 后，重新打开一个终端窗口，再运行测试命令。为了避免双重代理，可以先清除显式环境变量：

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy ALL_PROXY all_proxy

Windows PowerShell 中可以使用：

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:ALL_PROXY -ErrorAction SilentlyContinue

然后再次运行 Gemini CLI。如果清除变量后仍然能够访问，说明 TUN 已经接管了该程序。如果启用 TUN 后反而出现所有网络异常，应立即关闭 TUN 或恢复原配置，检查虚拟网卡、路由表、DNS 劫持和其他 VPN 软件是否冲突。WireGuard、其他 VPN 客户端、虚拟机网络和公司安全软件都可能安装自己的虚拟网卡，多个网络接管工具同时运行时尤其容易出现路由优先级问题。

第七步：网络恢复后检查 API Key 与运行环境

当连接问题解决后，Gemini CLI 可能会从“超时”变成“未授权”或“请求被拒绝”。这是一个积极信号，说明网络请求已经抵达服务器，接下来应检查应用配置。确认 API Key 没有包含多余的空格、引号或换行，也不要把示例占位符误当成真实密钥。若使用环境变量保存密钥，可以先检查变量是否存在，但不要把完整密钥复制到公共日志或截图中。

不同版本的 Gemini CLI、不同 SDK 和不同认证方式使用的变量名称可能不一致。请以当前工具文档为准，确认你使用的是 API Key、OAuth 登录还是 Vertex AI 等企业认证方式。认证方式混用时，旧变量可能优先级更高，导致程序一直使用错误账户。排查时可以暂时在干净的终端会话中只保留一种认证配置，避免多个变量相互覆盖。

还要检查系统时间。TLS 证书验证依赖本机时间，如果系统时间偏差较大，错误可能表现为证书无效、连接被重置或请求重试。虽然这类问题通常不是典型的 timeout，但在代理节点进行 TLS 中转时更容易暴露。同步系统时间后重新测试，可以排除这类隐藏因素。

常见错误与对应处理方法

浏览器能用，所以终端一定能用

这是最常见的误判。浏览器可能使用系统代理，而终端程序没有读取系统代理；浏览器还可能启用了自己的 DNS、扩展或安全策略。因此必须在终端中用 curl 或实际运行时进行测试，不能只根据浏览器结果下结论。

把 SOCKS 端口写成 HTTP 端口，或反过来

HTTP 代理和 SOCKS5 代理虽然都能转发流量，但地址格式和程序支持情况不同。若变量写成 http://127.0.0.1:7891，而 7891 实际是 SOCKS5 端口，程序可能出现协议错误或连接卡住。应从 Clash 设置页面确认端口类型，再选择正确的变量格式。

只添加 google.com，没有覆盖 googleapis.com

Gemini API 访问的关键域名并不只有网页域名。程序可能连接 generativelanguage.googleapis.com、googleapis.com 以及认证、遥测或模型服务相关域名。规则过于狭窄时，网页可以访问，API 仍然超时。建议查看 Clash 连接日志，根据实际请求域名添加精确规则，而不是无限扩大关键词匹配范围。

修改配置后没有重启终端

环境变量只在进程启动时读取的程序非常常见。你在一个窗口中修改变量，并不会自动改变已经运行的 CLI 进程，也不一定影响另一个已经打开的终端标签页。保存配置后关闭旧窗口，重新打开终端，再验证变量和请求路径。

总结：建立一套可复用的排查顺序

Gemini CLI 连接超时通常不是单一开关造成的，而是“应用没有使用代理、规则没有命中、DNS 无法解析或网络层未被接管”中的一个环节出现问题。最有效的排查方式是逐层确认，而不是同时修改多个设置。推荐保留以下顺序：

1. 确认 Clash 客户端正在运行，配置文件已激活，并且存在可用节点。
2. 确认 HTTP 或 SOCKS 代理端口真实监听，避免把控制端口当成代理端口。
3. 在当前终端设置代理环境变量，用 curl 验证显式代理是否生效。
4. 查看 Clash 连接日志，确认 Google API 域名没有被错误地判定为直连。
5. 检查 DNS 解析、DNS 劫持和规则集状态，排除域名解析异常。
6. 如果程序忽略代理变量，再启用 TUN 模式进行系统级接管。
7. 网络恢复后，最后检查 API Key、认证方式、运行时版本和系统时间。

与只提供简单系统代理开关的工具相比，Clash 的优势在于可以同时观察连接日志、切换节点、调整规则，并根据不同域名选择直连或代理。对于 Gemini CLI 这类命令行应用，能够明确控制 HTTP 代理、DNS 和 TUN 流量路径，比单纯反复更换节点更容易定位根因。如果你还没有安装 Clash 客户端，可以前往下载页面获取适合操作系统的版本，并按照本文的顺序完成基础配置。