Gemini CLI 代理配置与排障教程：登录超时、fetch failed、地区不支持怎么办（附 Gemini API / AI Studio，2026）

Gemini CLI 是 Google 开源的终端 AI 工具，用 Node.js 写成，可以用 Google 账号或 Gemini API Key 登录。国内用户的典型遭遇是：浏览器里 gemini.google.com、aistudio.google.com 都能打开，终端里的 Gemini CLI 却登录超时，或者一发消息就报 fetch failed；换了几个节点之后，又可能遇到 User location is not supported for the API use.。

前一类问题的原因和 Codex、Claude Code 一样：Gemini CLI 不读系统代理，只认环境变量。后一类是 Google 的地区判定，它和你在网页上查到的 IP 归属不一定一致。下面先说一件 2026 年的重要变化，再按「原理 → 安装 → 配置 → 认证 → 验证 → 排查」的顺序讲（基于 Gemini CLI v0.65 源码与 2026 年 10 月的官方文档）。

一、先确认：你的账号还能用 Gemini CLI 吗

Google 在 2026 年 5 月的开发者博客里宣布，从 2026 年 6 月 18 日起，Gemini CLI 和 Gemini Code Assist 编辑器插件不再为以下账号提供服务：免费的 Gemini Code Assist for individuals，以及 Google AI Pro、Google AI Ultra 订阅。这些账号用「Sign in with Google」登录 Gemini CLI 已经不可用，官方让它们迁移到新的 Antigravity CLI。

官方说明仍可继续使用 Gemini CLI 的情况：

认证方式	状态（截至 2026 年 10 月）
公司的 Gemini Code Assist Standard / Enterprise 授权（Google 账号登录）	不受影响
付费的 Gemini API Key	可继续使用
Vertex AI（Gemini Enterprise Agent Platform）	可继续使用
免费的 Gemini API Key	公告只写了「付费 API Key」，仓库里的配额文档仍列着免费档每天 250 次请求，以实际使用为准

所以如果你是个人用户，之前用 Google 账号登录，现在打开 Gemini CLI 被提示去用 Antigravity，那不是网络问题。本文的代理配置对 Gemini CLI 的各种认证方式都适用；Antigravity CLI 的情况在第八节单独说。

二、Gemini CLI 怎么决定走哪个代理

这部分直接看源码（packages/cli/src/config/config.ts 与 packages/core/src/utils/fetch.ts）：

• 启动时按 HTTPS_PROXY → https_proxy → HTTP_PROXY → http_proxy 的顺序，取第一个有值的作为代理，所有请求共用这一个地址；
• NO_PROXY（或 no_proxy）里的地址不走代理；
• 不读 ALL_PROXY，也不读系统代理。

另外三点很容易踩：

1. 不支持 SOCKS。 Gemini CLI 的网络层用的是 Node.js 的 undici 库，代理地址必须以 http:// 或 https:// 开头。写成 socks5://127.0.0.1:7897，启动就会报 Invalid URL protocol: the URL must start with http: or https:（GitHub issue #6822）。原生 SOCKS5 支持有人提过功能请求（#21410），官方回复目前没有计划。Clash Verge Rev 的混合代理端口同时接受 HTTP 和 SOCKS，写 http://127.0.0.1:7897 即可。
2. settings.json 里没有代理设置项。 和 Claude Code 不同，Gemini CLI 的 ~/.gemini/settings.json 没有代理相关的设置项（v0.65 的设置定义里找不到），代理只能通过环境变量传进去。
3. 只在启动时读一次。 改完变量要退出 Gemini CLI，新开终端再启动。

.gemini/.env 的加载规则

Gemini CLI 启动时会找一个 .env 文件加载环境变量，规则和 Codex 很不一样（源码 packages/cli/src/config/settings.ts）：

• 从当前目录往上逐级找，只用找到的第一个文件。 每一级先找 .gemini/.env，再找 .env；都没有时最后才用 ~/.gemini/.env、~/.env。也就是说，项目目录里随便一个 .env（比如前端项目自己的）会让 ~/.gemini/.env 完全不被读取。
• 不覆盖已有的环境变量。 只有系统里还没设的变量才会从 .env 补上。这一点和 Codex 正好相反（Codex 的 .env 会覆盖系统变量）。
• 未信任的文件夹只读认证变量。 Gemini CLI 默认开启「文件夹信任」，在没有被信任的目录里，.env 只加载 GEMINI_API_KEY、GOOGLE_API_KEY、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION 这几个，HTTPS_PROXY 会被忽略；.gemini/.env 也只在信任的目录里才会被找。

