GATE登机口

AI 工具

Claude Code 代理设置(2026):终端环境变量、TUN 模式与连接报错排查

Claude Code 代理设置:Claude Code 运行在终端里,不读取系统代理,浏览器能上网不代表它能连上。本文给出各系统设置 HTTPS_PROXY 的准确命令,说明环境变量和 TUN 模式各适合什么情况,以及连接错误、地区不支持、证书错误的排查顺序。

发布 · 最后更新 · 登机口编辑

Claude Code 代理设置:先说结论

Claude Code 是命令行程序,它不看系统代理开关,只认环境变量。最常见的「开了代理还连不上」,原因就是终端里没有设置 HTTPS_PROXY。解决办法二选一:在终端里执行 export https_proxy=http://127.0.0.1:7890(端口换成你自己的),或者在代理客户端里打开 TUN 模式让所有程序强制走代理。出口地区的要求与 Claude 网页版相同,不能是大陆和香港。另外按官方文档,它不支持 SOCKS 代理,地址要写 http:// 开头。

Claude Code 是什么,有哪些使用方式

Claude Code 是 Anthropic 官方的编程助手,主体是一个在终端里运行的命令行工具:你在项目目录里启动它,用自然语言让它读代码、改文件、执行命令。常见的安装方式是通过 npm 全局安装 @anthropic-ai/claude-code,官方也提供独立的安装脚本,以官网文档为准。

使用方式运行位置网络从哪里走
终端里直接运行本机 shell当前 shell 的环境变量,或 TUN
编辑器扩展(VS Code、JetBrains 等)编辑器启动的进程编辑器进程继承的环境变量,或 TUN
桌面应用中的相应功能桌面应用系统代理或 TUN
远程服务器、WSL、容器远程环境远程环境自己的网络和变量

安装阶段也有网络问题:npm 从官方源下载包在大陆可能很慢,这属于 npm 的代理或镜像设置,和 Claude Code 本身无关,处理方法见 AI 编程工具网络设置总览。

Claude Code 对网络环境的要求

  • 地区:出口 IP 需在 Anthropic 支持的国家或地区。大陆、香港出口会被拒绝,通常表现为请求返回 403 或提示地区不受支持。
  • 要连的服务:主要是 api.anthropic.com,登录授权还会用到 claude.ai 及 Anthropic 的控制台域名。规则里这几个域名要走同一个出口。
  • 稳定性:一次任务会连续发出很多请求,单次响应可能持续几十秒到几分钟。线路中途断一下,当前这一步就会报错重试。所以稳定比速度重要得多。
  • 出口一致:登录时浏览器的出口和终端的出口最好相同;日常使用也尽量固定节点,原因见 Claude 一文里关于地区稳定性的部分。

节点地区的选择与网页版完全一致:美国或日本作为主地区,新加坡、台湾备用,不用香港。

方法一:设置终端代理环境变量

先找到本地代理端口

打开代理客户端的设置页,找到本地监听端口。Clash 系客户端通常有一个混合端口,同时接受 HTTP 和 SOCKS 请求;v2rayN 等客户端则可能分为两个端口。下面统一用 7890 举例,请以你自己客户端里显示的数字为准,常见的还有 7897、10809 等。

macOS 与 Linux(zsh、bash)

只在当前终端窗口生效:

export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890

然后在同一个窗口里运行 claude。关闭代理变量:

unset https_proxy http_proxy

想每次打开终端自动生效,把 export 那一行加到 ~/.zshrc(bash 用户是 ~/.bashrc)末尾,然后执行 source ~/.zshrc。不过更推荐的做法是定义两个别名,用的时候再开:

alias proxy_on='export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890'

alias proxy_off='unset https_proxy http_proxy'

这样代理客户端没开的时候,终端里的其他命令不会因为连不上本地端口而全部报错。

Windows

PowerShell 当前窗口生效:

$env:HTTPS_PROXY="http://127.0.0.1:7890"; $env:HTTP_PROXY="http://127.0.0.1:7890"

