Gemini CLI 配合 Clash Verge：国内访问配置指南

先理解 Gemini CLI 与 Clash Verge 的连接关系

Gemini CLI 是运行在终端中的命令行工具,而 Clash Verge 是负责接管和转发网络流量的代理客户端。两者不是同一个层面的软件:Clash Verge 管理节点、代理端口、规则和 DNS,Gemini CLI 则负责读取本地环境变量、调用认证流程并向远程 API 发起请求。

这意味着,仅仅在 Clash Verge 里选中一个可用节点,不一定代表 Gemini CLI 已经会自动走代理。浏览器能够访问某个站点,也不代表终端程序一定使用了同一条网络路径。浏览器可能读取系统代理,而命令行程序通常只读取 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 等环境变量;如果程序自身不支持这些变量,则需要使用 TUN 模式接管。

Gemini CLI 的使用过程大致分为三段:安装命令行程序、完成 Google 账号或 API 凭据认证、发送模型请求。每一段都可能对应不同的故障。安装包下载失败通常是终端没有使用代理,浏览器登录页面打不开通常是认证流量没有正确转发,而命令执行后出现超时或连接错误,则需要重点检查 API 请求的代理变量、规则匹配和节点状态。

核心思路:先让 Clash Verge 本身确认节点可用,再让终端明确指向 Clash 的本地端口,最后通过日志和命令输出确认 Gemini CLI 的请求确实经过了代理。

准备 Clash Verge:导入订阅并确认本地端口

开始配置前,先安装能够正常运行 mihomo 或兼容 Clash 配置的 Clash Verge 版本。不同版本的界面名称可能略有差异,但通常都包含“配置”“代理”“设置”和“日志”等区域。客户端版本不同,默认端口也可能不同,不要直接照抄示例端口,应以本机设置页显示的端口为准。

打开 Clash Verge,进入配置管理页面,粘贴服务提供方给出的 Clash 订阅链接,填写一个便于识别的名称并执行更新。
订阅解析完成后,确认配置文件能够正常加载,代理页里可以看到节点或代理组,而不是空列表或解析错误。
进入代理页选择一个可用节点,如果配置使用了“自动选择”或 url-test 分组,先手动确认当前实际选中的节点。
打开设置页面,记录 HTTP 代理端口和 SOCKS 代理端口。常见端口可能是 7890、7897 或其他数值,实际配置以界面显示为准。
先打开系统代理,让浏览器或其他支持系统代理的程序通过 Clash Verge 访问目标服务,确认基础链路没有问题。

订阅导入成功不等于所有域名都能访问。订阅内容通常包含节点、代理组和规则,但不同服务提供方的分流策略差异很大。Gemini CLI 相关请求可能涉及认证页面、模型 API、遥测或更新服务,它们不一定全部属于同一个域名。排查时不要只测试一个网页,应观察实际请求失败时的目标域名和规则结果。

注意:不要把订阅链接、API 密钥或 OAuth 凭据发布到截图、日志仓库和公共聊天中。订阅链接通常带有个人识别信息或流量权限,一旦泄露应立即在服务提供方后台重置。

选择系统代理、环境变量还是 TUN 模式

Gemini CLI 的代理方式可以按终端环境和客户端支持情况选择。优先推荐为终端设置代理环境变量,因为范围清晰、容易关闭,不会影响系统中的其他应用。如果某个子进程忽略环境变量,再考虑 TUN 模式作为兜底。

方式	适用情况	优点	需要注意
系统代理	浏览器和支持系统设置的应用	操作简单,可快速验证基础网络	命令行程序不一定读取系统代理
环境变量	Gemini CLI、Node.js 工具和终端脚本	作用范围明确,便于按项目启用	端口、协议和变量作用域必须正确
TUN 模式	不支持代理变量的程序或多进程工具链	可接管更广泛的系统流量	需要额外权限,可能与 VPN、虚拟网卡冲突

如果只是使用 Gemini CLI,建议先关闭 TUN,通过环境变量完成测试。这样可以减少 DNS 劫持、路由冲突和其他代理软件抢占虚拟网卡造成的干扰。确认命令行请求稳定后,再根据实际需求决定是否长期启用 TUN。

动手配置:在终端设置 Gemini CLI 代理

