Gemini CLI搭配v2rayN：国内访问配置指南

想在国内网络环境中使用 Gemini CLI，真正影响体验的通常不是命令本身，而是认证请求、API 请求、终端代理变量和 v2rayN 分流规则是否走在同一条链路上。浏览器能够打开网页，并不代表终端里的 Node.js 进程已经使用代理；v2rayN 显示节点可用，也不代表 Gemini CLI 的 OAuth 登录请求没有被直连。

本文以 Windows 上的 v2rayN 为主要示例，从客户端安装、订阅导入开始，逐步配置本地代理端口、PowerShell 环境变量、Gemini CLI 登录和路由分流。文中端口使用 v2rayN 常见默认值作为示例，实际操作前应以“设置”→“参数设置”→“核心基础设置”中显示的 HTTP、SOCKS 端口为准。

先理解 Gemini CLI 的请求路径

Gemini CLI 的访问过程至少包含三类请求。第一类是安装或更新命令执行时访问的 npm 注册表；第二类是首次启动时的 Google 账户认证、授权回调或设备登录请求；第三类是登录完成后发送到 Gemini 服务的模型请求。它们可能使用不同的域名和不同的连接时机，因此不能只用“浏览器能不能打开某个网页”来判断整体环境是否正常。

在 v2rayN 中，节点只是代理出站的一部分。客户端还需要启动 Xray 或其他选定核心，在本机监听 HTTP、SOCKS 或混合代理端口。终端程序连接这些端口后，v2rayN 才能把请求交给当前活动节点。若终端没有设置代理变量，流量就可能直接交给本地网络；若设置了错误端口，则通常会出现连接被拒绝、连接重置或长时间等待。

可以把故障定位拆成三段。第一段是本地入口，检查 v2rayN 是否运行、活动服务器是否已设置、本地端口是否监听；第二段是终端环境，检查 PowerShell 或其他 Shell 是否真正读取了代理变量；第三段是远程请求，观察认证域名和模型请求是否被正确代理。只有三段都成立，Gemini CLI 才能稳定工作。

安装 v2rayN 并导入可用订阅

如果电脑尚未安装 v2rayN，建议从本站前往安装包页面选择当前 Windows 平台对应版本。下载后解压到具有写入权限的目录，例如用户目录下的独立文件夹。首次启动时不要把程序放在权限受限或会被系统清理的临时目录中，否则订阅、日志和本地配置可能无法正常保存。

打开 v2rayN 后，先确认核心状态正常，再导入订阅。不同版本的菜单排列可能略有变化，但基本路径通常是“订阅分组”→“订阅设置”→“添加”。将服务商提供的订阅地址粘贴到地址栏，保存后执行“更新订阅”或“更新全部订阅”。不要把包含授权信息的完整订阅地址发布到日志、截图或公共聊天中。

1. 安装并启动

   解压 v2rayN 后运行主程序，等待核心状态显示正常。若 Windows 防火墙弹出网络访问提示，只允许来自可信网络环境的必要访问。

2. 添加订阅

   进入“订阅分组”→“订阅设置”→“添加”，粘贴订阅链接并保存。分组名称建议使用“主用”或“Gemini”，方便后续确认节点来源。

3. 更新节点

   执行“更新订阅”，等待列表出现服务器数量变化或更新成功提示。若提示超时，先不要编辑节点，检查订阅地址是否过期。

4. 选择活动服务器

   在服务器列表中选中一个延迟较低、协议参数完整的节点，执行“设为活动服务器”。单击列表行只代表选中，不一定代表已经成为当前出口。

5. 确认本地端口

   进入“设置”→“参数设置”→“核心基础设置”，记录 HTTP 和 SOCKS 端口。本文示例使用 HTTP 10809、SOCKS 10808，实际值以本机显示为准。

导入订阅后，不要只看节点数量。先测试一两个节点，再观察 v2rayN 日志是否出现核心启动成功、监听端口成功以及连接建立记录。Gemini CLI 更适合使用稳定的 TCP 代理入口；如果当前模式启用了 TUN，也仍建议先明确终端变量，避免系统级接管与应用级代理同时存在时难以判断流量来源。

系统代理、终端代理与 TUN 如何选择

系统代理适合浏览器和遵循 Windows 代理设置的桌面应用，但命令行程序是否读取系统代理取决于运行时和网络库。TUN 模式能够接管更广泛的应用流量，却会同时引入 DNS、路由、虚拟网卡和局域网排除等变量。首次配置 Gemini CLI 时，建议先使用 HTTP 端口加环境变量完成验证，成功后再考虑是否需要 TUN。

配置终端环境变量并验证登录

在 Windows PowerShell 中，可以先为当前窗口设置代理变量。以下示例假设 v2rayN 的 HTTP 端口为 10809：

$env:HTTP_PROXY = "http://127.0.0.1:10809"
$env:HTTPS_PROXY = "http://127.0.0.1:10809"
$env:NO_PROXY = "localhost,127.0.0.1"
$env:GEMINI_CLI_NO_UPDATE_NOTIFIER = "1"

NO_PROXY 用于排除本机回环地址，避免终端访问本地服务时再次进入代理。最后一行不是联网必需项，只是减少每次启动时的更新提示；如果希望保留更新检查，可以不设置。不要把代理变量中的地址写成 v2rayN 窗口显示的远程节点地址，终端应连接本机监听地址 127.0.0.1。

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

