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

Gemini CLI 为什么会连接超时

Gemini CLI 的连接超时，通常不是单一的「节点速度慢」，而是命令行程序在登录、读取配置、请求模型和接收流式响应时，分别访问了不同的主机名。浏览器可以打开 Google 的网页，并不代表终端里的 Node.js 进程或独立 CLI 一定继承了系统代理。常见现象包括：执行登录命令后浏览器授权成功，但终端一直等待；模型列表可以显示，真正发送提示词时却出现 ETIMEDOUT；短问题能够返回，长回答或工具调用则在中途断开。

从 Clash 的角度看，最容易被忽略的是命令行代理没有接入、Google 相关域名被拆到不同出站、DNS 解析结果与代理路径不一致，以及节点本身无法稳定承载长连接。Gemini CLI 可能访问 generativelanguage.googleapis.com、accounts.google.com、googleapis.com、gstatic.com 或其他随版本变化的认证与静态资源域名。不要只看到浏览器里的 Gemini 页面正常，就直接断定 CLI 的 API 链路也没有问题。

先确认 Gemini CLI 是否真的经过 Clash

第一步不要急着修改复杂规则，而是确认当前 Shell 能否访问 Clash 的入站端口。常见配置会提供 mixed-port，它能够同时接受 HTTP 和 SOCKS 请求；也有配置把 HTTP 代理与 SOCKS 代理拆成两个端口。具体端口必须以 Clash 面板或配置文件中的 mixed-port、port、socks-port 为准，不能机械照抄其他教程里的数字。

在 macOS 或 Linux 中，可以先为当前终端设置代理环境变量，再启动 Gemini CLI。示例中的端口假定为本机的 mixed-port，若你的配置使用其他端口，请替换为实际值：

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

HTTP_PROXY 和 HTTPS_PROXY 的值通常写成 HTTP 代理地址，即使目标请求本身是 HTTPS；ALL_PROXY 则常用于支持 SOCKS 的运行时。不同版本的 Gemini CLI、Node.js 依赖和底层 HTTP 客户端对环境变量的读取方式并不完全相同，因此设置变量后，还要用一个简单请求验证。可以查看 CLI 自身的帮助信息，或者用系统已有的 curl 对相关 API 主机进行连接测试，观察请求是否能建立 TLS，而不是只看网页是否打开。

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"

如果浏览器通过 Clash 正常访问，而 CLI 仍然超时，最常见的原因是你只开启了系统代理，却没有让命令行读取系统代理设置。很多终端程序不会自动读取 macOS、Windows 的图形代理选项。此时环境变量是最短的验证路径；若变量有效，后续可以再考虑用 TUN 让更多不支持代理变量的进程透明接入。

Gemini CLI 的 Clash 规则应该怎么写

规则排查的核心不是堆一份永远不会更新的域名清单，而是先从 Clash 的连接日志中确认真实请求。启动 Gemini CLI 后，过滤包含 google、googleapis、gstatic 或认证关键词的连接，记录每个 Host 命中的规则、使用的策略组和最终节点。日志里的主机名比搜索引擎文章中的固定列表更可靠，因为 CLI 版本、登录方式和 Google 服务端都会改变请求路径。

对于已确认属于 Gemini API 的域名，可以使用较明确的 DOMAIN-SUFFIX 规则，将相关请求交给单独策略组。例如：

rules:
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,GEMINI_AI
  - DOMAIN-SUFFIX,googleapis.com,GEMINI_AI
  - DOMAIN-SUFFIX,accounts.google.com,GEMINI_AUTH
  - DOMAIN-SUFFIX,gstatic.com,GEMINI_AUTH

这段 YAML 只是说明分组思路，策略组名称必须与配置中的真实名称一致，且规则顺序要放在更宽泛的 Google、国外站点或最终兜底规则之前。如果前面已经有一条覆盖整个 googleapis.com 的规则，后面的 Gemini 专用规则就不会生效。修改后应在 Clash 的配置校验界面检查 YAML 语法，再重载配置，最后通过连接日志确认实际命中结果。

