教程 2026年7月19日 · 约 14 分钟阅读

Gemini CLI 国内怎么用？Clash 访问配置指南

Gemini CLI 热度上升后，许多用户在安装和调用时会遇到 API 连接失败、终端不走代理或请求超时。本文从网络检查开始，使用 Clash Verge 演示订阅导入、代理模式与分流规则设置，让没有 Clash 使用经验的读者也能完成基础配置。

Gemini CLI 为什么需要单独配置代理

Gemini CLI 是运行在终端中的 AI 命令行工具。它与普通网页应用不同，用户输入提示词后，程序会在后台访问模型服务、身份验证服务以及其他 API 地址。浏览器能够打开网页，并不代表终端里的 Gemini CLI 一定可以完成同样的请求。最常见的情况是浏览器读取了系统代理，而命令行程序只按照自己的网络库和环境变量建立连接。

在国内网络环境下，Gemini CLI 可能出现登录页面无法打开、授权回调失败、模型列表加载不出来、请求一直停留在等待状态等现象。还有一种容易误判的情况：Clash Verge 的连接数量在增加，但终端仍提示 fetch failed 或 ETIMEDOUT。这说明流量未必真正走到了可用节点，也可能只是 DNS 请求、认证域名或某个子进程没有使用代理。

因此，配置 Gemini CLI 的思路不是简单地打开 Clash，而是依次确认三条链路：Clash 本身能够连接节点，目标域名能够匹配正确规则，当前终端进程能够读取代理设置。只要其中一环缺失，就可能表现为「Clash 正常但 Gemini CLI 不可用」。

开始前准备：客户端、订阅与端口

配置清单

  • Clash 客户端：本文以 Clash Verge 或兼容 Mihomo 内核的桌面客户端为例。
  • 有效订阅链接：需要从代理服务商后台复制 Clash、Clash Meta 或 Mihomo 格式订阅。
  • 终端环境：Windows PowerShell、macOS Terminal、Linux Shell 均可，命令写法会略有不同。
  • 可用节点：至少准备一个能够访问 Gemini 相关服务的节点，不要只根据节点名称判断可用性。

Clash 本身不提供代理节点，订阅链接也不等于客户端。订阅负责提供节点、策略组和规则，Clash Verge 负责加载这些内容并启动本地代理端口。常见端口包括 HTTP 端口、SOCKS 端口和混合端口，实际数值必须以客户端当前显示为准。许多配置默认使用 7890，但不同版本、不同订阅模板可能使用其他端口。

还要确认电脑日期和时间准确。HTTPS 证书、OAuth 授权和 API 请求都依赖正确的系统时间，如果时间相差较大，终端可能出现证书无效、令牌过期或连接被重置等错误。首次排查时，建议关闭其他 VPN、网络加速器和代理软件，避免多个虚拟网卡或多个本地端口相互干扰。

第一步：在 Clash Verge 中导入订阅

安装并启动 Clash Verge 后，先不要急着运行 Gemini CLI。打开客户端的配置或 Profiles 页面，找到添加订阅的输入框，将代理服务商提供的订阅 URL 粘贴进去。订阅链接通常以 https:// 开头，可能包含较长的参数字符串，复制时不要带上前后空格或聊天软件自动添加的标点。

  1. 打开 Clash Verge，进入配置或Profiles页面。
  2. 将完整订阅链接粘贴到订阅地址输入框，点击下载、导入或更新按钮。
  3. 等待配置文件下载完成，确认列表中出现节点数量和配置名称。
  4. 点击刚刚导入的配置，使它成为当前正在使用的配置。
  5. 进入代理页面，确认策略组中至少出现一个节点，而不是只有空的自动选择组。

如果下载订阅时提示连接失败，问题发生在 Gemini CLI 之前，优先检查当前网络能否打开订阅域名。可以把订阅地址临时粘贴到浏览器中测试，但不要把包含个人授权信息的完整 URL 发布到公共平台。若浏览器也无法访问，可能是订阅服务器在当前网络不可达；若浏览器能下载内容而 Clash 失败，则需要检查客户端证书、订阅格式或内核兼容性。

安全提醒

订阅链接通常包含账户识别信息，泄露后他人可能消耗你的流量或获取节点。不要将完整订阅链接放进截图、公开仓库、论坛帖子或命令历史中；如果已经泄露，请立即在服务商后台重置订阅。

