AI 专题 使用教程

Claude Code 网络环境配置与代理设置：环境变量、TUN 模式与常见报错

Claude Code 在终端运行，通常不会自动使用系统代理。本文给出 macOS、Linux、Windows PowerShell 的 HTTPS_PROXY 配置方法、TUN 模式方案、WSL 与远程服务器设置，以及连接超时的排查步骤。

首次发布
最后更新
内容类型
使用教程
资料核对
阅读时间
约 5 分钟

信息可能随服务调整而变化，请以最新官方信息为准。

直接答案

Claude Code 运行在终端里，通常不会读取系统代理，所以浏览器能用 Claude 不代表 Claude Code 能连上。解决方法有两种：在终端设置 HTTPS_PROXY / HTTP_PROXY（及 NO_PROXY）环境变量，指向代理客户端的混合端口；或在代理客户端开启 TUN 模式，让所有程序的流量都经过代理。配置后保持节点固定，避免会话中途切换。

Key Takeaways · 要点速览

  • 系统代理通常只对浏览器生效，Claude Code 需要终端级别的代理配置。
  • 环境变量方案灵活、影响范围小；TUN 模式覆盖全部程序，适合同时使用多个命令行工具。
  • 代理地址建议写成 http://127.0.0.1:端口，端口以客户端显示的混合端口为准。
  • WSL2、远程 SSH 服务器、容器中的 127.0.0.1 不是宿主机，需要单独处理。
  • 长时间任务中不要切换节点，会话中断和额外验证多数由此引起。

操作步骤

  1. 确认代理客户端的混合端口

    打开代理客户端设置，找到混合端口（Mixed Port）或 HTTP 端口，记下数值，例如 7897。确认客户端已连接到官方支持地区的节点。

  2. 为终端设置代理环境变量

    macOS / Linux 执行 export HTTPS_PROXY=http://127.0.0.1:7897 与 export HTTP_PROXY=http://127.0.0.1:7897；Windows PowerShell 执行 $env:HTTPS_PROXY="http://127.0.0.1:7897" 与 $env:HTTP_PROXY="http://127.0.0.1:7897"。

  3. 设置 NO_PROXY 排除本地地址

    将 NO_PROXY 设置为 localhost,127.0.0.1，避免本地服务、登录回调等请求被错误地转发到代理。

  4. 验证终端是否已走代理

    在同一个终端窗口执行 curl -I https://api.anthropic.com，能收到 HTTP 响应头即说明网络已通；超时则说明代理未生效或节点不可用。

  5. 启动 Claude Code 并完成登录

    在已设置代理的终端中启动 claude，按提示在浏览器中完成登录授权。安装与登录方式以官方文档为准。

  6. 持久化配置或改用 TUN 模式

    确认可用后，把环境变量写入 shell 配置文件或系统用户变量；如果还有其他命令行工具需要代理，可以改为开启客户端的 TUN 模式。

为什么 Claude Code 需要单独配置代理

直接回答：Claude Code 是一个命令行程序，它发出的请求不经过浏览器，也通常不会读取操作系统的「系统代理」设置。所以常见现象是浏览器里的 Claude 一切正常，终端里却提示连接错误或请求超时。只要让终端的流量进入代理，问题多数就解决了，方法是设置代理环境变量，或者开启代理客户端的 TUN 模式。

两种方案的区别如下：

方案 原理 优点 局限
环境变量 程序读取 HTTPS_PROXY 等变量，主动把请求发给代理 只影响当前终端，容易排查 每个终端或 shell 都要生效；不读取变量的程序无效
TUN 模式 客户端创建虚拟网卡，在网络层接管流量 覆盖所有程序，无需逐个配置 需要管理员权限；与其他 VPN 类软件可能冲突

本文适用于 macOS、Linux 与 Windows。Claude Code 的安装方式以官方文档为准，这里只讨论网络部分。

准备工作

  1. 代理客户端已正常连接，并选中位于 Anthropic 官方支持地区的节点。中国大陆与中国香港不在官方支持列表中，地区判断以官方支持地区列表为准。
  2. 找到混合端口。在客户端设置中查看「混合端口」或「HTTP 端口」，以客户端显示的为准，例如 7897。下文均以 http://127.0.0.1:7897 举例，请替换为你自己的端口。
  3. 浏览器能正常打开 Claude，用于确认节点本身可用。

方法一：设置代理环境变量

macOS / Linux

在当前终端中临时生效：

export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897
export NO_PROXY=localhost,127.0.0.1

部分程序只认小写变量名，可以同时设置一份小写版本（https_proxy、http_proxy、no_proxy）。

想让每个新终端自动生效，把上面几行追加到 shell 配置文件中：macOS 默认 shell 是 zsh，对应 ~/.zshrc；bash 用户对应 ~/.bashrc。保存后执行 source ~/.zshrc 或重新打开终端。

Windows PowerShell

当前窗口临时生效：

$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:NO_PROXY="localhost,127.0.0.1"

