AI 工具
终端怎么走代理?2026 年命令行、git、npm、pip 代理设置与 AI 编程工具 TUN 配置
终端怎么走代理?Claude Code、Codex 等 AI 编程工具连不上,多半是终端没有走代理。本文汇总 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 的准确写法和 git、npm 的代理命令,并对比环境变量与 TUN 模式。
终端怎么走代理?先说结论
AI 编程工具的网络问题,十有八九归结为一句话:系统代理管不到终端。浏览器能打开网页,不代表 Claude Code、Codex、git、npm 能连上。解决方法只有两类:给终端和工具设置代理(环境变量 export https_proxy=http://127.0.0.1:7890,以及 git、npm 各自的配置),或者开 TUN 模式一次接管所有程序。工具少、偶尔用,选环境变量;工具多、天天用,选 TUN。出口地区统一固定在美国、日本或新加坡,可以同时满足所有主流 AI 工具的要求。
各工具的网络要求一览
下表汇总了本站各篇专文的结论,点击工具名可以看详细步骤和报错处理。
| 工具 | 主要形态 | 代理方式 | 地区要求 |
|---|---|---|---|
| Cursor | 编辑器 | 编辑器内 http.proxy;终端另设;或 TUN | 部分模型不支持大陆和香港 |
| Claude Code | 终端 | 环境变量(HTTP 代理)或 TUN | 同 Claude,不支持大陆和香港 |
| Codex CLI | 终端 | 环境变量或 TUN;另有沙箱联网限制 | 同 ChatGPT,不支持大陆和香港 |
| GitHub Copilot | 编辑器扩展 | 编辑器代理设置或 TUN | 限制不突出,重在稳定 |
| Gemini CLI | 终端 | 环境变量或 TUN | 不支持大陆,香港不建议 |
| Gemini API | 代码调用 | 环境变量、代码内配置或 TUN | 按请求来源 IP 判断 |
网页聊天类工具的准备方法见 ChatGPT、Claude、Perplexity 各篇。各家的支持地区以官方说明为准,可以确定的共同点是:大陆和香港出口问题最多,美国、日本、新加坡最通用。
第一步:找到本地代理地址和端口
代理客户端在本机开了一个或多个监听端口,终端工具就是把请求发到这个端口上。打开客户端的设置页,找到下面这些信息:
- HTTP 端口:只接受 HTTP 代理协议的请求。
- SOCKS 端口:只接受 SOCKS5 协议的请求。
- 混合端口:同时接受上面两种,Clash 系客户端通常提供。有混合端口时一律用它,最省事。
- 允许局域网连接:一个开关。只在本机使用时不需要打开;WSL、虚拟机、容器或其他设备要用这台电脑的代理时才需要。
本文统一用 127.0.0.1:7890 举例。端口以你自己客户端显示的为准,不要照抄。客户端的安装和基础用法见 Clash Verge 使用教程。
第二步:设置终端代理环境变量
macOS 与 Linux(zsh / bash)
在当前终端窗口设置:
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890
取消:
unset http_proxy https_proxy all_proxy
这样设置只对当前窗口和从它启动的程序有效,关掉窗口就没了。想方便地开关,在 ~/.zshrc 或 ~/.bashrc 里加两个别名:
alias proxy_on='export http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890'
alias proxy_off='unset http_proxy https_proxy all_proxy'
保存后执行 source ~/.zshrc,以后输入 proxy_on 和 proxy_off 即可切换。
Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7890"
取消用 Remove-Item Env:HTTPS_PROXY(其余变量同理)。同样只对当前窗口有效;需要长期生效,可以在系统的环境变量设置界面里添加用户变量。
Windows CMD
set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
几个容易踩的细节
- 大小写:Linux 和 macOS 上变量名区分大小写,多数工具两种都认,但少数只认其中一种。最稳妥的是大写小写各设一份。Windows 上变量名不区分大小写。
- 协议头别写错:
https_proxy的值一般仍然是http://开头。变量名里的 https 指的是「访问 https 网站时用哪个代理」,值里的 http 指的是「用什么协议和本地代理通信」。写成https://127.0.0.1:7890多半会报错。 - SOCKS 的支持不统一:有些工具不支持 SOCKS 代理,例如 Claude Code 的官方文档就明确只支持 HTTP 代理。所以
http_proxy和https_proxy优先填 HTTP 或混合端口。 - NO_PROXY:用来指定不走代理的地址,例如
export no_proxy=localhost,127.0.0.1。访问本机服务或公司内网地址出现异常时,把它们加进来。 - 代理客户端没开时:变量还在,所有命令都会去连一个没人监听的端口,报连接被拒绝。这就是推荐用别名随用随开的原因。
验证是否生效
curl -I https://www.google.com
几秒内返回 HTTP 状态行即为生效。查看出口地区:
curl https://www.cloudflare.com/cdn-cgi/trace
输出中 ip= 是出口 IP,loc= 是国家代码。注意不要用 ping 测试:ping 走的是 ICMP 协议,不经过 HTTP 或 SOCKS 代理,ping 不通不能说明代理没生效。
第三步:git、npm、pip 的代理
git
通过 https 地址克隆和推送时,git 会读取上面的环境变量,也可以写进 git 自己的配置:
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
更推荐只对 GitHub 生效,避免影响国内仓库和公司内网仓库:
git config --global http.https://github.com.proxy http://127.0.0.1:7890
取消设置:
git config --global --unset http.proxy(其余各项同理)
用 [email protected]: 开头的 SSH 地址时,上述设置都不起作用,因为 SSH 不是 HTTP 协议。需要在 ~/.ssh/config 里为 github.com 这个主机添加一行 ProxyCommand。macOS 和 Linux 上常见写法是 ProxyCommand nc -X 5 -x 127.0.0.1:7890 %h %p;Windows 的 Git Bash 里通常用自带的 connect 工具,写作 ProxyCommand connect -S 127.0.0.1:7890 %h %p。这里要用 SOCKS 端口或混合端口。嫌麻烦的话,把远程地址改成 https 形式,或者直接用 TUN。
npm
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
取消:
npm config delete proxy 和 npm config delete https-proxy
如果只是为了装包快,其实不一定要走代理,换成国内镜像源同样有效,例如 npm config set registry https://registry.npmmirror.com。镜像走直连,不消耗机场流量。但要注意,镜像只解决「下载包」的问题,AI 工具本身运行时仍然需要代理。
pip
pip 会读取环境变量,也可以单次指定:pip install 包名 --proxy http://127.0.0.1:7890。同样可以改用国内镜像源来加速下载。
写进全局配置的代理是「永久」的。某天换了客户端、端口变了,或者代理没开,git 和 npm 会全部失败,而你可能早就忘了自己设过。出现莫名其妙的连接被拒绝时,先用 git config --global --list 和 npm config list 看一眼。
TUN 模式:一次解决所有程序
TUN 模式由代理客户端创建一块虚拟网卡,在系统网络层把所有流量接管过来,再按规则决定直连还是走代理。程序不需要知道代理的存在,自然也不需要任何环境变量和单独配置。开启步骤见代理模式与 TUN。
| 对比项 | 环境变量与工具配置 | TUN 模式 |
|---|---|---|
| 覆盖范围 | 只有设置过的终端和工具 | 全部程序,包括不支持代理设置的 |
| 配置工作量 | 每个工具各配一次 | 客户端里开一个开关 |
| SSH 协议的 git | 需单独配置 | 自动覆盖 |
| AI 工具启动的子进程 | 通常继承变量,个别不继承 | 全部覆盖 |
| 权限 | 不需要管理员权限 | 首次开启通常需要授权或安装服务 |
| 与公司 VPN、虚拟机、容器 | 互不影响 | 可能冲突,需调整路由或排除规则 |
| 出问题时 | 容易定位,看变量即可 | 涉及路由和 DNS,排查略复杂 |
| 流量消耗 | 只有指定工具走代理 | 取决于规则,建议配合规则模式 |
使用 TUN 时请保持规则模式,不要用全局模式。否则访问国内镜像源、国内代码托管平台的流量也会绕到国外,又慢又浪费流量。TUN 开启后终端仍然不通,按 TUN 模式不生效的排查处理,其中 DNS 相关的问题可以参考 DNS 设置说明。
WSL、容器与远程服务器
WSL2
WSL2 默认使用独立的虚拟网络,在 WSL 里访问 127.0.0.1 指向的是 WSL 自己,而不是 Windows。因此代理地址不能直接照搬。有两种做法:
- 在 Windows 的代理客户端里打开允许局域网连接,然后在 WSL 里把代理地址换成 Windows 主机的地址。主机地址可以从 WSL 的默认网关得到,执行
ip route show default查看。 - 较新版本的 Windows 支持把 WSL 设为镜像网络模式,此时 WSL 与主机共享网络,可以直接使用
127.0.0.1。是否可用取决于系统版本,以微软官方文档为准。
在 Windows 上开 TUN 模式通常也能覆盖 WSL 的流量,但受网络模式影响,不通时再回到上面的方法。
Docker 容器
容器内的 127.0.0.1 同样是容器自己。Docker Desktop 提供了 host.docker.internal 这个主机名指向宿主机,可以把容器内的代理变量设为 http://host.docker.internal:7890,同时在代理客户端里允许局域网连接。拉取镜像走的是 Docker 守护进程,需要在 Docker 自己的设置里配置代理,与容器内的变量无关。
远程服务器
通过 SSH 在远程服务器上运行 AI 工具时,请求从服务器发出,本机代理不起作用。服务器在支持地区的话无需处理;服务器在大陆的话,需要让它通过合规的方式获得可用出口,具体方案取决于你的网络条件,不在本文展开。
排查顺序与机场选择
遇到连接问题,按这个顺序检查,基本都能定位:
- 浏览器能否打开国外网站。不能,说明代理本身有问题,见连不上的排查步骤。
- 终端里 curl 是否通。不通,说明环境变量没生效或端口不对。
- trace 命令里的
loc是否在支持地区。不在,换节点并关闭自动选择。 - 工具自身的报错是否与网络有关。额度用尽、速率限制、权限错误都不是网络问题。
- 是否为晚高峰才出现。是的话多半是线路拥挤,见速度慢的排查。
为编程工具选机场,有一条是其他场景不太强调的:客户端要可控。你需要能看到本地端口、能开 TUN、最好还能自定义规则,所以优先选支持 Clash Verge、sing-box 等第三方客户端的机场。在本站机场推荐清单里,公开资料标注支持第三方客户端、同时标注了 ChatGPT 和 Claude 的有 二猫云(另标注 Copilot)、暮光网络(另标注 Cursor)、星岛梦和 宇宙云。只能使用官方客户端的机场并非不能用,但下单前要先确认它的客户端是否提供本地代理端口或 TUN 功能。
这些都是官方标注或公开资料,本站没有做过测试。写代码本身流量很小,但拉镜像、装依赖可能很大,建议先月付试用并观察几天实际用量,其余标准见 AI 工具用机场怎么选。使用时请遵守所在地法律法规和各工具的服务条款。
常见问题
终端怎么走代理?
AI 编程工具的网络问题,十有八九归结为一句话:系统代理管不到终端。浏览器能打开网页,不代表 Claude Code、Codex、git、npm 能连上。
为什么浏览器能上网,终端里的命令却连不上?
系统代理只对遵守该设置的应用生效,比如浏览器。终端里的大多数命令行程序不读取系统代理,只读取 HTTP_PROXY、HTTPS_PROXY 等环境变量。所以需要在终端里设置这些变量,或者打开 TUN 模式接管全部流量。
HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 有什么区别?
HTTP_PROXY 用于访问 http 地址,HTTPS_PROXY 用于访问 https 地址,ALL_PROXY 是其他协议的兜底,值都是代理服务器地址。现在绝大多数请求是 https,所以 HTTPS_PROXY 最关键。
代理端口应该填 7890 吗?
不一定。7890 只是部分客户端的默认值,不同客户端和版本并不相同,常见的还有 7897、10808、10809 等。请打开自己代理客户端的设置页,以那里显示的 HTTP 端口或混合端口为准。
设置了环境变量,git clone 还是很慢怎么办?
先看仓库地址的开头。https 开头的地址会使用环境变量或 git 的 http.proxy 设置;git@ 开头的是 SSH 协议,不读这些设置,需要在 SSH 配置里单独写代理命令,或者改用 https 地址,再或者直接开 TUN。
TUN 模式和环境变量可以同时开吗?
可以但没必要。开了 TUN 后所有流量已被接管,再设环境变量只会让请求多绕一层本地端口,出问题时更难判断原因。建议二选一:工具多、每天都用就开 TUN,偶尔使用就用环境变量。