第二步：选择节点并设置代理模式

导入配置后，进入 Clash Verge 的代理页面。策略组通常包含自动选择、故障转移、地区节点或手动选择等项目。初次配置不必追求最复杂的策略，先选择一个延迟较低、状态稳定的节点，再使用规则模式进行测试。延迟测试只能说明测速请求能够完成，不能完全代表 Gemini API 一定可用，因此最终仍要以实际请求和日志为准。

  • 规则模式 Rule：根据配置文件中的域名和 IP 规则分流，国内网站通常直连，海外服务按规则走代理，适合日常使用。
  • 全局模式 Global：大多数流量都交给当前代理节点，适合短时间判断是否为规则匹配问题，但不建议长期使用。
  • 直连模式 Direct：关闭代理转发，只适合访问国内资源或检查本地网络，不能用来验证 Gemini CLI 的代理链路。

建议先使用规则模式。如果 Gemini CLI 仍然失败，再临时切换到全局模式进行对照。全局模式下成功、规则模式下失败，通常表示 Gemini 相关域名没有被规则正确识别，或者配置文件的规则集过旧。全局模式下仍然失败，则更应该检查节点质量、终端变量、端口和 DNS，而不是立即修改大量 YAML 内容。

实操建议

排错时一次只改一个变量。先固定节点，再比较 Rule 和 Global；先确认浏览器访问，再确认终端访问。这样可以避免多个设置同时变化，最后无法判断究竟是哪一项解决了问题。

第三步：开启系统代理并确认端口

Clash Verge 的系统代理开关主要影响遵循操作系统代理设置的应用。打开客户端的常规或 General 页面，启用系统代理，然后查看 HTTP、SOCKS 或混合端口的具体数值。Windows、macOS 和 Linux 的界面名称可能不同，但核心信息都是本地监听地址和端口，例如 127.0.0.1:7890。

这里要区分「允许局域网连接」和「系统代理」。允许局域网连接只是让其他设备访问本机代理端口，并不会自动让当前电脑的 Gemini CLI 走代理；系统代理则是修改操作系统的代理设置，但也不能保证所有终端程序都会读取它。Gemini CLI 是否使用代理，最终要看它所使用的运行时和启动环境。

检查项目 正常表现 异常时的方向
系统代理 浏览器或系统网络设置显示本地代理已启用 检查 Clash Verge 是否有权限修改系统代理
监听端口 Clash 页面显示 HTTP、SOCKS 或混合端口正在监听 检查端口冲突、客户端是否真正启动内核
代理模式 Rule 或 Global 模式下存在可用节点 切换节点并查看连接日志是否产生请求
连接日志 运行测试命令时出现目标域名和代理策略 终端可能没有使用系统代理或环境变量

第四步：让 Gemini CLI 使用终端代理

这是最容易被忽略的一步。终端程序通常不会像浏览器那样完整读取系统代理，因此建议显式设置环境变量。HTTP 代理变量一般适用于 HTTP 和 HTTPS 请求；SOCKS 变量是否被当前运行时支持，则取决于程序和依赖库。为了提高兼容性，可以优先使用 Clash Verge 的混合端口，并同时设置 HTTP_PROXY、HTTPS_PROXY 和小写形式。

在 macOS 或 Linux 的当前 Shell 中，可以使用类似下面的命令。端口请替换成 Clash Verge 页面实际显示的值： 

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"

在 Windows PowerShell 中，对应写法如下： 

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7891"
$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY

这些变量通常只对当前终端窗口和从该窗口启动的子进程有效。关闭窗口后，设置可能消失，这是比较安全的默认行为，也方便你在不同项目之间切换网络环境。不要把代理账号、订阅链接或带认证信息的代理 URL 直接写入公共脚本。如果端口使用的是混合端口，HTTP 形式往往比直接使用 SOCKS 更容易被 Node.js 生态中的工具识别。

终端验证顺序

  1. 在当前终端打印环境变量，确认值不是空字符串，也没有多余引号或中文空格。
  2. 使用一个简单的 HTTPS 请求测试代理，观察 Clash 日志是否出现对应域名。
  3. 确认测试请求完成后，再启动 Gemini CLI，避免把多个问题混在一起。
  4. 如果程序使用独立的 Node.js、Python 或容器环境，检查该环境是否继承当前 Shell 的变量。