CMD 当前窗口生效:

set HTTPS_PROXY=http://127.0.0.1:7890 和 set HTTP_PROXY=http://127.0.0.1:7890

需要长期生效,可以在系统的环境变量设置里新增这两个用户变量,之后新开的终端都会带上。

写进 Claude Code 的配置文件

Claude Code 支持在用户配置文件 ~/.claude/settings.json 的 env 字段里声明环境变量,例如加入 "env": {"HTTPS_PROXY": "http://127.0.0.1:7890"}。好处是只影响 Claude Code,不影响终端里的其他程序;通过编辑器扩展启动时也能读到。字段的具体写法以官方文档为准。

验证代理是否生效

设好变量后,先别急着开 Claude Code,用 curl 验证:

curl -I https://api.anthropic.com

几秒内返回了 HTTP 状态行(哪怕是 404 之类的状态码),说明网络是通的;一直卡住或提示超时,说明代理没生效或节点不通。再执行:

curl https://www.cloudflare.com/cdn-cgi/trace

输出里的 loc= 一行是当前出口的国家代码,确认它不是 CN 或 HK。

不要把变量写成 socks5:// 开头。按官方文档,Claude Code 不支持 SOCKS 代理。如果你的客户端只有 SOCKS 端口,在客户端里开启 HTTP 或混合端口,或者直接用下面的 TUN 方式。

方法二:开启 TUN 模式

TUN 模式由代理客户端创建一个虚拟网卡,在系统网络层接管所有流量。开启后终端里的任何程序都自动走代理,不需要设置任何环境变量。Claude Code 在工作过程中会调用 git、包管理器、测试脚本,还可能启动 MCP 服务,这些子进程在 TUN 下也都一并覆盖。设置步骤见代理模式与 TUN。

对比项环境变量TUN 模式
生效范围设置了变量的终端及其子进程整台电脑的所有程序
是否需要管理员权限不需要首次开启通常需要授权
不读环境变量的程序无效有效
与公司 VPN、虚拟机、容器网络互不干扰可能冲突,需要调整
排查难度低,变量一看便知略高,涉及路由和 DNS
适合谁偶尔使用、想精确控制的人每天使用、工具很多的人

使用 TUN 时仍然建议用规则模式而不是全局模式,这样访问国内的代码仓库和镜像源还是直连,速度不受影响。TUN 开了但终端依然不通,按 TUN 模式不生效的排查检查。

登录授权怎么完成

首次运行时需要登录。使用订阅账号的方式会打开浏览器,在网页上确认授权后回到终端。这个过程有两个容易出问题的地方:

  • 浏览器能打开授权页,终端却等不到结果:说明终端没有代理。先设好环境变量再重新登录。
  • 在没有浏览器的远程服务器上:终端会显示一个链接,复制到本机浏览器打开,授权后把页面给出的代码粘贴回终端。此时服务器本身也要能连到 Anthropic,所以服务器需要在支持地区,或者自己配置好代理。

使用 API 密钥的方式不需要浏览器授权,但密钥属于敏感信息,建议通过环境变量或官方推荐的方式提供,不要写进会提交到仓库的文件里。

常见报错与处理

现象常见原因处理
连接错误、请求超时、fetch failed终端没走代理;代理客户端没开;端口写错检查变量和端口,用 curl 验证
连接被拒绝(指向 127.0.0.1)变量指向的端口上没有程序监听启动代理客户端,核对端口号
403 或提示地区不受支持出口在大陆、香港等不支持地区换节点,用 trace 命令确认 loc
登录一直等待终端与浏览器出口不一致或终端不通设好代理后重新登录
证书校验失败、自签名证书公司网络或安全软件解密了 HTTPS向管理员索取根证书,按官方文档配置额外 CA;不要关闭校验
响应中途断开后自动重试线路抖动换更稳定的节点,避开拥挤时段
提示达到用量上限或服务过载账号额度或官方负载,与网络无关等待恢复,换节点没有意义

