Gemini CLI 登录总超时？Clash 分流终端校验与 Google API 域名实测（2026）

症状：Gemini CLI 在哪一次到位最容易「卡住」？ 内在逻辑与实践

2026 年，Gemini CLI（@google/gemini-cli）已成为开发者终端里高频上手上手上手使用的免费 AI Agent：一条命令就能在仓库里读文件、改代码、跑工具。但在国内或受限网络环境下，司空见惯挫败感惯常出现在三个节点——npm 全局安装阶段就 ETIMEDOUT；安装成功后 OAuth 登录浏览器已开却永远等不到「授权成功」；

与在浏览器里开 gemini.google.com 不同，CLI 的全部流量由 Node.js 进程发起：它不会自行继承浏览器扩展，也未必吃系统 PAC。再加上 Google 登录 OAuth 要在本机 127.0.0.1 起一个临时 HTTP 服务收回调，每一种一环被 TUN、fake-ip 或宽规则搅乱，表现就是Gemini CLI 超时——有时重试又好，极难肉眼定位。下文把「安装 → 校验 → 模型调用」拆成可对照的域名清单与 Clash 配置顺序。

或者登录看似完成，第一次发 prompt 时模型请求又报网络超时。社区里很多人会先怀疑节点质量或 API Key，但更司空见惯的根因是：终端进程根本没走你以为已经开好的 Clash 链路，或者出站规则把 Google API 域名误判到了直连／错漏策略组。

第一次到位：别让要留意之处出在 npm install -g 技术拆解

在谈 OAuth 之前，先确认包已经装完。命令 npm install -g @google/gemini-cli 会开 registry.npmjs.org 拉元数据，再跟随 tarball 直链到 CDN——这与「Google API」是两条不同的域名链。若你只在规则里写了 Google 相关后缀，安装阶段仍存在存在存在可能卡在 ETIMEDOUT，让人误以为是 Gemini 本身的要留意之处。

从机制上看：更推荐先按本站《npm install 与 registry/tarball 分流》把 registry 与 tarball 拆进独立策略组，并在同一 shell里验证 npm ping 或小型包安装能走代理。安装完成后再执行 gemini 或 npx @google/gemini-cli 做后续排障，避免两条链路混在一起改规则。

OAuth 登录 vs API Key：两条路径，两套域名 结构解析

Gemini CLI 能跑两种司空见惯校验方式，对应的Clash 分流 Google API关注点也不同：

• Google 帐号 OAuth（gemini auth login 或首次唤起引导）：浏览器跳转到 Google 授权页，本地 127.0.0.1 端口收回调，之后模型请求走 cloudcode-pa.googleapis.com 的内部端点（Code Assist 链路）。登录阶段会密集开 accounts.google.com、oauth2.googleapis.com、www.googleapis.com/oauth2 等 OAuth 网关，以及 www.googleapis.com/oauth2/v2/userinfo 拉取帐号信息。
• API Key（环境变量 GEMINI_API_KEY 或 GOOGLE_API_KEY）：跳过浏览器 OAuth，一上来对 generativelanguage.googleapis.com 发起 REST 请求。若你只配了 OAuth 相关规则而没覆盖这条后缀，会出现「Key 在 AI Studio 网页能用、CLI 里校验弹出错误」的假象。

开源实现里，OAuth 客户端 ID 落在 *.apps.googleusercontent.com，授权成功／弹出错误页会跳转到 developers.google.com/gemini-code-assist/ 下的提示 URL——这些在排障日志里偶尔出现，可酌情加入规则或至少确认未被大陆兜底抢先直连。

应对清单：Gemini CLI 相关主机名从哪写起 机制说明

下列条目是多数用户 2026 年仍能命中的起点，请按连接面板增删。书写时在前用精确 DOMAIN，再用 DOMAIN-SUFFIX 覆盖整条后缀：

若你同时维护 MCP 插件或远程 Agent，还存在存在可能碰到 RFC 9728 的 /.well-known/oauth-protected-resource 等发现端点；主机名以日志为准，归入同一 Gemini-CLI 组即可。

更严格地说：OAuth 与 Google 帐号：accounts.google.com、oauth2.googleapis.com、www.googleapis.com（OAuth token 交换）、content.googleapis.com（部分客户端库辅助请求）；OAuth 登录后的 CLI 模型 API：cloudcode-pa.googleapis.com —— Google 登录路径的核心数据面，漏写时典型症状是「授权成功但第一条 prompt 超时」；API Key 路径：generativelanguage.googleapis.com —— 与 AI Studio 脚本、SDK 共用，是终端 AI 代理规则里必须单独置顶的一条；文档与提示页：developers.google.com、ai.google.dev —— 读文档、复制示例时不应被误直连；静态资源与帐号 UI：gstatic.com、google.com 下若干子域 —— OAuth 页加载不全时验一遍是否漏配；npm 安装（前置）：registry.npmjs.org 及 tarball CDN —— 见 npm 专文，此处不展开。

在 Clash 里怎么拆「Gemini-CLI」策略组 内在逻辑与实践