结论：代理写在系统或 shell 的环境变量里最可靠，.env 只适合放 API Key 这类认证信息。

最省事的做法：切到「整机」。 Clash Verge Rev（科技熊版）首页「科技熊工作室」卡片上有「浏览器 / 整机」切换。「浏览器」只把代理写进系统设置，读不读由程序自己决定；切到「整机」（模式保持「规则」）会用虚拟网卡在系统层面接管所有程序的海外流量，Gemini CLI 不读系统代理、不支持 SOCKS 这些问题都绕开了，不用设任何变量。第一次切换需要按提示安装系统服务、输入一次管理员密码。Linux 版卡片上没有这个切换，Linux 用户按下文设环境变量。

三、准备：端口与 Google 的地区判定

端口。 本文以科技熊推荐的电脑客户端 Clash Verge Rev（科技熊版）为例：打开首页，滚到最下方的「Clash 信息」卡片，「混合代理端口」那一行就是要填的端口，科技熊版默认是 7897（同一张卡片的「系统代理地址」会显示 127.0.0.1:7897）。卡片上显示的不是 7897，就把下文的 7897 换成它。

支持的地区。 按 Google 官方「Available regions for Google AI Studio and Gemini API」页面（2026 年 10 月 22 日更新），中国大陆、香港、澳门都不在 Gemini API 和 AI Studio 的支持列表里；台湾、日本、新加坡、美国等在列表内。注意 Gemini 网页版、App、API 各有各的地区列表：Gemini 网页版 2026 年 3 月起已对香港个人用户开放，但 API 与 AI Studio 仍未包含香港，所以「网页能用、CLI 报地区不支持」是可能的。

Google 用自己的 IP 库判断地区。 这是 Gemini 和其它 AI 服务最大的不同。Cloudflare trace、ipinfo 之类的网站查到的归属地，和 Google 的判断不一定一致：一些海外机房的 IP 会被 Google 判成中国或香港；同一台服务器走 IPv4 和走 IPv6，结果也可能不同（Google AI 开发者论坛里有用户实测 IPv4 正常、IPv6 报地区不支持）。所以排查 Gemini 的地区问题，要看 Google 自己的反馈，而不是第三方 IP 查询：

• 有 API Key 的，直接问 Gemini API（Windows PowerShell 里写 curl.exe，变量写法见下文）：

  curl -x http://127.0.0.1:7897 "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY"

  返回模型列表说明这个出口可用；返回 400、FAILED_PRECONDITION、User location is not supported for the API use.，就是 Google 判定这个出口不在支持地区，换节点即可，改配置没有用。

• 没有 Key 的，可以在浏览器里打开 YouTube 看一眼：左上角 Logo 旁边的小字是 Google 判定的国家或地区代码（美国不显示），显示 CN 或 HK 说明这个出口在 Google 眼里不在 Gemini API 的支持范围。这只是粗略参考，浏览器和终端可能走的不是同一个节点。

四、安装：npm 也要能连上

Gemini CLI 需要 Node.js 20 及以上。官方给出的安装方式：

npm install -g @google/gemini-cli   # 通用
brew install gemini-cli             # macOS / Linux 的 Homebrew
npx @google/gemini-cli              # 不安装，直接运行

npm 需要能连上 registry：在同一个终端里先设好下一节的代理变量再装，或者临时换国内镜像 npm install -g @google/gemini-cli --registry=https://registry.npmmirror.com。装完用 gemini --version 确认。

五、Windows 配置

用用户级环境变量，一次设置，之后新开的终端都生效（把 7897 换成你的端口）：

setx HTTPS_PROXY "http://127.0.0.1:7897"
setx HTTP_PROXY  "http://127.0.0.1:7897"
setx NO_PROXY    "localhost,127.0.0.1,::1"

setx 只对之后新开的程序生效，设完关掉终端重开。只想在当前窗口临时用：

$env:HTTPS_PROXY = "http://127.0.0.1:7897"
$env:HTTP_PROXY  = "http://127.0.0.1:7897"
gemini

检查当前生效的值：Get-ChildItem env: | ? Name -match proxy。如果这里出现了你没设过的 socks5:// 地址，多半是别的软件或旧教程留下的，删掉或改成 http://。

六、macOS 与 Linux 配置

写进 shell 配置文件（macOS 默认 zsh 用 ~/.zshrc，bash 用 ~/.bashrc）：

export HTTPS_PROXY="http://127.0.0.1:7897"
export HTTP_PROXY="http://127.0.0.1:7897"
export NO_PROXY="localhost,127.0.0.1,::1"

保存后执行 source ~/.zshrc 或新开终端，用 env | grep -i proxy 确认。