Claude Code 自带一个诊断子命令 claude doctor,可以检查安装和基本环境是否正常,报错原因不明时先跑一下。如果 curl 测试都不通,问题在代理而不在 Claude Code,转到连不上的排查步骤和节点超时怎么办。地区类报错的更多说明见 Claude 地区不支持的排查。

机场怎么选

Claude Code 的流量消耗不大,但对连接稳定性和出口稳定性要求高。挑机场时建议按这个顺序看:标注支持 Claude → 有美国或日本节点 → 支持带 TUN 功能的第三方客户端 → 晚高峰稳定。第三点对终端用户很关键:只能用官方客户端的机场,要先确认客户端是否提供本地代理端口或 TUN,否则终端工具无从接入。

本站机场推荐清单里没有机场专门标注 Claude Code,可以参考 Claude 的标注。公开资料标注支持 Claude 且明确支持第三方客户端的有:二猫云(Clash Verge Rev、v2rayN)、暮光网络(Clash Verge Rev、sing-box、Surge 等)、星岛梦(通用订阅客户端)、宇宙云(Clash Verge、v2rayN 等)。飞猫云、光速云、无忧链接也有 Claude 标注,但使用官方客户端,买之前先确认能否满足终端代理的需要。

以上均为官方标注或公开资料,本站未做测试。建议先买月付,用上面的 curl 命令和几次真实的编码任务验证,再决定是否长期使用。更多选择标准见 AI 工具用机场怎么选。使用时请遵守所在地法律法规和 Anthropic 的服务条款。

所属专题:Claude 用什么机场。同专题还有:Claude 提示所在地区不支持怎么办、AI 机场推荐。

常见问题

Claude Code 代理设置怎么做?

Claude Code 是命令行程序,它不看系统代理开关,只认环境变量。最常见的「开了代理还连不上」,原因就是终端里没有设置 HTTPS_PROXY。解决办法二选一:在终端里执行 export https_proxy=http://127.0.0.1:7890(端口换成你自己的),或者在代理客户端里打开 TUN 模式让所有程序强制走代理。

Claude Code 为什么开了代理还是连不上?

因为终端里的程序不读取系统代理设置。代理客户端打开系统代理后,只有浏览器等遵守该设置的应用会走代理。需要在终端里执行 export https_proxy=http://127.0.0.1:端口,或者在代理客户端里开启 TUN 模式。

Claude Code 支持 SOCKS5 代理吗?

按官方文档,Claude Code 不支持 SOCKS 代理,应使用 HTTP 代理地址。Clash 系客户端的混合端口两种协议都支持,把变量写成 http://127.0.0.1:端口 即可。只有 SOCKS 端口时改用 TUN 模式。

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

只在一两个终端里用 Claude Code,环境变量更轻量,也方便随时关闭。如果还要让它调用的 git、npm、各种脚本一起走代理,或者在多个终端和编辑器里使用,TUN 更省心。两者不需要同时开。

Claude Code 登录时浏览器授权成功但终端没反应怎么办?

通常是浏览器和终端的网络出口不一致,或者终端这边没有代理、拿不到登录结果。先在终端里设好代理变量再重新执行登录。在远程服务器上使用时,按提示把授权后得到的代码粘贴回终端。

Claude Code 对节点地区有要求吗?

有,和 Claude 网页版一致。出口需要在官方支持的国家或地区,中国大陆和香港不在其中。建议固定使用美国或日本的一两个节点,网页版和终端尽量用同一个出口,详见 Claude 网络环境与节点选择。

本站主推:星岛梦 2020 年开业的老牌机场,12 个地区、套餐形式多。主打「超量 150G」¥25/月 / 150GB,年付小包 ¥96(折合 ¥8/月),资料分 9.5(第 1),优惠码 nmw888(新人注册 9 折)。

去星岛梦官网星岛梦完整评测