Gemini CLI 配合 Clash：国内开发者访问配置指南

先明确 Gemini CLI 与 Clash 的分工

Gemini CLI 是运行在终端中的 AI 编程工具，主要用于阅读项目文件、解释代码、生成补丁、执行开发任务以及通过命令行与 Gemini 模型交互。Clash 或 mihomo 则是本地代理转发工具，负责监听代理端口、匹配域名规则，并按照策略组把连接发送到不同的出站节点。两者并不是同一类软件：Gemini CLI 负责发起请求，Clash 负责决定请求如何离开本机。

国内开发者在使用 Gemini CLI 时，常见问题包括登录页面无法打开、模型请求超时、TLS 连接被重置、终端提示网络错误，以及浏览器能够访问但 CLI 仍然失败。这些现象通常不是“节点延迟高”这么简单，而是由客户端没有使用代理、域名规则未命中、终端环境变量未设置，或者认证流程与 API 请求使用了不同网络路径造成的。

选择客户端并导入订阅

在 Windows、macOS 和 Linux 上，可以优先选择仍在维护、采用 mihomo 内核并且能够查看连接日志的 Clash 客户端。FlClash、Clash Verge Rev 等客户端通常提供配置导入、系统代理和 TUN 管理功能；macOS 用户还需要留意网络扩展授权，Windows 用户则要区分系统代理与 TUN 驱动。选择客户端时不要只看软件名称，应在“关于”“内核”或日志页面确认实际运行的核心。

订阅应选择服务提供方明确标注的 Clash、Clash Meta 或 mihomo 格式。订阅链接包含身份令牌，导入前不要把完整 URL 发到群聊、工单截图或公开代码仓库。若同一服务同时提供“通用订阅”“Clash 订阅”和“单节点列表”，Gemini CLI 配合 Clash 时通常应选择完整的 Clash 或 mihomo 配置，因为它需要代理节点、策略组和规则，而不是只有若干分享链接。

1. 打开客户端的配置或 Profiles 页面，选择“从 URL 添加”或类似入口。
2. 粘贴订阅链接，保存后手动执行一次更新。
3. 选中刚导入的配置，并确认 mihomo 内核已经启动。
4. 在代理页面选择一个可用节点，先测试普通 HTTPS 网站。
5. 确认连接日志中能够看到请求，再继续配置 Gemini CLI。

导入成功后，建议先不要立即打开 TUN。对于只需要让终端访问特定服务的场景，系统代理加命令行环境变量更容易控制，也不会改变所有应用的网络路径。只有当某个程序完全不读取代理变量，或者需要接管 DNS 与非 HTTP 流量时，才考虑启用 TUN。

检查端口与运行状态

常见的混合代理端口是 7890，但实际端口必须以当前配置中的 mixed-port 为准。控制端口例如 9090 只用于客户端管理内核，不是给 Gemini CLI 填写的代理端口。一个适合本机使用的基础配置片段如下：

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

allow-lan: false 可以避免代理端口被局域网其他设备直接访问。如果确实需要局域网共享，应同时设置明确的监听地址、防火墙规则和访问控制，不要为了排查方便长期开放到所有网卡。

为 Gemini CLI 设置命令行代理

这是整个配置中最容易被忽略的一步。浏览器使用系统代理，并不意味着终端中的 Node.js、Python、Go 或其他 CLI 程序也会遵循相同设置。Gemini CLI 启动后通常会通过 HTTPS 访问认证服务和模型接口，因此可以先为当前终端设置 HTTP_PROXY 与 HTTPS_PROXY，并同时设置小写变量，以兼容不同依赖库的读取方式。

Windows 终端设置方法

在 PowerShell 中，下面的设置只对当前窗口有效。将端口替换为 Clash 实际监听端口：

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:http_proxy="http://127.0.0.1:7890"
$env:https_proxy="http://127.0.0.1:7890"
$env:NO_PROXY="127.0.0.1,localhost"

如果使用 Windows 命令提示符，可以写成：

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
set http_proxy=http://127.0.0.1:7890
set https_proxy=http://127.0.0.1:7890
set NO_PROXY=127.0.0.1,localhost

macOS 与 Linux 终端设置方法

