当前位置：首页 > news >正文

macOS 笔记本下 Gemini CLI 客户端网络连接问题诊断与解决方案

news 2025/7/12 6:16:27

前言

近期在使用 Google Gemini CLI 客户端时，部分 macOS 用户可能会遇到网络连接问题，表现为命令行操作超时 (ETIMEDOUT) 或网络请求失败 (TypeError: fetch failed sending request)。特别是当用户处于受限网络环境（如公司/学校网络）或使用了 VPN/代理时，这类问题尤为突出。

本文将详细记录一个典型的诊断过程，并提供最终有效的解决方案，希望能帮助遇到类似问题的用户。

问题描述

最初遇到的错误信息包括：

Error flushing log events: AggregateError [ETIMEDOUT]
[API Error: exception TypeError: fetch failed sending request]

这些错误反复出现，导致 Gemini CLI 无法正常工作。

诊断过程

为了深入了解问题，我们进行了一系列诊断：

基础网络连通性测试：
- ping 216.239.36.223 (Gemini API 常见 IP)： 结果显示 100.0% packet loss，所有请求超时。
- traceroute 216.239.36.223： 结果显示数据包在离开本地网络后 (192.168.x.x 地址后) 就无法继续，全部显示为 * * *。
- 结论： 您的设备无法直接连接到 Google 的 API 服务器。数据包在网络中间被阻塞了。
DNS 解析测试：
- nslookup generativelanguage.googleapis.com： 结果成功解析出多个 Google IP 地址 (例如 142.250.x.x)。
- 结论： DNS 解析本身没有问题，排除了域名解析失败的可能。
系统防火墙检查：
- 确认 macOS 防火墙状态： 发现防火墙是关闭的。
- 结论： 本地防火墙不是导致连接问题的直接原因。
curl 测试与代理情况：
- 电脑设置了 VPN 代理，且为 SOCKS5 协议。尝试设置 export ALL_PROXY="socks5://127.0.0.1:1080" 后，正常访问curl -I https://gemini.google.com： 返回 HTTP/2 200 OK。
- 结论： 外部网络是通畅的，且 SOCKS5 代理可以工作。问题在于 Gemini CLI 没有正确使用这个 SOCKS5 代理。
proxychains-ng 尝试与抓包验证：
- 尝试使用 proxychains4 gemini hello： proxychains-ng 报告配置文件已加载，但 Gemini CLI 仍然报错。
- 进行网络抓包 (例如使用 Wireshark)： 抓包结果显示，Gemini CLI 仍然直接向目标 IP 216.239.36.223 发送 TCP 连接请求 (SYN 包)，而不是将其流量重定向到本地的 SOCKS5 代理地址 127.0.0.1:1080。并且这些连接请求持续重传，没有收到响应。
- 结论： proxychains-ng 未能成功劫持 Gemini CLI 的网络流量。这可能是因为 Gemini CLI 底层使用了某些 proxychains-ng 无法有效拦截的网络库或系统调用。

问题根本原因

综合诊断结果，根本原因是：

Gemini CLI 客户端在 macOS 环境下，无法自动识别和使用通过环境变量（如 ALL_PROXY）配置的 SOCKS5 代理。同时，像 proxychains-ng 这样的通用流量劫持工具也未能成功强制其流量通过 SOCKS5 代理。因此，CLI 客户端的网络请求绕过了代理，直接发向了被防火墙（或网络限制）阻断的 Google API 服务器，导致连接超时和请求失败。

最终解决方案：使用 `privoxy` 转换 SOCKS5 代理为 HTTP 代理

鉴于 Gemini CLI 无法直接使用 SOCKS5 代理，我们采取了一种“曲线救国”的方法：利用 privoxy 将本地的 SOCKS5 代理（由 VPN 提供）转换为标准的 HTTP/HTTPS 代理，然后通过 HTTPS_PROXY 环境变量让 Gemini CLI 使用这个 HTTP 代理。

privoxy 是一个无缓存的 Web 代理，具有高级过滤功能，但在这里我们主要利用它作为代理协议转换器。

步骤详解

安装 privoxy： 打开终端，使用 Homebrew (macOS 上的包管理器) 安装 privoxy。
Bash
```
brew install privoxy
```
编辑 privoxy 配置文件： 打开 privoxy 的配置文件进行编辑。
Bash
```
sudo nano /usr/local/etc/privoxy/config # 或使用您熟悉的文本编辑器，如 vim
```
- 确认监听地址： 确保 privoxy 监听在本地的某个端口。通常，您会看到类似下面这行（如果前面有 #，请去掉）：
  代码段
```
listen-address 127.0.0.1:8118
```
  8118 是 privoxy 默认监听的 HTTP 代理端口。您可以保持默认或更改为其他未被占用的端口。
- 添加 SOCKS5 转发规则： 在文件的任何位置（推荐在 forward- 规则集附近）添加以下一行，将所有请求转发到您的 SOCKS5 代理：
  代码段
```
forward-socks5 / 127.0.0.1:1080 .
```
  - forward-socks5： 指示 privoxy 使用 SOCKS5 协议将请求转发到指定的代理。
  - /： 表示此规则适用于所有 URL 路径。
  - 127.0.0.1:1080： 这是您的 VPN 客户端在本地提供的 SOCKS5 代理的实际地址和端口。 请务必根据您的 VPN 配置进行核对和替换。
  - .： 必需的，表示匹配所有目的地。
- 保存并关闭文件（Nano 编辑器：Ctrl+X, Y, Enter）。
启动 privoxy 服务： 使用 Homebrew 启动 privoxy 服务。
Bash
```
brew services start privoxy
```
您可以通过以下命令确认 privoxy 是否正在运行并监听端口：
Bash
```
lsof -i :8118 # 替换为 privoxy 实际监听的端口
```
设置 HTTPS_PROXY 环境变量： 在您运行 Gemini CLI 的终端会话中，设置 HTTPS_PROXY 和 HTTP_PROXY 环境变量，指向 privoxy 监听的 HTTP 代理地址和端口。
Bash
```
export HTTPS_PROXY="http://127.0.0.1:8118" # 记住这里是 http:// 而不是 https://
export HTTP_PROXY="http://127.0.0.1:8118"  # 强烈建议也设置 HTTP_PROXY
```
- 重要提示： 即使是 HTTPS 流量，这里连接 privoxy 时依然是 HTTP 协议，所以前缀是 http://。
运行 Gemini CLI： 现在，尝试运行您的 Gemini CLI 命令：
Bash
```
gemini hello
```
如果一切配置正确，Gemini CLI 应该能够正常工作了。