如何在企业网络中为Cursor和Claude Code设置HTTPS_PROXY

如果您的公司通过企业代理关闭了外发流量，像 Cursor 和 Claude Code 这样的 AI 助手 就会停止响应：自动补全卡住，CLI 输出 ETIMEDOUT 或 SSL certificate problem。 我们将讨论如何正确设置环境变量 HTTPS_PROXY， 配置身份验证并避免常见错误，这些错误使开发人员花费数小时调试网络设置而不是代码。

为什么 AI 助手在企业网络中需要代理

Cursor 和 Claude Code 不是本地模型。它们不断访问外部 API：Cursor 连接到其 代码索引服务器和模型 API（根据所选提供商，可能是 OpenAI、Anthropic、Google），而 Claude Code — 直接通过 HTTPS 连接到 Anthropic API。在企业网络中，直接访问互联网通常被防火墙阻止， 所有外发流量必须通过代理服务器（如 Squid、Zscaler、Blue Coat、Fortinet FortiProxy 或内部 企业网关）。如果没有正确设置的环境变量，应用程序根本不知道流量需要通过代理转发， 而是尝试直接连接互联网 — 从而导致超时。

另一个复杂性在于，Cursor 基于 Electron（本质上是 Chromium + Node.js），而 Claude Code 是 Node.js CLI 应用程序。每个应用程序都有自己的代理设置读取逻辑：Electron 部分继承系统的 操作系统设置，而 Node.js 进程直接读取环境变量 HTTP_PROXY/HTTPS_PROXY 或通过类似 undici 和 node-fetch 的库。 这就造成了混淆：设置已定义，但工具却“看不见”它们。

HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 变量：如何工作

为控制台 Node.js、Python 和 Go 应用程序指定代理的经典方法是通过环境变量。 HTTP_PROXY 和 HTTPS_PROXY 之间的区别是根本性的：前者用于 HTTP 协议的请求， 后者用于 HTTPS 请求（几乎所有 AI 助手的流量都是通过 HTTPS）。即使实际流量仅为 HTTPS， 也应该同时指定这两个变量 — 一些库在启动时会发出服务性 HTTP 请求。

export HTTP_PROXY="http://proxy.company.local:8080"
export HTTPS_PROXY="http://proxy.company.local:8080"
export NO_PROXY="localhost,127.0.0.1,.company.local"

请注意：即使是 HTTPS 流量，代理地址中的方案也应指定为 http://， 而不是 https:// — 这是代理服务器的地址，而不是目标资源的地址。通过 HTTP 连接到代理是正常的，加密 仍然通过 CONNECT 隧道机制在最终服务器上工作。

变量 NO_PROXY 是必需的， 以排除公司内部地址的代理 — 否则对内部 git 仓库、Jira 或本地开发服务的请求也会通过外部代理进行， 可能找不到或变慢。一个重要的细节是：某些库对变量的大小写敏感。为了可靠性，请同时指定这两种情况 — 大写和小写字母：

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

为 Cursor 配置代理

Cursor 部分使用操作系统的系统代理设置（尤其是在 macOS 和 Windows 上），但为了在企业网络中稳定工作， 最好通过环境变量明确设置，并在必要时通过应用程序的配置文件进行设置。

在 macOS 和 Linux 上，最简单的方法是将变量导出到 shell 配置文件中，以便在每次启动终端时都能加载，从而启动 Cursor：

# ~/.zshrc 或 ~/.bash_profile
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,*.company.local"

修改配置文件后，执行 source ~/.zshrc 并完全重启 Cursor（不要只是最小化窗口 — 通过活动监视器或任务管理器终止进程，因为 Electron 应用在启动时会缓存环境）。

在 Windows 上，更方便通过系统环境设置（控制面板 → 系统 → 高级系统设置 → 环境变量）或通过 PowerShell 进行永久保存：