在 VS Code、Cursor 的内置终端里用：内置终端每次新开都会读一遍 ~/.zshrc，但已经开着的终端标签不会更新。改完变量后新开一个终端标签，先 echo $HTTPS_PROXY 确认再启动 gemini。

WSL： WSL2 里的 127.0.0.1 默认指 WSL 自己。Windows 11 可以在 %USERPROFILE%\.wslconfig 里设 networkingMode=mirrored；否则要在代理客户端里打开「允许局域网连接」，代理地址写 Windows 主机的内网 IP。

七、认证：API Key、Google 账号与 Vertex AI

用 Gemini API Key（个人用户现在最常用的方式）。 在 aistudio.google.com 里创建 API Key（打开 AI Studio 本身也要求出口在支持地区），然后设成环境变量：

export GEMINI_API_KEY="你的 Key"          # macOS / Linux

setx GEMINI_API_KEY "你的 Key"             # Windows

启动 gemini 后在认证方式里选「Use Gemini API Key」。也可以把 GEMINI_API_KEY=你的 Key 写进 ~/.gemini/.env，但按第二节的规则，它只在信任的目录里、且项目目录里没有别的 .env 时才会被读到；拿不准就直接设环境变量。

用 Google 账号登录（公司的 Code Assist 授权）。 选「Sign in with Google」后，Gemini CLI 会在本机随机开一个端口，浏览器登录完成后跳回 http://127.0.0.1:<端口>/oauth2callback，然后 CLI 再向 oauth2.googleapis.com 换取登录凭据。这一步是 CLI 自己发的请求，走的是终端里的代理变量，所以「浏览器里登录成功、终端报 Failed to login. Message: request to https://oauth2.googleapis.com/token failed, reason: connect ETIMEDOUT」几乎都是终端没设代理。另外：

• NO_PROXY 里要有 localhost,127.0.0.1，保证本机回调不被送进代理；
• 在 SSH 远程服务器上没有浏览器，可以设 NO_BROWSER=true 再启动，CLI 会给出一个链接，在自己电脑的浏览器里打开、把授权码粘回终端；
• 需要固定回调端口时可以设 OAUTH_CALLBACK_PORT；
• 公司、学校、Workspace 账号还要设 GOOGLE_CLOUD_PROJECT 为对应的 Google Cloud 项目编号。

用 Vertex AI。 设 GOOGLE_CLOUD_PROJECT 与 GOOGLE_CLOUD_LOCATION（例如 us-central1），通过 gcloud 的应用默认凭据、服务账号或 Google Cloud API Key 认证。用 gcloud 登录时，gcloud 本身也要能连上 Google，它有自己的代理设置（gcloud config set proxy/type http 等），和环境变量是两套。

自己写代码调 Gemini API 时

• Python（google-genai 库）：底层用 httpx，默认会读 HTTPS_PROXY 等环境变量，设好即可。
• Node.js（@google/genai 等用内置 fetch 的库）：Node 内置的 fetch 默认不读代理环境变量。Node.js 22.21 / 24 及以上版本可以设 NODE_USE_ENV_PROXY=1（或启动参数 --use-env-proxy）打开；更早的版本要在代码里自己配置代理 agent。
• 浏览器里的 AI Studio 走系统代理，和上面两者无关。

八、关于 Antigravity CLI

Antigravity CLI 是 Google 给个人用户的替代品，用 Go 编写，和 Antigravity 2.0 桌面应用共用后台。它的代理支持目前没有找到官方文档：社区反馈早期版本不认代理环境变量，需要借助 graftcp、Proxifier 一类按进程转发的工具；之后有用户反馈新版本已经支持环境变量。可以先按第五、六节设好 HTTPS_PROXY 试试，不生效的话改用代理客户端的 TUN 模式（Clash Verge Rev 里叫「虚拟网卡模式」），它在系统层接管流量，不依赖程序读不读代理设置。地区要求与 Gemini 相同。

九、分流：Gemini 相关域名走同一个出口

Gemini CLI 和 Gemini API 用到的主要域名：

域名	用途
generativelanguage.googleapis.com	Gemini API（API Key 方式的主要流量）
cloudcode-pa.googleapis.com	Google 账号登录方式下的模型请求（Code Assist 接口）
oauth2.googleapis.com、accounts.google.com	登录与凭据刷新
*-aiplatform.googleapis.com	Vertex AI
aistudio.google.com、gemini.google.com	AI Studio 与 Gemini 网页
registry.npmjs.org	安装与更新

