jichangmom.mom机场测评与选购指南 · 机场推荐

AI 工具AI 工具 · 约 10 分钟

Claude Code 终端代理设置:在终端里怎么走代理

Claude Code 终端代理设置:浏览器能打开 Claude,终端里的 Claude Code 却报连接错误,原因几乎总是同一个:终端程序不认系统代理。解决办法有两种,开 TUN 模式让客户端接管全部流量,或者给终端设置代理环境变量。这篇把两种做法、验证方法和长任务断线的原因讲清楚。

Claude Code 终端代理设置,先说结论:两种做法,选一种

Claude Code 是在终端里运行的程序。让它走代理只有两条路:

不确定选哪个,就先开 TUN;想精细控制,再换环境变量。无论哪种,配完都要验证,方法在后面。

各 AI 服务有自己的官方支持地区和使用条款,是否可以使用、如何注册和付费,以官方说明为准,请遵守其条款。

本文只讲终端的网络配置,账号注册、订阅付款和账号风控都不在本文范围。

终端为什么不认系统代理

代理客户端里的“系统代理”开关,做的事情是往操作系统的网络设置里写一条记录:“HTTP 代理在本机某个端口”。

浏览器和多数图形界面软件会主动去读这条记录,所以它们能上。

终端里的命令行程序大多不读这条记录。

它们遵循的是另一套更老的约定:看环境变量里有没有 HTTP_PROXY、HTTPS_PROXY 这些名字,有就用,没有就直接连接。

于是出现了经典场面:浏览器里 Claude 用得好好的,终端里 Claude Code 却一直报连接失败或超时。

这不是 Claude Code 特有的问题,git、npm、pip、curl 都一样。更完整的解释见 TUN 模式与系统代理 和 浏览器能上、软件不走代理。

做法一:打开 TUN 模式

TUN 模式会在系统里创建一块虚拟网卡,把所有程序的流量引到代理客户端,再由客户端按规则决定直连还是走节点。

对终端来说,它什么都不用知道,流量已经被接管了。

  1. 打开 TUN 开关在 Clash Verge Rev 等客户端的设置页里打开。首次开启通常需要管理员权限或先安装服务组件,按提示操作,见 Clash Verge Rev 教程。
  2. 保持规则模式TUN 只是把流量收进来,去向仍由规则决定。不需要切到全局模式。
  3. 确认规则覆盖相关域名Claude Code 主要连接 anthropic.com、claude.ai、claude.com 这几个后缀下的地址,把它们指向一个手动选择的 AI 策略组。完整清单以官方文档和你连接页里看到的为准。
  4. 新开一个终端验证按后面“怎么验证”一节检查。

优点:一次设置全部生效,包括 Claude Code 在工作中调用的 git、npm 等子命令;出口和浏览器天然一致。

缺点:需要系统权限;可能和公司的 VPN、其他虚拟网卡软件冲突;所有程序的连接都经过客户端的规则,规则写得不好时,本来该直连的国内服务可能被误送去代理。

DNS 也要交给客户端接管,否则会出现解析错误,见 DNS 设置与 DNS 泄漏。

做法二:设置代理环境变量

先在代理客户端里找到本地端口。

Clash 系客户端一般有一个“混合端口”,同时接受 HTTP 和 SOCKS 代理请求,具体数字以你客户端设置页显示的为准。

下面用 7897 举例,换成你自己的端口。

几点说明:

优点:不需要系统权限,不影响其他程序,可以做到“这个窗口走代理、那个窗口不走”。

缺点:只有读取这些变量的程序才生效;用 sudo 运行的命令默认不继承你的环境变量;每换一种环境(新终端、容器、远程机器)都要重新设置。

两种做法对照

对比项TUN 模式环境变量
生效范围整台电脑的所有程序设置了变量的终端及其启动的程序
是否需要系统权限通常需要不需要
子命令(git、npm 等)自动覆盖多数会读变量,少数要单独配置
和公司 VPN 共存容易冲突一般不冲突
出口是否与浏览器一致一致,走同一套规则一致,前提是都经过同一个客户端和策略组
容易出的问题DNS 没接管、规则误伤国内服务忘了设、客户端没开、端口写错