[System.Environment]::SetEnvironmentVariable('HTTPS_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('HTTP_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('NO_PROXY','localhost,127.0.0.1','User')

如果之后 Cursor 仍然无法连接到模型 API，请检查应用程序内部的代理设置：设置 → 网络（或常规） — 可能会有单独的代理 URL 字段，覆盖 系统变量。在某些版本的 Cursor 中，还需要明确启用“使用系统代理设置”选项。

为 Claude Code 配置代理

Claude Code 是一个基于 Node.js 的 CLI 工具，通过 npm/npx 启动，因此它直接从调用它的终端会话中读取环境变量。 这简化了配置：只需在启动前导出变量即可。

export HTTPS_PROXY="http://user:[email protected]:8080"
export HTTP_PROXY="http://user:[email protected]:8080"
claude

如果您将 Claude Code 作为 CI 管道的一部分或从脚本中运行，请在启动命令中明确传递变量， 以避免依赖于全局 shell 环境：

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "检查项目中的测试"

对于永久配置，更方便在项目根目录中的 .env 文件中固定变量，并通过 direnv 或内置的 dotenv 支持加载它，如果您的 shell 支持的话。这在不同项目需要 不同代理设置时尤其方便（例如，一个项目使用内部 API，而另一个项目使用外部服务）。

在企业代理上的身份验证

大多数企业代理要求身份验证 — Basic Auth、Digest 或 NTLM。对于 Basic Auth，用户名 和密码可以直接嵌入到代理 URL 中，如上所示： http://user:[email protected]:8080。 一个重要的细节是 — 如果密码中包含特殊字符（@、#、%）， 需要进行 URL 编码，否则代理字符串解析器会在用户名和主机之间出错。

# 如果密码是 P@ssw0rd#2024，编码特殊字符：
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

NTLM 身份验证更复杂（通常与 Microsoft ISA Server、Forefront TMG 或 Fortinet 一起使用） — Node.js 和大多数 HTTP 客户端默认不支持 NTLM。在这种情况下，标准解决方案是 启动一个本地代理中介，它负责 NTLM 握手，然后将“干净”的 HTTP 代理提供给应用程序。为此，通常使用 cntlm 或 px（基于 Python 的本地 NTLM 代理）。 方案很简单：Cursor/Claude Code → localhost:3128 (cntlm) → 企业 NTLM 代理 → 互联网。

# cntlm 的配置示例 (/etc/cntlm.conf)
Username    your_login
Domain      COMPANY
Password    ваш_пароль_или_хеш
Proxy       proxy.company.local:8080
Listen      3128

# 启动 cntlm 后，指定本地地址：
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

证书和 MITM：企业网络中的 SSL 问题

如果公司部署了 Zscaler、Netskope 或任何其他具有 SSL 检查的 Web 过滤器， 流量会在代理上被解密并由企业根 CA 证书签名。Node.js（因此也包括 Claude Code 和大部分内部模块 Cursor） 默认只信任其内置的根证书集合，并会抛出错误 UNABLE_TO_VERIFY_LEAF_SIGNATURE 或 self signed certificate in certificate chain。

解决方案是导出企业 CA 证书（通常可以从 IT 部门获取或从浏览器的证书存储中导出） 并通过变量 NODE_EXTRA_CA_CERTS 指定 Node.js 的路径：

export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-root-ca.pem"

强烈不建议通过 NODE_TLS_REJECT_UNAUTHORIZED=0 全局禁用证书验证 — 这会消除整个进程的 MITM 攻击保护，包括合法连接。仅在一次性诊断时使用此标志，并确保将保护恢复。

常见错误及其解决方案

错误	原因	解决方案
ETIMEDOUT / ECONNREFUSED	代理变量未在应用程序运行的会话中导出	检查 echo $HTTPS_PROXY 在同一终端中，完全重启应用程序
407 Proxy Authentication Required	未指定或过期的用户名/密码	更新代理字符串中的凭据，URL 编码密码中的特殊字符
self signed certificate in certificate chain	企业 MITM 代理替换了证书	指定 NODE_EXTRA_CA_CERTS 与企业根 CA
代理在终端中工作，但在 Cursor 中不工作	Cursor 不是从正确的终端启动或通过没有环境的快捷方式启动	从终端以导出变量的命令启动 Cursor，或者在系统中全局定义变量
NTLM authentication failed	客户端不支持 NTLM 握手	在应用程序和企业代理之间启动中介代理 cntlm 或 px

通过 curl 检查连接

在弄清楚为什么 Cursor 或 Claude Code 不工作之前，请确保代理本身是可用的 并且正确代理 HTTPS 流量。为此，请使用 curl — 它读取相同的环境变量，并且 可以快速定位问题，而无需启动重型应用程序。

# 检查代理和身份验证的可用性
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# 考虑企业证书的检查
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

如果 curl 成功获得响应（即使是 401 或 403 — 这也是正常的，意味着 TLS 握手成功），而 Claude Code 仍然无法连接 — 问题不在网络，而在于进程无法看到环境变量。如果 curl 也因证书错误或超时而失败 — 问题出在网络或代理层面，工具无能为力。

何时需要外部代理而不是企业代理

有时任务不仅限于从企业网络外部访问。开发人员在测试与地理相关的 API 集成时， 检查来自不同国家的服务行为或调试提供商模型的速率限制策略时，发现企业代理为所有请求提供相同的企业 IP。 在这种情况下，方便将测试流量通过外部代理与主要工作环境并行。

对于稳定的长期测试会话，风险最小的 IP 阻塞，适合使用 住宅代理 — 它们使用 真实的家庭提供商 IP 地址，看起来像普通用户流量，这在检查 地理特定 API 响应时非常重要。如果需要重现移动客户端的行为或测试对网络类型敏感的场景，值得考虑 移动代理。 而对于对公共 API 进行大规模并行请求的测试，其中速度和流量成本比伪装成普通用户更重要，通常只需使用 数据中心代理。

重要的是：这样的外部代理通过变量 HTTPS_PROXY/HTTP_PROXY 进行设置， 但用于测试环境或单独的终端配置文件，以免与通过企业网关的主要工作流量混合。如果企业政策要求所有公司的流量仅通过 内部代理，使用外部代理必须与 IT/Security 协商 — 许多公司明确禁止在未获许可的情况下绕过企业网关。

设置检查清单

结论

大多数与 Cursor 和 Claude Code 在企业代理后相关的问题归结为三件事：环境变量 没有传递到进程，身份验证设置不正确，或者企业 MITM 证书未添加到 受信任的列表中。按顺序检查这三项 — 通过 curl， 而不是直接通过应用程序 — 您可以节省数小时的调试时间并快速定位原因。

如果任务超出了企业网络的范围，并且您需要测试来自不同区域或不同类型 IP 的 API 行为，建议尝试 住宅代理 — 它们提供比普通数据中心地址更稳定且对外部服务不那么可疑的流量。