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 网络环境与节点选择。