怎么验证终端是否已经走代理

不要凭感觉,按下面四步确认。Windows PowerShell 里请输入 curl.exe,因为旧版 PowerShell 里的 curl 是另一个命令的别名。

  1. 看变量在不在用环境变量做法的话,macOS 和 Linux 执行 env | grep -i proxy,PowerShell 执行 Get-ChildItem Env:*PROXY*,确认输出里有你设置的地址。
  2. 测一下能不能通执行 curl -I 加上你要访问的服务地址。有响应头返回说明链路是通的;长时间卡住或提示连接超时,说明没走代理或节点不通。加 -v 参数可以看到 curl 有没有使用代理、连的是哪个地址。
  3. 看出口 IP用 curl 请求一个会原样返回来源 IP 的查询服务(用你平时信得过的即可,这里不列具体网址),再用浏览器打开同一个服务对比。两边显示的 IP 和地区应该一致,并且是你选中的那个节点的地区。
  4. 看客户端的连接页启动 Claude Code 发一条消息,在代理客户端的连接页里应当出现对应的连接,并显示命中的规则和节点。这里看不到,说明流量根本没进客户端。

别用 ping 来判断。ping 走的不是 HTTP,不经过代理端口,它通不通都说明不了问题。

还有一个小细节:curl 对明文 HTTP 只认小写的 http_proxy,想让各种工具都识别,大小写两种写法都设置一遍最保险。

长任务中断的网络侧原因

Claude Code 的一次任务可能持续几分钟到几十分钟,期间和服务端之间是一连串流式请求。

任何一环断开,你看到的就是报错和重试。网络侧常见的原因有这些:

服务端自身也可能过载或限流,那种情况换节点没有用,等待或查看官方状态页面即可。

区分的办法是看报错:连接超时、连接被重置多半是网络问题;明确返回过载、限流之类的提示则是服务端的事。

几种特殊环境

WSL

WSL2 默认运行在独立的虚拟网络里,它里面的 127.0.0.1 指向的是 WSL 自己,不是 Windows。

所以环境变量里的代理地址要写 Windows 主机在这个虚拟网络中的地址,并且在代理客户端里打开“允许局域网连接”。

Windows 上的 TUN 能否接管 WSL 的流量和 WSL 的网络模式有关,不要想当然,用上一节的 curl 方法在 WSL 里实际验证。Windows 侧的基本配置见 Windows 怎么用机场。

远程服务器和容器

通过 SSH 连到远程服务器后再运行 Claude Code,请求是从那台服务器发出的,你本机的代理对它不起作用,要看服务器自己的网络。

Docker 容器同理:容器有自己的网络环境,里面的 127.0.0.1 是容器自身,需要把代理环境变量传进容器,并把地址指向宿主机。

macOS

macOS 上两种做法都常用。用 TUN 时注意系统会弹出添加网络配置或授权的提示,要允许。基础设置见 Mac 怎么用机场。

终端里常见的报错文字是什么意思

Claude Code 运行在 Node.js 上,网络出错时经常带着 Node 的错误代码。认识这几个,就能大致判断问题在哪一段。

报错里出现含义先查什么
ECONNREFUSED 127.0.0.1:端口连本机代理端口被拒,没有程序在监听代理客户端是否开着,变量里的端口是否写对
ETIMEDOUT连接超时,对方一直没响应是否走了代理,当前节点是否可用
ECONNRESET连接被中途重置节点是否稳定,策略组是否在自动切换
ENOTFOUND域名解析失败DNS 是否被客户端接管,规则是否覆盖该域名
证书相关错误,如 unable to get local issuer certificate收到的证书不被信任是否在公司网络里,有没有中间设备做 HTTPS 检查
提示过载或请求过多服务端繁忙或限流与代理无关,稍后再试或查看官方状态页面

公司网络里的证书问题,Claude Code 的官方文档提供了指定额外根证书的办法(Node.js 通用的 NODE_EXTRA_CA_CERTS 环境变量),证书文件要由公司 IT 提供。不要用关闭证书校验的方式绕过。

它调用的 git、npm、pip 也要能走代理

Claude Code 在工作中会替你运行各种命令。