第五步：检查 Gemini 相关域名的分流规则

Gemini CLI 的请求可能不只访问一个域名。登录、身份验证、模型 API、静态资源和遥测请求有时属于不同服务，规则只覆盖其中一个域名时，仍然可能出现登录成功但调用失败的情况。打开 Clash Verge 的连接面板，在启动 Gemini CLI 并执行请求的同时观察目标域名、匹配规则和最终策略。

如果连接日志中显示目标域名匹配了 DIRECT，而当前网络无法直连该服务，就需要检查配置文件的规则顺序或规则集更新状态。Clash 通常按照规则从上到下匹配，越具体的域名规则应该放在更宽泛的规则之前。最后的 MATCH 只能作为兜底规则，不能把它放在具体规则前面，否则后面的条目不会有机会生效。

  • 确认当前配置不是空配置，也不是导入后没有被选中的旧配置。
  • 检查规则集是否成功下载，部分订阅更新失败时会保留旧规则。
  • 对照连接日志中的实际域名，不要只根据软件名称猜测规则名称。
  • 排错时可临时使用 Global 模式，如果 Global 成功，再回头修复 Rule 模式。

不建议为了追求「全部代理」而长期删除规则或把所有流量交给海外节点。这样会增加国内网站延迟、消耗流量，也会让问题更加难以定位。更合理的做法是先用全局模式确认节点可用，再在规则模式下根据日志补充必要的域名规则。对于由订阅提供商维护的规则集，优先使用其更新机制，不要随意覆盖整个配置文件。

DNS、证书与请求超时排查

DNS 问题经常被误认为节点问题。终端首先需要解析目标域名，如果解析请求没有经过 Clash，或者本地 DNS 返回了不可用地址，后续代理连接自然无法建立。浏览器可能通过自己的 DoH 工作正常，但 Gemini CLI 使用系统解析，于是两个应用表现不一致。排查时可以暂时关闭浏览器的安全 DNS，并观察 Clash 日志中是否出现 DNS 查询和连接记录。

如果终端提示证书错误，先检查电脑时间、系统证书和运行时版本，不要直接关闭 TLS 验证。忽略证书校验会降低安全性，尤其不适合长期使用，也无法解决真正的节点或规则问题。若错误只发生在某个旧版 Node.js 环境，优先升级运行时和 Gemini CLI，再重新测试。

不要混淆两种超时

连接超时通常发生在无法建立 TCP 或 TLS 连接时，重点检查节点、端口、DNS 和代理变量；API 响应超时则可能与节点拥堵、请求内容过大或服务端限流有关。先看 Clash 日志中的连接状态，再判断应该更换节点还是调整应用参数。

当连接日志完全没有出现 Gemini 相关请求时，优先检查终端代理变量和进程继承关系；当日志显示请求但策略为直连时，检查规则；当日志显示请求经过代理却反复失败时，切换节点并测试其他网络。这样的分层排查比反复重装客户端更有效，也能保留后续诊断所需的信息。

常见报错与处理方法

提示 fetch failed 或 network error

这类错误通常只说明底层网络请求没有成功，并不能单独判断原因。先确认 Clash Verge 中是否出现对应连接，再检查当前 Shell 是否设置了大写和小写代理变量。若连接日志没有目标域名，说明请求可能绕过了 Clash；若有域名但显示超时，则切换节点、检查规则和 DNS。

登录或授权回调无法完成

登录过程可能需要浏览器和终端同时参与。浏览器打开授权页并不表示回调到本地终端的过程没有问题。检查默认浏览器、系统时间、终端是否保持运行，以及 Clash 是否错误代理了本地回调地址。对于本机地址和局域网地址，通常应保持直连，避免把 localhost 或 127.0.0.1 发送到远程节点。

模型列表为空或 API 返回拒绝

如果网络连接成功但服务端仍返回拒绝，原因可能是账户权限、地区限制、API 密钥、项目配置或客户端版本，而不是 Clash。此时查看完整错误正文和 HTTP 状态码，确认使用的是正确账户和合法凭据。不要在日志、截图或公共 issue 中暴露 API Key；可先撤销旧密钥，再创建权限范围更小的新密钥。