不建议一开始就使用 DOMAIN-KEYWORD,google 这类宽泛规则。它可能把无关的 Google 服务、办公应用、国内可直连资源全部送进代理，增加排障噪声，也可能让登录域、API 域和静态资源分别命中不同策略。更稳妥的做法是先精确覆盖日志中出现的主机，再根据实际失败请求增量补充。若机场提供维护良好的 Google 或 AI 远程规则集，也可以使用 RULE-SET，但必须确认规则集已经被当前内核成功下载并启用。

注意：不要把「网页 Gemini 能打开」当成 API 规则正确的证据。网页可能走的是浏览器缓存、不同 CDN 或另一套登录会话；CLI 的真实请求必须以 Clash 连接日志和终端错误信息交叉验证。

DNS、IPv6 与 TLS：超时不一定是节点问题

DNS 是 Gemini CLI 超时排查中经常被跳过的一层。若系统 DNS 将 API 域名解析到不可达地址，Clash 可能在连接尚未进入预期代理策略前就已经失败。特别是在开启 IPv6 的网络中，系统可能优先返回 IPv6 记录，但当前节点、路由器或本地运营商并不能稳定访问 IPv6，结果就是浏览器偶尔成功、CLI 多次重试后超时。

在 Clash 的 DNS 设置中，应先确认当前内核使用的是可用的远程 DNS、是否开启了合理的增强模式，以及 fake-ip 或 redir-host 是否与客户端环境兼容。不要在多个软件中同时启用互相冲突的 DNS 劫持：例如系统代理、浏览器安全 DNS、VPN 客户端和 Clash TUN 同时接管解析，可能造成日志显示的域名与实际连接目标不一致。

排查时可以分成两组测试。第一组关闭 IPv6 或暂时让 Clash 不优先使用 IPv6，观察 Gemini CLI 是否恢复；第二组切换 DNS 增强模式并清理本地 DNS 缓存，重新执行登录或 API 请求。如果只有某一个网络环境失败，例如家庭宽带失败而手机热点正常，就要重点比较两边的 DNS 响应、IPv6 路由和 MTU，而不是立即认定订阅节点失效。

TLS 握手同样值得关注。若日志显示连接建立后长时间停在握手阶段，可能涉及节点出口、SNI、证书验证、系统时间或中间网络设备。请先确认电脑日期和时区正确，避免证书被判断为尚未生效或已经过期；同时检查是否有企业 VPN、杀毒软件或 HTTPS 解密功能拦截 Node.js 的连接。不要为了测试而长期关闭证书校验，这会隐藏真正的问题并降低账号安全性。

什么时候需要 TUN，什么时候应该换节点

如果设置 HTTP_PROXY、HTTPS_PROXY 后 Gemini CLI 仍然完全没有出现在 Clash 连接日志中，说明该进程可能不读取代理变量，或者它通过子进程、原生网络库建立连接。此时可以考虑启用 TUN 模式，让系统层面的流量经过虚拟网卡和 Clash 路由。TUN 对命令行工具、Git、包管理器、容器外部进程通常更省心，但它涉及系统权限、路由表、DNS 劫持以及与其他 VPN 的冲突，不能把它当作所有超时的万能开关。

开启 TUN 前，先关闭其他 VPN 或网络加速器，确认 Clash 内核具有创建虚拟网卡所需的权限，并保留原配置备份。启用后检查三件事：第一，Clash 日志是否出现 Gemini CLI 的连接；第二，本地局域网、打印机和公司内网是否仍能访问；第三，DNS 请求是否没有形成循环。若 TUN 开启后网页和 CLI 都变慢，可能是路由范围过宽、DNS 模式冲突或 MTU 不合适，应先回退，而不是继续叠加规则。

节点选择要看稳定性和长连接表现，不只是测速页面上的毫秒数。Gemini CLI 的流式回答可能持续几十秒甚至更久，低延迟但高丢包的节点，往往比延迟稍高却稳定的节点更容易触发断流。建议在同一策略组内测试两到三个节点，比较登录、短请求、较长输出和连续多轮对话四种场景。若所有节点都无法连接，优先检查规则、DNS 和账号；若只有一个节点失败，则更换节点或联系服务商更有意义。

