症状：Gemini CLI 在哪一步最容易「卡住」？

2026 年，Gemini CLI（@google/gemini-cli）已成为开发者终端里高频使用的免费 AI Agent：一条命令就能在仓库里读文件、改代码、跑工具。但在国内或受限网络环境下，常见挫败感往往出现在三个节点——npm 全局安装阶段就 ETIMEDOUT；安装成功后 OAuth 登录浏览器已打开却永远等不到「授权成功」；或者登录看似完成，第一次发 prompt 时模型请求又报网络超时。社区里很多人会先怀疑节点质量或 API Key，但更常见的根因是：终端进程根本没走你以为已经开好的 Clash 链路，或者出站规则把 Google API 域名误判到了直连／错误策略组。

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

与站内其它 Gemini 文的分工：若你主要用网页 AI Studio，请读《Gemini / AI Studio 分流》；若场景是企业 Gemini Enterprise / Vertex 控制台，请读《Gemini Enterprise 与 GCP 分流》。本文聚焦终端里的 Gemini CLI 进程与 npm 安装链，三者规则可并排维护，不宜混成一团。

第一步：别让问题出在 `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 做后续排障，避免两条链路混在一起改规则。

版本提示：Gemini CLI 迭代很快，本文域名清单以 2026 年 5 月开源代码与社区工单为基准。产品若新增子域或切换端点，请以你本机 Clash 连接日志中的真实 SNI为准增量维护，不要只复制静态列表。

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——这些在排障日志里偶尔出现，可酌情加入规则或至少确认未被大陆兜底抢先直连。

403 不一定是网络：社区工单里存在 OAuth 绑定到不可访问 Cloud 项目导致 403 的个案，与代理无关。若连接日志显示域名已正确走代理且 TLS 成功，仍返回权限错误，应转向 Google 帐号／订阅侧排查，不要无限换节点。

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

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

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 专文，此处不展开。

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

在 Clash 里怎么拆「Gemini-CLI」策略组

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

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

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

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

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

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 握手可能被错误直连，表现为随机超时。

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

终端代理：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

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

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

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，不要两个路径共用一个明显不合适的出口。

分步验证清单（建议照着勾）

确认 npm install -g @google/gemini-cli 已成功，registry 链路按 npm 分流文走代理。
打开连接日志，在同一 shell 中设置 HTTPS_PROXY 后运行 gemini，复现一次失败并记录主机名与命中规则。
对照上文域名表，把缺失的 cloudcode-pa.googleapis.com 或 generativelanguage.googleapis.com 补进 Gemini-CLI 组。
确认 rules 中 127.0.0.0/8 与 Google API 域名在 GEOIP-CN 与国内兜底之前。
OAuth 登录时观察：授权页域名走代理，127.0.0.1 回调不走代理。
分别用 OAuth 与 GEMINI_API_KEY 各测一次模型请求，确认两条路径都命中预期组。
若进程仍绕开环境变量，启用 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：AI Studio 网页已通，还要单独配 Gemini CLI 吗？
要。网页侧以 gemini.google.com、aistudio.google.com 为主；CLI 的 OAuth 路径还依赖 cloudcode-pa.googleapis.com，API Key 路径走 generativelanguage.googleapis.com。半通最常见原因就是只配了网页域名。

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

小结

把 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 开始验证，几分钟内就能看到差异。

请遵守所在地法律法规与各在线服务条款；本文仅供技术原理与客户端配置说明。远端规则集请自行甄别来源可信度。