稳定使用 Gemini CLI 的建议

配置完成后，建议把「节点选择」「规则更新」「终端变量」固定下来。不要每次遇到一次错误就更换客户端和配置，因为这样会同时引入新的变量。可以建立一个简单的测试流程：先确认 Clash 核心运行，再测试一个普通 HTTPS 请求，然后检查 Gemini 目标域名的日志，最后运行实际命令。每一步都记录结果，之后遇到相同问题时可以快速定位。

  • 定期更新订阅：节点和规则会变化，更新后重新确认当前配置已被选中。
  • 保留可用节点：不要只依赖单个节点，至少准备一个备用节点用于对照。
  • 按需设置代理：项目脚本可以使用独立启动命令，避免长期污染全局 Shell 环境。
  • 保护凭据：API Key、订阅链接和登录令牌都应放在安全的本地环境中。
  • 遵守服务条款：使用 AI 服务时应遵守所在地法律法规以及服务商的使用政策。

对开发者而言，代理配置最好能够复现。可以在项目文档中只记录端口类型、启动前提和清理方法，不要记录真实订阅地址或密钥。例如写明「启动 Clash Verge，启用系统代理，在当前终端设置 HTTPS_PROXY，然后执行测试命令」，而不是把个人环境变量直接提交到 Git 仓库。这样既方便团队协作，也降低敏感信息泄露风险。

常见问题

为什么浏览器可以访问，Gemini CLI 却连接失败？

浏览器可能读取了系统代理，而 Gemini CLI 所使用的 Node.js 或其他网络库没有自动读取系统设置。请在启动程序的同一个终端中设置 HTTP_PROXY 和 HTTPS_PROXY，然后观察 Clash 日志是否出现请求。如果日志仍然为空，检查是否从图形界面、IDE 或容器中启动了另一个没有继承变量的进程。

应该一直使用 Global 全局模式吗？

不建议。Global 模式适合短时间排查「规则是否误判」，但日常使用 Rule 模式更合理，可以让国内流量直连，降低延迟并减少不必要的代理消耗。确认节点正常后，应回到规则模式，并通过连接日志检查 Gemini 相关请求是否命中正确策略。

如何判断代理端口写对了？

以 Clash Verge 当前页面显示的 HTTP 或混合端口为准，不要照抄其他教程中的数字。代理地址通常是 127.0.0.1，端口可能是 7890、7897 或其他数值。设置后运行测试请求，同时观察 Clash 是否出现连接记录；如果本地端口未监听，终端会立即报连接被拒绝。

如果你还没有完成桌面端安装，可以阅读《Windows Clash 安装与配置教程》；遇到连接成功但无法访问网页的情况，可参考《Clash 连接成功但无法上网的 DNS 排查方法》。如果希望把代理共享给同一局域网中的其他设备，也可以继续阅读《Clash 局域网共享代理配置指南》。

总结

  1. 准备兼容的 Clash Verge 客户端、有效订阅和至少一个可用节点。
  2. 导入订阅并选中当前配置，在代理页面确认节点和策略组正常。
  3. 优先使用规则模式，排错时短暂切换全局模式进行对照。
  4. 确认 HTTP、HTTPS 或混合端口，并在启动 Gemini CLI 的同一终端设置代理变量。
  5. 结合 Clash 连接日志排查规则、DNS、节点、证书和账户权限问题。

与一些只提供简单开关的代理工具相比，终端 AI 工具更需要明确的端口、环境变量和分流反馈；当规则不可见或日志不完整时，用户往往很难判断请求究竟走了哪里。Clash 的优势在于策略组、连接日志、规则匹配和多种代理端口都可以集中管理，既能帮助新手完成基础配置，也方便开发者针对不同项目做精细分流。

如果你希望用一个界面同时管理订阅、节点、规则和系统代理，不妨先从 Clash Verge 开始配置。完成基础设置后，免费下载 Clash，立即体验，再根据自己的终端环境逐步完善代理变量与规则。

让 Gemini CLI 稳定走 Clash 代理

从订阅导入到终端变量设置，快速完成 AI 命令行工具的网络配置。

免费下载 Clash（Windows / macOS）