下面以 Clash Verge 设置页显示的 HTTP 代理地址为例。假设本地监听地址是 127.0.0.1,端口是 7897;如果你的客户端显示的是其他端口,必须替换成实际数值。HTTP 代理端口通常可以同时处理 HTTPS 请求,变量名称仍然建议完整设置。

Windows PowerShell 配置

在当前 PowerShell 窗口临时设置代理,关闭窗口后变量就会失效:

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

如果希望只让当前命令使用代理,可以把环境变量和命令放在同一个脚本或终端会话中,不要一开始就写入系统级环境变量。系统级变量可能影响包管理器、版本控制工具、公司内网程序和其他本地服务。

macOS 与 Linux 配置

在 Bash 或 Zsh 中可以使用下面的写法:

export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
export ALL_PROXY="http://127.0.0.1:7897"

如果终端工具只接受 SOCKS5 代理,可以把地址改为 Clash Verge 的 SOCKS 端口,例如 socks5://127.0.0.1:7898。但不要把 HTTP 端口和 SOCKS 端口混用。最稳妥的做法是查看设置页中每个监听器的协议类型,并根据程序文档选择对应变量。

先验证代理,再启动 Gemini CLI

设置变量后,先用一个简单的网络请求检查终端是否能通过代理访问目标站点。测试命令不需要包含账号信息:

curl -I https://generativelanguage.googleapis.com

如果返回 HTTP 响应头,说明终端至少建立了连接;如果提示连接被拒绝,优先检查 Clash Verge 是否正在运行、端口是否写对、HTTP 与 SOCKS 类型是否匹配。如果请求一直超时,打开 Clash Verge 的日志页,观察是否出现该域名以及实际使用的代理组。完全没有日志记录,通常表示命令没有使用这些变量,或者请求在程序内部被其他网络库处理。

在确认代理变量有效后,再按照 Gemini CLI 当前版本的官方安装说明完成安装和登录。认证方式可能随版本变化,常见流程包括浏览器 OAuth 登录或使用环境变量提供 API 凭据。不要因为登录页面打不开就反复更换账号,先确认浏览器、终端和 Clash 日志中的请求路径是否一致。

安装 Gemini CLI 并处理认证流程

Gemini CLI 通常依赖 Node.js 运行环境或对应的包管理器。安装前先确认 Node.js 版本满足当前工具的要求,再使用官方文档给出的安装命令。不同发布版本的包名和启动命令可能调整,不要使用来源不明的第三方脚本替代安装命令。安装阶段如果需要访问包仓库,同样会受到终端代理变量影响。

完成安装后,先运行版本检查命令,确认终端能够找到可执行文件。如果系统提示“命令不存在”,检查包管理器的全局安装目录是否在 PATH 中;如果提示权限错误,不要直接使用高权限覆盖整个用户目录,应先检查 Node.js 和包管理器的安装方式。

登录阶段通常会打开浏览器,由浏览器完成账号授权,再把授权结果交给本地命令行程序。此时可能出现两条不同的网络路径:浏览器使用系统代理,终端进程使用环境变量。如果浏览器能打开登录页面,但回到终端后仍显示认证超时,重点检查终端是否能访问认证服务,以及本地回调端口是否被防火墙或其他程序占用。

浏览器页面打不开:检查 Clash Verge 的系统代理开关、当前节点和认证域名的规则匹配。
浏览器能登录但 CLI 不返回:检查终端代理变量、本地回调地址和安全软件是否拦截了命令行进程。
提示凭据无效:确认使用的是当前版本支持的认证方式,并检查环境变量名称是否拼写正确。
请求频繁失败:先停止重复登录,查看日志和服务端返回信息,避免短时间内反复刷新造成额外限制。

建议:把 API 密钥放在操作系统的用户级环境变量或受保护的凭据管理器中,不要直接写入项目代码、Shell 历史记录、批处理文件或公开的配置截图。

为 Gemini CLI 检查分流规则与代理组

代理已经打开,终端变量也已设置,仍然可能出现“能登录但模型请求失败”的情况,原因往往是规则没有把实际 API 域名交给正确的代理组。Clash 的规则从上到下匹配,越靠前的规则优先级越高。若某条通用的 GEOIP,CN,DIRECT、DOMAIN-SUFFIX,googleapis.com,DIRECT 或自定义直连规则排在前面,请求就可能绕过代理。