set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set NO_PROXY=localhost,127.0.0.1

如果使用 Git Bash 或 macOS、Linux Shell，则使用：

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

设置变量后，先不要立即执行登录。可以使用 PowerShell 检查变量是否存在，并确认 v2rayN 进程正在监听对应端口：

Get-ChildItem Env:HTTP_PROXY
Get-ChildItem Env:HTTPS_PROXY
Test-NetConnection 127.0.0.1 -Port 10809

最后一条命令中的 TcpTestSucceeded 应为 True。这只能证明本地端口有程序接收 TCP 连接，不能证明远程节点可用。若结果为 False，先回到 v2rayN 检查核心是否启动、端口是否改过，以及是否有其他程序占用了该端口。

安装 Gemini CLI 后，在同一个已经设置变量的终端窗口中启动命令。不同版本的命令名称和认证提示可能会有变化，按当前终端显示完成登录即可。若浏览器授权页面已经打开，但终端迟迟没有完成回调，应同时观察 v2rayN 日志和终端输出：前者判断请求是否经过本地代理，后者判断 CLI 是否收到授权结果。

为 Gemini 相关域名设置分流规则

如果 v2rayN 使用规则路由，不能简单地把所有流量都交给代理，也不建议只添加一个模糊的“Google”规则就认为认证和模型请求已经覆盖。Gemini CLI 可能访问账户、认证、API、模型服务和更新服务等不同域名。具体域名会随客户端版本、认证方式和服务端调整而变化，因此分流时应以 v2rayN 日志中实际出现的目标域名为准。

在 v2rayN 中进入“设置”→“参数设置”→“路由设置”，先确认当前路由模式和规则来源。若使用自定义规则，可以把明确需要代理的域名放在直连规则之前，再把局域网和中国大陆常用站点保留为直连。规则不是越多越好，过度枚举域名会增加维护成本，也可能因为漏写新域名造成登录阶段时好时坏。

• 本机和局域网：将 geoip:private、局域网网段和本地回环地址保持直连，避免命令行访问本机服务时绕入代理。
• Gemini 相关请求：根据日志补充实际出现的认证、账户和 API 域名，统一指向代理出站。
• 国内常用目标：使用 geosite:cn 或 geoip:cn 直连，但要确认没有把 Gemini 所需域名错误归入直连。
• 默认规则：将剩余流量交给代理或按个人需求处理，兜底规则必须放在列表末尾。

如果启用 TUN 模式，还需要检查 DNS 设置、虚拟网卡状态和绕过局域网选项。TUN 能让没有读取环境变量的应用也进入代理，但 Gemini CLI 已经可以通过 HTTP_PROXY 明确指定路径，二者同时使用时要避免重复接管。排查阶段最好一次只改变一个变量：先关闭 TUN、保留终端 HTTP 代理完成登录；确认成功后，再开启 TUN 测试是否需要更广泛的应用接管。

按现象定位登录失败与请求超时

登录页面打不开、浏览器完成授权但终端失败、命令启动后请求超时，这三种现象对应的故障层并不相同。判断时应记录发生时间、当前节点、终端类型、代理端口和 v2rayN 日志中的第一条错误，不要在同一轮测试中同时更换节点、修改路由和重装 CLI。

127.0.0.1:10809 connection refused
ECONNRESET
ETIMEDOUT
socket hang up
407 Proxy Authentication Required
fetch failed

• connection refused：通常表示本地端口没有监听，或环境变量填写了错误端口。检查 v2rayN 核心状态、HTTP 端口和是否需要重启核心。
• ETIMEDOUT：可能是节点不可达、远程域名未走代理、规则把目标送入直连，或线路质量不足。先查看 v2rayN 是否出现对应目标域名和出站记录。
• ECONNRESET、socket hang up：可能发生在代理链路被中途关闭、TLS 参数不匹配或节点负载过高时。更换一个已测试可用的节点进行对比。
• 407 Proxy Authentication Required：说明程序连接到的代理要求认证。v2rayN 本地 HTTP 端口通常不需要用户名密码，若出现该提示，应检查是否误填了其他企业代理或远程代理地址。
• fetch failed：这是运行时层面的概括错误，不能单独判断原因。需要结合前一条 v2rayN 日志、终端变量和目标域名继续定位。

如果浏览器认证成功，但 Gemini CLI 仍然提示登录失败，先关闭旧终端并新建窗口，再重新设置环境变量。环境变量只对启动后的进程生效，已经打开的终端不会自动获得后来新增的用户变量。若使用图形化终端或编辑器内置终端，也要确认它是否继承了系统环境，而不是继续使用旧进程中的变量。

如果登录成功但模型请求超时，问题通常已经从认证层转移到 API 请求层。此时检查活动节点是否仍在线、API 域名是否命中代理规则、v2rayN 是否出现连接重置，以及当前节点是否对长连接或较大响应支持稳定。不要仅依据网页首页判断线路质量，命令行请求的连接保持时间、响应大小和目标域名可能与浏览器访问完全不同。

完成配置后，可以建立一套固定检查顺序：先启动 v2rayN 并确认活动服务器，再检查 127.0.0.1 的代理端口，然后在新终端设置 HTTP_PROXY 和 HTTPS_PROXY，最后启动 Gemini CLI。每次更换节点后只重复后两步，不必重新导入订阅。若需要在不同网络之间切换，优先保留一份已验证的终端配置和一份简洁路由规则，减少临时改动带来的变量。