1. 先判断请求是否已经发出
TypeError: HttpsProxyAgent is not a constructor 与普通的连接超时不同。前者说明 CLI 在构造代理 Agent 时就终止了，服务端可能完全没有收到请求。
| 表现 | 更可能的层级 | 优先动作 |
|---|---|---|
| 启动后立即抛 TypeError | CLI 依赖或打包兼容 | 记录版本并做无代理对照 |
| 等待后 ETIMEDOUT | 代理、DNS 或出口网络 | 用 curl 测试代理端口 |
| 控制台出现 401/429 | 请求已到 API | 转查认证或额度 |
2. 用一次对照实验锁定 HTTP_PROXY
先在新终端记录变量，不要直接修改全局配置。随后仅对当前进程临时清除代理变量，再发送同一个最小请求。
env | grep -i proxy
env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy gemini --prompt "ping"若清除变量后不再出现构造器错误，可以确认触发点在 CLI 的代理代码路径；这不等于代理服务器本身失效。
3. 检查代理协议与大小写变量
HTTP_PROXY、HTTPS_PROXY 以及小写版本可能同时存在。值中的协议描述的是如何连接代理，而不是目标 API 的协议。实际监听 HTTP 的本地代理不要因为目标是 HTTPS 就擅自写成 https://。
export HTTP_PROXY="http://127.0.0.1:PORT"
export HTTPS_PROXY="http://127.0.0.1:PORT"
export NO_PROXY="localhost,127.0.0.1,::1"4. 修复顺序：升级、对照、临时回退
- 记录
gemini --version、Node.js 版本和认证类型。 - 升级到当前稳定版后重复同一测试。
- 若新版本才出现，临时回退到已验证版本并锁定版本号。
- 必须经过代理时，可测试系统级 TUN；它不会触发相同的 Node 代理 Agent 路径。
- 保留代理变量前后的日志，等待客户端修复后再回归。
5. 使用 Gemini API 中转时分层验证
先检查中转控制台是否有对应时间的请求记录。没有记录说明请求尚未到达 Base URL；有记录并返回 HTTP 状态码，才进入 API Key、模型权限、余额和限流排查。
island AI Coding 的统一 Base URL 为 https://www.codex789.com/v1。客户端是否支持自定义地址取决于其协议和版本，OpenAI 兼容地址不能自动等同于 Gemini 原生端点。
6. 修复后的验证清单
- 无代理和有代理各执行一次同样的短请求。
- 确认不再出现 JavaScript TypeError。
- 检查请求是否到达目标 API 或中转控制台。
- 逐步恢复项目上下文和工具调用。
- 记录可用 CLI、Node 与代理组合。
7. 常见问题
更换 API Key 能解决 HttpsProxyAgent 报错吗？
通常不能。该 TypeError 多发生在代理对象初始化阶段，认证请求尚未发出。先验证代理变量和客户端版本。
为什么 curl 通过代理正常，Gemini CLI 仍然崩溃？
curl 与 Gemini CLI 使用不同的 HTTP 实现。代理服务器可用，不代表特定版本的 Node 代理依赖一定能正确加载。
可以永久删除 HTTPS_PROXY 吗？
只有网络允许直连时才适合。必须走代理的环境应升级或回退客户端，或者采用已验证的系统级网络方案。
中转控制台没有请求记录说明什么？
说明故障发生在客户端、代理、DNS 或 Base URL 配置阶段，请求尚未到达中转网关。
* 本文由 island AI Coding 技术团队根据官方文档与公开问题记录原创整理。公开 issue 描述的是特定版本和环境，修复状态可能变化；操作前请记录版本并保留回滚路径。更新时间：2026-09-01。