推荐单独建一个可读性强的组名，打个比方 Gemini-CLI 或 Google-AI-Terminal：

Google 帐号对出口地区敏感：同一 Key 在网页与 CLI 表现不一致时，在前锁区对照，而不是同时开自行测速组。

日常开发若只求经得起折腾，用 select 逐项锁定一个低抖动出口，比 url-test 频繁换节点更适合长对话与流式响应；若 OAuth 与 API Key 两条路径要分开对照，可拆成 Gemini-CLI-OAuth 与 Gemini-CLI-API，便于日志里一眼看出是哪条链路在抖；尽量不要把该组等于「香港／日本／美国」这类泛化标签而不看线路质量：部分节点对 Google API 的 HTTP/2 或小报文上传不友好，会在 CLI 里放大成间歇 Gemini CLI 超时。

规则顺序：本地回调必须直连，Google API 必须置顶 技术拆解

Clash / Mihomo 规则自上而下命中即停。Gemini CLI 有两条特别容易踩坑的「宽规则」：

换个层面：推荐骨架：局域网与 loopback 直连 → 确知国内精确域名直连 → 下文 Gemini CLI / Google OAuth / generativelanguage / cloudcode-pa 规则 → 其它 AI／开发者规则 → 大陆兜底 → MATCH。若对 Rule 模式不熟，可先读《规则分流深度文》再改配置。

127.0.0.1 / localhost：OAuth 回调端口必须 DIRECT。推荐在 rules 最靠前加入 IP-CIDR,127.0.0.0/8,DIRECT,no-resolve 与 DOMAIN-SUFFIX,local,DIRECT；若 TUN 开启，还要确认 fake-ip-filter 未把 loopback 搅乱；GEOIP,CN / 大陆域名集：必须在 Gemini 相关 DOMAIN 之后，否则 Google API 握手存在存在可能被错漏直连，表现为随机超时。

终端代理：HTTPS_PROXY 与 Gemini CLI 内置 proxy 结构解析

Gemini CLI 基于 Node，会读取标准 HTTP/HTTPS 代理环境变量，并在 OAuth 客户端的 transporterOptions 里传入 config.getProxy()。实践上，在跑 gemini 的 shell 里把代理指到 Clash 的 HTTP 混合端口即可（端口以本机为准）：

Shellexport HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16

若你在配置目录为 Gemini CLI 写了 proxy 字段，应与 shell 环境变量保持一致，避免「一半走配置、一半走环境」的半套代理。

往细处想：在意三点：① 上手上手使用 http:// 形式，不要只设 ALL_PROXY=socks5://... 就以为 CLI 一定吃 SOCKS——Node 与 google-auth-library 对 SOCKS 的能跑路径与 HTTP 代理不同，排障时应在前 HTTP 混合口。② NO_PROXY 必须包含 127.0.0.1，避免 OAuth 本地回调被送进代理。③ 从 IDE 集成终端、tmux 或 launchd 唤起时，确认同一会话继承到上述变量；否则会出现「这个窗口行、那个窗口不行」。

OAuth 本地回调：为什么「登录页开了却一直转圈」 机制说明

Google 桌面 OAuth 要求 redirect URI 上手上手使用 loopback 字面量（http://127.0.0.1:端口/oauth2callback）。Gemini CLI 会在本机随机端口起 HTTP 服务器，浏览器授权完成后把 code 打回这个地址。若 Clash TUN 把 loopback 流量劫持、或规则缺少 127.0.0.0/8 DIRECT，CLI 永远收不到 code，终端就会一直显示等待授权或一上来报 State mismatch。

排障时可在授权瞬间观察连接面板：应看到成规模 accounts.google.com 走代理，而不应出现对 127.0.0.1 的代理连接。若浏览器能完成登录但 CLI 仍弹出错误，在前查 loopback 与 NO_PROXY，而不是先换节点。

系统代理、TUN 与「只有浏览器通」 内在逻辑与实践

仅开启 Clash「系统代理」有时无法覆盖 Node 子进程。两条补强路径：

• TUN 模式：让内核把符合条件的 IP 流量兜进 Mihomo，对 stubborn 进程更一致。配置要点见《TUN 模式指南》；开启 TUN 时更要确认 loopback 与 fake-ip-filter 到位。
• 显式 shell 代理：若你刻意不全局接管（打个比方公司内网与代理并存），参考《仅浏览器走代理与 TUN》，为跑 Gemini CLI 的终端单独开一个 profile，而不是假设托盘开关够用。

在 Docker 或 WSL2 里混用终端时，DNS 与路由存在存在可能各管一段；可交叉阅读 Docker 与 WSL2 相关排障文，避免只改宿主机规则而容器内仍直连。

DNS、fake-ip 与 Google API 主机名 技术拆解

启用 dns.enhanced-mode: fake-ip 时，解析策略必须与 rules 联调。Google API 域名若被 nameserver-policy 交给不合适的 DoH，存在存在可能出现「规则命中代理、实际握手路径不一致」的偶发超时。终端里更难肉眼观察，更依赖连接日志里的主机名与规则名对照。