需要长期生效时，可以写入当前用户的环境变量，之后新开的终端都会继承：

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:7897", "User")
[Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://127.0.0.1:7897", "User")

如果使用的是 CMD，对应写法是 set HTTPS_PROXY=http://127.0.0.1:7897。

提示Claude Code 也支持在其配置文件的 env 字段中声明环境变量，适合只想让 Claude Code 走代理、不影响其他程序的情况。具体字段与文件位置以官方文档为准。

关于 NO_PROXY

NO_PROXY 列出不经过代理的地址。至少保留 localhost 与 127.0.0.1，避免本地开发服务、登录回调等请求被转发到代理导致失败。如果公司内网有需要直连的域名，也加在这里，用英文逗号分隔。

方法二：开启 TUN 模式

TUN 模式让代理客户端在系统中创建一块虚拟网卡，所有程序的流量都会先经过它，再由规则决定走代理还是直连。开启后无需设置环境变量，Claude Code、git、npm 等都会自动生效。

开启时注意：

  • 首次开启通常需要授予管理员权限或安装服务组件；
  • 建议同时开启客户端的 DNS 接管相关选项，避免 DNS 泄漏或解析异常；
  • 与其他 VPN、加速器类软件同时运行可能冲突，出问题时先关闭其他软件。

以 Clash Verge Rev 为例的完整步骤，可以参考 Clash Verge Rev TUN 模式设置。

验证配置是否生效

在同一个终端窗口中执行：

curl -I https://api.anthropic.com
  • 很快返回 HTTP 响应头（状态码不重要），说明终端到 Anthropic 的网络已通；
  • 长时间无响应后超时，说明代理没有生效，或当前节点无法连接；
  • 返回连接被拒绝，通常是端口写错或代理客户端没有运行。

验证通过后再启动 Claude Code，按提示在浏览器中完成登录授权。

特殊环境

WSL2

WSL2 默认运行在独立的虚拟网络中，里面的 127.0.0.1 指向 WSL 自身，而不是 Windows。可选做法：

  • 在代理客户端开启「允许局域网连接」，把代理地址改为 Windows 宿主机在虚拟网络中的 IP；
  • 或在较新的 WSL 版本中启用 mirrored 网络模式，使 WSL 与 Windows 共享网络，此时 127.0.0.1 可以直接使用。

远程 SSH 服务器

在远程服务器上运行 Claude Code 时，可以把本机的代理端口通过 SSH 反向转发过去：

ssh -R 7897:127.0.0.1:7897 user@server

登录后在服务器上设置 HTTPS_PROXY=http://127.0.0.1:7897 即可。请确认这种用法符合服务器所属机构的安全规定。

Docker 与开发容器

容器内的 127.0.0.1 同样不是宿主机。需要在容器启动参数中传入代理环境变量，并使用宿主机可达的地址；具体写法取决于容器运行环境。

稳定性建议

  • 固定节点：为 AI 工具单独建立一个手动选择的策略组，不要使用自动测速切换。
  • 任务中不换节点：Claude Code 的一次任务可能持续较长时间，中途切换出口会导致请求中断，也可能因出口变化触发额外验证。
  • 浏览器与终端同一出口：账号在同一时间从两个地区发出请求，属于不必要的风险。
  • 优先稳定线路：长连接对晚高峰丢包非常敏感，选择方法见 Claude 网络环境完整指南。

常见报错与处理

症状 可能原因 处理方式
Connection error / 请求超时 终端没有走代理 按方法一设置环境变量，或开启 TUN
连接被拒绝（ECONNREFUSED） 端口写错，或代理客户端未运行 核对客户端显示的混合端口
地区不可用相关提示 节点出口不在官方支持地区 更换支持地区节点并核实 IP 归属
浏览器登录后终端仍未登录 登录回调被代理或防火墙影响 确认 NO_PROXY 包含 localhost 与 127.0.0.1
任务进行中断开（ECONNRESET） 线路丢包或中途切换节点 固定节点，换晚高峰更稳定的线路
证书错误 公司网络或安全软件进行了 HTTPS 检查 联系网络管理员，按官方文档配置受信任证书

按上述步骤仍无法连接，可以继续阅读 Claude Code 网络连接失败怎么办，按问题页的检查清单逐项排除。

常见问题

Claude Code 为什么不走系统代理？

系统代理是一项供程序自愿读取的设置，浏览器等图形程序会遵循它，但大多数命令行程序只读取 HTTPS_PROXY 等环境变量。因此需要为终端单独配置，或开启 TUN 模式在网络层接管流量。

代理地址能写 socks5:// 吗？

不建议。部分命令行工具对 SOCKS 代理支持有限，使用代理客户端混合端口对应的 http://127.0.0.1:端口 兼容性最好。

环境变量和 TUN 模式该选哪个？

只需要 Claude Code 走代理时用环境变量，影响范围小、便于排查；同时使用 git、npm、Codex CLI 等多个工具，或某个工具不读取环境变量时，用 TUN 模式更省心。两者不要叠加后又互相冲突，出现异常时先只保留一种。

在 WSL2 中设置 127.0.0.1 为什么不生效？

WSL2 默认运行在独立的虚拟网络中，127.0.0.1 指向的是 WSL 自身而不是 Windows。需要改用 Windows 宿主机的 IP 并在客户端开启允许局域网连接，或启用 WSL 的 mirrored 网络模式。

Claude Code 用着用着断开，是代理的问题吗？

多数与线路稳定性或中途切换节点有关。长任务依赖持续的长连接，建议固定一个晚高峰稳定的节点，关闭自动切换类策略组，并避免在任务进行中更换节点。

相关阅读