• 连接日志完全没有请求：优先检查代理变量、TUN 状态和 CLI 是否启动了独立子进程。
• 请求命中 DIRECT：检查规则顺序、域名后缀和策略组名称。
• 请求命中代理但 TLS 超时：比较节点出口、IPv6、DNS 和系统时间。
• 短请求成功、长回答中断：重点检查节点丢包、流式连接和策略组稳定性。
• 只有登录失败：单独检查认证域名、浏览器回调和本地端口占用。

登录成功但 API 仍超时，应该怎样继续定位

Gemini CLI 的登录状态和模型调用不是同一个网络阶段。浏览器完成授权后，CLI 仍可能需要访问令牌交换端点、读取账户信息和请求模型服务。若登录成功但第一次提示词超时，不要重复删除凭据；先在 Clash 日志中确认 API 主机是否沿用了与认证阶段相同的策略意图。认证域名能够访问，只能证明账户授权链路基本完成，不能证明模型 API 的出站节点适合当前请求。

还要检查 CLI 的实际配置来源。某些工具会从环境变量读取 API 地址、项目 ID 或区域设置，也可能从用户目录下的配置文件读取。若你曾经配置过第三方兼容端点、公司代理或旧版本变量，程序可能并没有请求 Google 官方 API，而是请求一个已经失效的自定义 base URL。可以先打印非敏感的配置摘要，确认端点、模型名称和认证方式；API Key、OAuth 刷新令牌等秘密信息不要直接粘贴到日志、论坛或截图中。

终端里的错误信息也有区分价值。ENOTFOUND 更接近 DNS 或域名解析问题；ECONNREFUSED 常见于本地代理端口未监听或端口写错；ETIMEDOUT 可能发生在 TCP、TLS 或上游响应等待阶段；HTTP 401、403 则更偏向认证、权限、项目设置或配额问题，不应继续用换节点来处理。把错误代码、发生时间和 Clash 日志中的对应连接放在一起，排查效率会明显提高。

如果使用的是公司网络、校园网或云服务器，还要考虑出口策略和连接限制。某些网络会允许普通网页访问，却限制长时间 HTTPS、WebSocket 或流式响应；某些服务器则对外连频率和目标端口有额外防火墙规则。可以用手机热点或另一条固定网络做一次对照测试，但不要在公共环境中暴露账号令牌。对照结果只能帮助缩小范围，不能替代对 Clash 连接日志的确认。

Gemini CLI 超时常见问题

浏览器能打开 Gemini，为什么 CLI 还是超时？

浏览器可能自动读取系统代理、使用独立的安全 DNS 和已有登录缓存，而 CLI 通常依赖环境变量、自己的 HTTP 客户端和不同的 API 域名。请先确认终端是否设置了正确的代理变量，再从 Clash 日志确认 API 请求是否出现，并检查 API 域名是否命中预期策略组。

必须开启 TUN 才能使用 Gemini CLI 吗？

不一定。如果 CLI 能正确读取 HTTP 或 SOCKS 代理变量，使用 mixed-port 或 SOCKS 端口即可。只有当程序不读取变量、子进程绕过代理，或你希望统一接管多个命令行工具时，TUN 才更有价值。启用前要注意与 VPN、DNS 劫持和局域网路由的冲突。

什么时候应该直接更换节点？

当规则已经命中代理、DNS 正常、多个请求都在同一节点上出现握手失败或流式断开，而更换其他节点后立即恢复时，才可以判断节点质量是主要因素。若所有节点都失败，继续换节点通常只会浪费时间，应回到代理变量、规则、DNS、端点和账号权限这些基础层面。

与只依赖浏览器扩展的代理方案相比，扩展往往无法覆盖 Gemini CLI 的 Node.js 进程、认证回调和长连接请求；单纯使用系统代理又可能被不读取系统设置的终端工具绕过。Clash V.CORE 则可以通过连接日志、规则分流、mixed-port 与可选的 TUN 模式，把登录域、API 域和流式连接放进同一套可观察的网络路径中，减少「网页正常但 CLI 超时」的盲目试错。完成本文的代理变量、规则和节点验证后，如果你希望获得更完整的命令行兼容性与分流控制，可以前往下载 Clash V.CORE，继续使用适合 Gemini CLI 的稳定代理环境。