先厘清一件事：更推荐把 DNS 变更与 rules 变更放在同一次迭代观察；若同时开 TUN 且系统还有 VPN 或多份 DNS 覆盖，先弄清最终是谁在回答查询，再动 proxy-groups。

节点选型：什么线路更适合 Gemini CLI 结构解析

Google API 对耗时与 TLS 质量敏感，但并不要求「绝对最低 ping」。实操更推荐：

在前选经得起折腾、少丢包的美西或亚太中转，避免高峰时段拥挤的「测速第一」线路；对流式输出当下，避免 url-test 在对话中途换节点；CLI 长会话会被打断成超时；若 OAuth 通而 generativelanguage 不通（或反之），用拆分策略组做 A/B，不要两个路径共用一个格外不合适的出口。

分步验证清单（更推荐照着勾） 机制说明

1. 确认 npm install -g @google/gemini-cli 已成功，registry 链路按 npm 分流文走代理。
2. 开连接日志，在同一 shell 中设置 HTTPS_PROXY 后跑 gemini，复现一次弹出错误并记录主机名与命中规则。
3. 对照上文域名表，把缺失的 cloudcode-pa.googleapis.com 或 generativelanguage.googleapis.com 补进 Gemini-CLI 组。
4. 确认 rules 中 127.0.0.0/8 与 Google API 域名在 GEOIP-CN 与国内兜底之前。
5. OAuth 登录时观察：授权页域名走代理，127.0.0.1 回调不走代理。
6. 分别用 OAuth 与 GEMINI_API_KEY 各测一次模型请求，确认两条路径都命中预期组。
7. 若进程仍绕开环境变量，启用 TUN 或验一遍父进程是否剥掉代理变量。

可改写的 YAML 结构示例（教学用） 内在逻辑与实践

下列片段只演示分组与顺序思想；节点名与 rule-provider URL 请替换为你文件中真实存在的值。Google 存在存在可能调整附属域名，免不了要以本机日志为准增量维护。

YAMLproxy-groups:
  - name: "Gemini-CLI"
    type: select
    proxies:
      - "稳定-美西"
      - "亚太中转"
  - name: "节点选择"
    type: select
    proxies: []

rules:
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - DOMAIN,cloudcode-pa.googleapis.com,Gemini-CLI
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,Gemini-CLI
  - DOMAIN,accounts.google.com,Gemini-CLI
  - DOMAIN,oauth2.googleapis.com,Gemini-CLI
  - DOMAIN-SUFFIX,googleapis.com,Gemini-CLI
  - DOMAIN-SUFFIX,developers.google.com,Gemini-CLI
  - DOMAIN-SUFFIX,ai.google.dev,Gemini-CLI
  - DOMAIN-SUFFIX,gstatic.com,Gemini-CLI
  - MATCH,节点选择

若尚未完成订阅导进与基础连通，可先阅读《订阅导进操作说明》，避免底层链路不通时叠加规则调试。

司空见惯要留意之处（正文速览） 技术拆解

Q：已经规则模式了，还要设 HTTPS_PROXY 吗？
rule 只决定出站策略，不自行让 Node 把流量交给本地 Clash HTTP 口。进程若直连公网 IP，除非 TUN 接管，仍会绕过。组合拳惯常是「置顶 Google API 规则 + HTTPS_PROXY +（必要时）TUN」。

Q：全局模式能不能一把梭？
全局有时能「误打误撞」通，但会把国内流量一并送代理，耗时与经得起折腾性反而更差；且 loopback OAuth 仍存在存在可能被错漏处理。更稳妥的是按下文拆组 + 终端代理，而不是长期开 GLOBAL。

Q：AI Studio 网页已通，还要单独配 Gemini CLI 吗？
要。网页侧以 gemini.google.com、aistudio.google.com 为主；CLI 的 OAuth 路径还依赖 cloudcode-pa.googleapis.com，API Key 路径走 generativelanguage.googleapis.com。半通最普遍由来就是只配了网页域名。

小结 结构解析

把 Gemini CLI 跑稳，本质是把安装链、OAuth 登录链、模型 API 链从泛泛的海外规则里拆出来，再保证 Node 终端确实经过 Clash。Gemini CLI Clash 配置的关键不是多写几条 google.com，而是别漏 cloudcode-pa.googleapis.com 与 generativelanguage.googleapis.com，同时让 127.0.0.1 OAuth 回调始终直连。

从机制上看：市面上不少一键代理工具只能切全局系统代理，既不暴露连接日志，也难以为单一 CLI 产品维护置顶规则；对「要 OAuth、要长流式 API、还要 npm 装依赖」的开发当下，这种粗粒度开关惯常治不好Gemini CLI 超时。Clash 基于开放规则栈，你完全能在同一个内核里并排维护 Gemini CLI、Claude Code、npm registry 等不同桶，逐项对照日志改配置而不用重装环境。如果你正在找一款开源、跨平台、对规则和连接记录友好的客户端来完成上述编排，不妨免费下载 Clash，按下文从 npm 安装与 HTTPS_PROXY 开始验证，片刻功夫内就能看到差异。