这些子进程会继承启动它的终端里的环境变量,所以用环境变量做法时,多数工具自动就能走代理。

但有几处例外要知道:

如果 Claude Code 对话正常、唯独它执行的安装命令失败,在同一个终端里手动跑一遍同样的命令对比,就能分清是网络问题还是别的原因。

把配置固定下来,少踩重复的坑

每次开终端都手敲变量,迟早会忘。下面几种做法任选一种:

无论哪种,都记住一条:哪天所有命令行工具同时报连接错误,先看代理客户端是不是没开、端口是不是变了。

登录和授权这一步

首次使用时,Claude Code 会引导你在浏览器里完成登录授权,再回到终端继续。这一步涉及浏览器和终端两个程序,任何一边没走对出口都可能卡住。

账号本身的问题,比如订阅状态、组织权限,不是网络能解决的,以官方说明为准。

选机场时看什么

从终端使用的角度,机场要满足这几条:

公开资料里标注支持 Claude、同时支持通用客户端的有 二猫云、WgetCloud、TAG、宇宙云、暮光网络。

这些只是公开资料标注,需自行验证:买最短周期,配好后在晚高峰跑一个十分钟以上的任务,看重试多不多。

更多候选见 AI 机场推荐;网页版 Claude 的配置见 Claude 网络设置。

参考来源

本文涉及的客户端功能、协议和服务规则,以下面的官方文档和项目页面为准:

  1. Claude Code 文档:Enterprise network configuration:HTTPS_PROXY、NO_PROXY 代理变量
  2. Claude Code 文档:Troubleshooting:官方排查指南
  3. Microsoft Learn:Accessing network applications with WSL:WSL 与 Windows 主机的网络关系
  4. everything curl:Proxy environment variables:代理环境变量的通用约定

常见问题

Claude Code 提示连接错误,但浏览器访问一切正常,怎么办?

这是终端没走代理的典型表现。浏览器遵守系统代理,终端里的程序默认不遵守。

打开代理客户端的 TUN 模式,或者在当前终端里设置 HTTPS_PROXY 和 HTTP_PROXY 环境变量指向客户端的本地端口,然后用 curl 验证一下再启动。

TUN 模式和环境变量,选哪个?

想省事、电脑上所有工具都要走代理,选 TUN。

想精确控制、只让某个终端窗口走代理,或者公司电脑不方便装虚拟网卡,选环境变量。

两者可以同时存在,但排查问题时最好先只留一种,免得分不清流量走的是哪条路。

HTTPS_PROXY 的值为什么是 http 开头?

变量名里的 HTTPS 指的是“访问 HTTPS 网站时用哪个代理”,值里的 http 指的是“和本地代理端口之间用什么协议通信”。

代理客户端的本地端口一般提供的是 HTTP 代理,所以写成 http 加本机地址和端口是正常的。

Claude Code 长任务跑到一半断了,会丢进度吗?

遇到网络错误时它通常会自动重试几次,短暂抖动一般能自己恢复;已经写入磁盘的文件改动不会消失。

但连接长时间不通,这一轮任务就会失败,需要你重新发起。所以长任务前先确认策略组是手动选择、电脑不会休眠。

在 VS Code 或 Cursor 的内置终端里运行 Claude Code,需要另外设置吗?

需要。编辑器设置里的代理只管编辑器自己和扩展的请求,不会传给内置终端里启动的程序。

内置终端和普通终端一样,要靠 TUN 模式或环境变量。编辑器本身的代理设置见 Cursor 网络设置。

怎么确认 Claude Code 的出口和浏览器是同一个?

在同一个终端里用 curl 查看出口 IP,再用浏览器查看一次,两边对比。

同时打开代理客户端的连接页,确认终端发出的连接命中的是和浏览器相同的策略组和节点。

不一致时,检查规则里是否包含相关域名。

报错里有 ECONNREFUSED 127.0.0.1 加一个端口号,是什么意思?

程序按环境变量去连本机的代理端口,但那个端口上没有程序在监听。

通常是代理客户端没开、刚重启还没就绪,或者客户端的端口改过而变量里还是旧的。

打开客户端核对端口,再用 curl 测一次。

AI 工具里的其他文章

其他栏目