很多分流规则只把 gemini.google.com、generativelanguage.googleapis.com 这些放进 Gemini 分组，而 cloudcode-pa.googleapis.com、oauth2.googleapis.com 落进通用的 Google 规则走了另一个分组。两个分组出口在不同地区时，就会出现「登录成功、对话报地区不支持」或反过来的情况。科技熊下发的规则也是这样分的：Gemini 网页、AI Studio、Gemini API（generativelanguage.googleapis.com）和 Google 账号登录（accounts.google.com）走「🤖Gemini」分组，oauth2.googleapis.com、cloudcode-pa.googleapis.com 等其它 Google 域名走「🔰国外流量」。所以用 Gemini CLI 时，在 Clash Verge Rev 的「代理」页把「🤖Gemini」和「🔰国外流量」选到同一个地区的节点（例如都选台湾或都选美国）。选好后到「连接」页按 googleapis 搜索，确认这些连接落在同一地区。

固定节点。 Gemini CLI 一次任务会持续发起多次请求，节点在中途按延迟自动切换，出口 IP 会在不同地区之间跳。Google 对出口 IP 的判定又比较敏感，频繁换 IP 容易遇到人机验证或「异常流量」提示。在 Clash Verge Rev 的「代理」页把「🤖Gemini」分组改为手动选择一个固定节点，先用上面的 API 请求确认这个节点可用，再到「连接」页「关闭全部」清掉旧连接。

十、常见报错速查

报错	含义	先查哪里
User location is not supported for the API use.（400 FAILED_PRECONDITION）	Google 判定出口不在支持地区	换节点，用第三节的 API 请求逐个验证
Failed to login. Message: request to https://oauth2.googleapis.com/token failed, reason: connect ETIMEDOUT	终端里的 CLI 没走代理	HTTPS_PROXY 是否在启动前设好
fetch failed、ConnectTimeoutError	请求发不出去或超时	代理变量、端口；节点是否可用
Invalid URL protocol: the URL must start with http: or https:	代理变量写成了 socks5://	改成 http://127.0.0.1:端口
API key not valid. Please pass a valid API key.（400 INVALID_ARGUMENT）	Key 写错或已失效；能收到这条说明网络是通的	重新复制 Key，检查变量里有没有多余空格
429、RESOURCE_EXHAUSTED	配额用完，和网络无关	等配额恢复，或查看所用档位的限额
个人 Google 账号登录后提示改用 Antigravity	2026 年 6 月 18 日后的政策变化	改用 API Key，或迁移到 Antigravity CLI
浏览器里频繁出现 Google 人机验证	出口 IP 被 Google 标为异常流量	换一个节点并固定下来

排查顺序和其它 AI 编程工具一样，从外到内，一层只回答一个问题：

1. 代理客户端开着吗，端口是多少？ 看客户端设置。
2. 这个端口出去，Google 认不认？ 用第三节的 curl -x 请求模型列表。
3. Gemini CLI 读到的是这个端口吗？ 在启动 gemini 的同一个终端里看 HTTPS_PROXY 的值；记住它不读系统代理，也不读 ALL_PROXY。
4. 相关域名走的是同一个出口吗？ 「连接」页搜 googleapis。

第 2 步通过、第 3 步不对，问题在配置上，不用换节点；第 2 步不通过，改配置没有用，换节点。

关于线路的选择

Gemini 对网络的要求比其它 AI 服务多一条：出口不仅要在支持地区，还要被 Google 自己的 IP 库认成这个地区。加上本机代理变量写对、相关域名同一出口、长时间使用不换出口，就是全部条件。配置部分照上面做，线路部分取决于你用的服务。

如果你在找线路，科技熊是可选项之一：每个节点提供 [专线]（走 BGP IEPL 专线）和经海外中转的 [备线] 两条线路，备线只按同节点专线的四分之一计流量（最低 0.5x）；订阅里 Gemini 有单独的分组，可以在里面手动固定节点，台湾、美国节点有家宽（住宅）IP。AI 节点从钻石尊爵套餐起；希望出口只有自己在用的，可以加购家宽独享 IP（说明）。桌面端按 Clash Verge Rev 教程 下载客户端、登录账号即可，默认混合端口 7897，正好填进上面的 HTTPS_PROXY。新用户有 ¥1 体验（1GB / 1 天，不含 AI 节点），可以先测一下连接质量。是否选择由你判断。

Gemini 网页版、Grok、Midjourney 等其它 AI 工具的访问问题，见 Gemini / Grok / Midjourney 等 AI 工具国内访问指南；同样在终端里用的 AI 编程工具，见 Codex 代理配置教程 和 Claude Code 代理配置教程；用 Cursor 编辑器的，见 Cursor 代理配置与排障教程。