在 Bash 或 Zsh 中，可先执行以下命令进行临时测试：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export NO_PROXY=127.0.0.1,localhost

确认有效后，再把这些内容加入 ~/.zshrc、~/.bashrc 或其他实际使用的 shell 启动文件。不要把代理变量直接写入所有系统服务的全局环境，尤其是多人使用的开发机。需要取消当前终端代理时，可以执行：

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY

配置完成后，先用一个简单的 HTTPS 请求验证代理链路。测试域名只用于确认网络路径，不代表它一定是 Gemini CLI 的实际接口：

curl -I --connect-timeout 10 --max-time 20 https://example.com

如果 Clash 的连接日志出现对应请求，说明终端至少已经把流量交给本地代理。若命令直接连接超时且日志没有任何记录，应检查环境变量是否在同一个终端窗口中生效、端口是否正确，以及是否有其他工具覆盖了代理设置。

配置规则让请求稳定分流

只设置代理端口还不够。若 Clash 处于 rule 模式，Gemini CLI 请求会按照 rules 从上到下匹配。规则没有覆盖实际使用的认证域名或 API 域名时，请求可能被错误地直连；而规则过于宽泛，又可能让整个终端流量都经过代理，增加延迟和排查难度。

建议先使用服务提供方或维护者提供的官方域名清单，再将这些域名加入专用策略组。不要根据搜索结果随意添加大量第三方域名，也不要把未知域名全部指向代理。下面是结构示例，域名仅用于说明写法，实际规则应以当前服务文档和连接日志为准：

proxy-groups:
  - name: Gemini
    type: select
    proxies:
      - 节点选择
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example-ai.invalid,Gemini
  - DOMAIN-SUFFIX,accounts.example.invalid,Gemini
  - MATCH,DIRECT

在真实配置中，策略组名称必须与现有订阅中的名称完全一致。若订阅已经提供“节点选择”或“国外服务”策略组，可以直接复用，而不要重复创建同名组。规则应放在最终生效配置或客户端覆写文件中，否则下次更新订阅时可能被覆盖。

动手排查的五步流程

1. 确认核心：在客户端日志中确认 mihomo 已启动，并记录混合端口。
2. 确认节点：手动选择一个稳定节点，观察测速结果和持续连接情况，不要只看一次延迟。
3. 确认代理：在同一个终端设置 HTTPS_PROXY，使用 curl 观察 Clash 是否收到请求。
4. 确认规则：查看认证和模型相关域名最终命中的策略组，必要时临时设置为专用代理组。
5. 确认 CLI：重新启动 Gemini CLI，再根据错误发生阶段判断是认证、接口访问还是本地权限问题。

每次只修改一个变量。例如先固定节点，再测试环境变量；不要同时切换节点、打开 TUN、替换 DNS 和改写全部规则。这样即使问题解决，也无法知道真正有效的改动是什么。排查结束后，应恢复不必要的临时规则，并将代理环境变量限制在需要使用 Gemini CLI 的终端或脚本中。

DNS、TUN 与安全边界

DNS 配置会影响规则匹配和连接速度。启用 fake-ip、远程 DNS 或复杂的 nameserver-policy 后，某些开发工具可能出现证书、内网域名或本地服务访问异常。首次配置 Gemini CLI 时，建议先使用客户端默认且稳定的 DNS 方案，确认请求可以完成后再逐步调整。不要为了“加速”同时启用多个实验性 DNS 选项。

TUN 模式适合接管不读取系统代理的软件，但它会改变系统路由和 DNS 行为。开启前应关闭其他 VPN、网络加速器或同类虚拟网卡，避免多个程序争抢默认路由。Windows 可能需要管理员权限或安装驱动；macOS 可能需要批准网络扩展。若仅为 Gemini CLI 配置代理，通常不必一开始就启用 TUN。

API 密钥、OAuth 凭据、订阅令牌和终端历史都属于敏感数据。不要把包含密钥的命令写入公开脚本，不要将完整错误日志直接上传，也不要在共享电脑中长期设置全局代理和认证变量。使用 API 密钥时，优先通过系统环境变量或受权限保护的凭据管理方式提供，并在怀疑泄露后立即撤销和重新生成。

常见问题