不要盲目复制一整套规则到订阅配置中。先在 Clash Verge 日志或连接页面确认 Gemini CLI 实际访问的域名,再检查该域名命中了哪条规则。常见相关域名可能包括 Google API、认证或账号服务,但具体域名会因 CLI 版本、登录方式和功能模块变化而不同。只根据实际日志添加规则,比凭猜测维护一长串域名更可靠。

启动 Gemini CLI,执行一次不会泄露敏感内容的基础命令,让客户端产生真实连接记录。
在 Clash Verge 的连接或日志页面筛选刚刚出现的域名,记录目标地址、端口、规则和代理组。
确认目标请求使用的是可用代理组,而不是误命中直连、拒绝或不存在的策略组。
如果规则命中顺序不符合预期,调整自定义规则位置,并在修改后重新加载配置。
重新执行命令,确认同一请求的规则结果和节点选择已经稳定。

对于只希望 Gemini CLI 走代理、其他国内站点保持直连的场景,可以采用“按域名分流”的方式;对于需要多个命令行工具共同访问外部服务的开发环境,则可以使用全局代理组进行短时间验证。验证完成后恢复规则模式,避免下载依赖、访问公司内网或本地服务时被不必要地转发。

TUN 模式、DNS 与常见故障排查

如果 Gemini CLI 或其子进程完全不读取代理环境变量,可以在 Clash Verge 中尝试开启 TUN 模式。TUN 会创建虚拟网络接口,把更多系统流量交给 mihomo 内核处理,因此比单纯的系统代理覆盖范围更大。Windows 通常需要管理员权限,macOS 可能需要批准网络扩展;开启前应关闭其他 VPN、虚拟网卡工具和重复的流量接管软件。

TUN 模式开启后,还要检查 DNS 设置。Fake-IP 模式会为域名分配本地映射地址,便于内核在规则匹配时保留域名信息,但某些本地开发服务、企业 VPN 或依赖真实 IP 的程序可能出现兼容性问题。若只有本地服务无法访问,优先检查 fake-ip-filter、局域网规则和虚拟网卡路由,不要直接把整个 DNS 模式改掉。

现象	优先检查	处理方向
命令提示连接被拒绝	Clash 是否运行、端口是否正确	核对监听协议与端口,重新设置变量
浏览器可用,CLI 超时	CLI 是否读取环境变量	在同一终端重新导出变量并查看日志
登录成功,模型请求失败	API 域名的规则和代理组	按连接日志调整域名分流
TUN 开启后内网异常	路由、Fake-IP 网段和 VPN 冲突	关闭冲突软件或加入局域网例外
偶尔成功、频繁超时	节点稳定性、丢包和高峰拥塞	更换节点并在不同时间段复测

排查时建议一次只改一个变量。先固定节点,再确认端口,然后检查终端变量和规则命中,最后才调整 TUN 或 DNS。一次同时切换节点、配置文件和代理模式,即使问题消失也很难知道真正起作用的是哪一步。

建立适合开发工作的稳定使用流程

Gemini CLI 适合融入终端开发流程,但稳定性不只取决于节点延迟。建议把 Clash Verge 配置、终端环境和项目凭据分开管理。日常工作时使用一个专用代理配置或代理组,不要频繁手动编辑订阅原文件,以免下一次更新时覆盖修改。需要自定义规则时,优先使用客户端支持的覆写或扩展配置功能,并保留一份可恢复的备份。

可以为不同场景准备两套清晰的运行方式:普通开发使用规则模式和按需环境变量,需要排查某个工具是否支持代理时临时开启 TUN。每次切换后都执行一次简单的连通性测试,并在日志里确认请求路径。这样能避免“客户端显示已连接,但实际命令走直连”的错觉。

启动工作前确认 Clash Verge 内核运行、配置已加载、代理组有可用节点。
检查当前终端是否存在旧的 HTTP_PROXY 或 HTTPS_PROXY 值,防止它们指向已经关闭的端口。
认证凭据只保存在本地安全位置,项目目录中使用环境变量引用,不要提交到版本控制系统。
遇到失败先看终端错误和 Clash 日志,区分 DNS、连接、认证、规则和服务端响应问题。
完成开发后关闭临时全局代理,避免其他命令误用代理或访问本地网络异常。

按照“客户端可用、端口明确、终端可测、规则可见、凭据安全”的顺序配置,Gemini CLI 与 Clash Verge 的组合通常不需要复杂改动。真正重要的是确认每一层都在工作,而不是只看到面板上的“已连接”状态。