问题 问题排查

Claude Code 网络连接失败怎么办？终端代理与 TUN 排查方法

Claude Code 报 Connection error、请求超时或登录失败，多数是终端没有走代理。本文说明如何设置 HTTPS_PROXY 或开启 TUN 模式，并给出常见报错对照与排查步骤。

首次发布
最后更新
内容类型
问题排查
资料核对
阅读时间
约 2 分钟

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

直接答案

Claude Code 连接失败，最常见的原因是终端没有走代理：代理客户端的「系统代理」通常只对浏览器生效，命令行程序需要单独设置 HTTPS_PROXY 环境变量，或开启客户端的 TUN 模式。其次是出口不在 Anthropic 官方支持地区、节点不稳定导致长连接中断，以及登录授权时浏览器与终端出口不一致。先在终端验证代理，再检查地区与节点。

可能原因

  1. A

    终端没有走代理

    浏览器能打开 claude.ai，不代表终端也能访问。命令行程序默认不读取系统代理设置，需要环境变量或 TUN 模式。

  2. B

    代理端口或协议填写错误

    HTTPS_PROXY 指向了错误端口，或客户端没有开启对应的混合端口，请求会直接被拒绝。

  3. C

    出口不在官方支持地区

    终端走的节点在香港等不受支持地区时，API 请求会被拒绝，表现为 403 或地区相关错误。

  4. D

    节点不稳定，长连接中断

    Claude Code 的任务往往持续较长时间并使用流式输出，节点丢包或晚高峰拥塞会导致请求中途断开。

  5. E

    公司网络或安全软件拦截

    企业代理、防火墙或杀毒软件的 HTTPS 检查，可能导致证书错误或连接被重置。

检查方法

  • 在同一个终端窗口执行 echo $HTTPS_PROXY（Windows PowerShell 中为 $env:HTTPS_PROXY），确认变量已设置。
  • 在终端中用 curl -I https://api.anthropic.com 测试，观察能否返回 HTTP 响应头而不是超时。
  • 在代理客户端的连接列表中查看是否出现 anthropic.com 相关请求。
  • 核对客户端设置中显示的混合端口或 HTTP 端口，例如 7897，与环境变量是否一致。
  • 用 IP 查询网站确认当前策略组的出口地区在官方支持列表中。

解决步骤

  1. 确认代理客户端端口

    打开代理客户端设置，记下混合端口或 HTTP 代理端口，以客户端显示的为准，例如 7897，并确认允许本机连接。

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

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

  3. 或者开启 TUN 模式

    不想逐个配置环境变量时，在 Clash Verge Rev 等客户端中开启 TUN 模式，让所有终端流量被系统级接管。

  4. 在终端内验证连通性

    在设置了代理的同一个终端中用 curl 访问 Anthropic API 域名，确认能拿到响应后再启动 Claude Code。

  5. 固定支持地区节点

    把 Anthropic 相关域名指向一个手动选择的支持地区节点，避免自动切换导致会话中断或地区变化。

  6. 重新登录 Claude Code

    在代理生效的终端中重新执行登录，确保浏览器授权和终端请求使用同一地区出口。

  7. 持久化代理配置

    确认可用后，把环境变量写入 shell 配置文件，或在 Claude Code 的 settings.json 中通过 env 字段设置，避免每次新开终端都要重复配置。

为什么终端是重灾区

浏览器、桌面 App 和终端读取代理的方式不同。代理客户端开启「系统代理」后，修改的是操作系统的代理配置，浏览器会读取它，但大多数命令行程序不会。这就是「网页正常、Claude Code 报错」最主要的原因。确认终端代理之后，剩下的问题才回到地区和节点质量上。

常见报错对照

报错 / 表现 可能原因 处理方向
Connection error / Unable to connect 终端未走代理 设置 HTTPS_PROXY 或开 TUN
Request timed out / ETIMEDOUT 节点超时、端口错误 核对端口，换节点
ECONNREFUSED 127.0.0.1 代理端口未开启或填错 检查客户端混合端口
ECONNRESET / socket hang up 长连接被中断 换稳定的专线节点
403 Forbidden 出口地区或 IP 被拒 换支持地区节点
证书错误（self signed certificate 等） 企业代理或安全软件解密 HTTPS 关闭 HTTPS 扫描或在可信网络测试

不同系统与客户端的差异

  • macOS / Linux：环境变量写入 ~/.zshrc 或 ~/.bashrc 后，需要新开终端或执行 source 才会生效。
  • Windows：PowerShell 与 CMD 的设置语法不同，CMD 使用 set HTTPS_PROXY=…；在 WSL 中，127.0.0.1 不一定指向 Windows 主机，需要改用宿主机地址或在客户端中开启允许局域网连接。
  • Clash Verge Rev：开启 TUN 模式需要授予服务权限，详细步骤见 Clash Verge Rev TUN 模式设置。
  • IDE 内置终端：VS Code 等编辑器的终端继承的是编辑器启动时的环境，修改配置后需要重启编辑器。

提示可以写一个只在当前会话生效的代理别名，需要时执行，不需要时用 unset 取消，避免影响 npm 等其他工具访问国内镜像。

注意不要在环境变量中设置 NODE_TLS_REJECT_UNAUTHORIZED=0 来绕过证书错误，这会关闭证书校验，带来中间人攻击风险。

完整的配置说明见 Claude Code 网络环境配置与代理设置；Codex CLI 的同类问题可参考 Codex 无法连接怎么办。

仍然无法解决怎么办？

如果环境变量与 TUN 都已配置仍无法连接，建议联系机场客服确认节点是否能访问 Anthropic API，或换一款客户端（例如从 Clash Verge Rev 换到 v2rayN）复测；也可以在另一台设备上测试以排除本机安全软件影响。同时查看 Anthropic 官方状态页，确认 API 与 Claude Code 服务是否正常，并遵守服务条款与当地法律法规。

进入网络急诊室 同类问题 搜索机场湾

常见问题

Claude Code 网络连接失败怎么办？

Claude Code 连接失败，最常见的原因是终端没有走代理：代理客户端的「系统代理」通常只对浏览器生效，命令行程序需要单独设置 HTTPS_PROXY 环境变量，或开启客户端的 TUN 模式。其次是出口不在 Anthropic 官方支持地区、节点不稳定导致长连接中断，以及登录授权时浏览器与终端出口不一致。先在终端验证代理，再检查地区与节点。

为什么浏览器能用 Claude，Claude Code 却连不上？

系统代理只对遵循系统设置的程序生效，终端程序需要设置 HTTPS_PROXY 环境变量或开启 TUN 模式才会走代理。

设置了 HTTPS_PROXY 还是不行？

检查变量是否在启动 Claude Code 的同一个终端会话中生效、端口是否正确，以及出口地区是否在官方支持列表中。

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

环境变量影响范围小、可控；TUN 模式一次性接管所有程序，适合同时使用多个命令行工具。二选一即可，无需叠加。

相关阅读