Claude Code 代理设置、Codex CLI 代理:TUN 与长任务断连
先说明边界
这篇只讲网络层面的设置:流量怎么走代理、为什么会断、怎么排查。各家 AI 服务支持哪些国家和地区、账号如何开通,由服务方的条款决定,不在本文范围内。使用前请确认你所在地区在官方支持范围内,并遵守服务条款和当地法律法规。
命令行工具走的是哪条路
在浏览器里用 AI 对话,流量走系统代理。在终端里运行命令行工具,情况不同:这些工具是命令行程序,网络请求由它们自己发出,只认环境变量和自己的配置文件。
所以会出现这种情况:网页版正常,命令行工具启动后一直卡在连接,或者报超时、网络错误。这不是工具坏了,是它的请求根本没有进代理。原理和 git、npm 一样,详细解释见终端代理设置教程。
方法一:设置代理环境变量
先在代理客户端的设置页确认本地端口(下面用 7890 举例,以客户端显示的为准)。
macOS / Linux:
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
Windows PowerShell:
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"
设置完,在同一个终端窗口里启动工具。环境变量只对当前窗口有效,新开的窗口需要重新设置,或者把上面两行写进 ~/.zshrc、~/.bashrc 里。
几个要点:
- 优先用 HTTP 代理地址。 Claude Code 的官方文档说明它支持
HTTPS_PROXY和HTTP_PROXY,不支持 SOCKS 代理。所以这里填http://开头的地址,不要填socks5://。Clash 系客户端的混合端口本身就能接收 HTTP 代理请求。 - Codex CLI 等其他工具 一般也读取这组标准环境变量。不同版本的行为可能有差别,以各自的官方文档为准。
- 不想影响其他命令时,可以只在启动那一行前面加变量,例如
HTTPS_PROXY=http://127.0.0.1:7890 claude,这样变量只对这一次运行有效(macOS / Linux 的写法)。 - 部分工具支持在自己的配置文件里写环境变量,适合不想改 shell 配置的人,具体格式查官方文档。
方法二:开启 TUN 模式
TUN 模式用一张虚拟网卡接管整台电脑的流量,终端里的任何程序都不需要再单独配置。对命令行 AI 工具来说,它有一个额外的好处:这类工具在执行任务时会调用很多子命令,比如 git clone、npm install、pip install、下载依赖。环境变量方案下,这些子命令是否走代理取决于它们各自的规矩;TUN 方案下全部被接管。
| 对比项 | 环境变量 | TUN 模式 |
|---|---|---|
| 设置成本 | 两行命令 | 首次开启需要管理员权限 |
| 工具本身的请求 | 能走代理 | 能走代理 |
| 工具调用的子命令 | 大多能走,个别不认 | 全部接管 |
| 对其他程序的影响 | 无 | 整机流量都经过规则判断 |
| 推荐场景 | 偶尔使用、公司电脑不便改网络 | 每天长时间使用 |
开启方法见系统代理与 TUN 模式。开了 TUN 就不要再设置环境变量,两层叠加不会更稳,只会让排查变复杂。
长任务为什么会断
命令行 AI 工具和网页对话最大的不同是任务时间长。让它重构一个模块、跑一轮测试再修,可能持续十几分钟甚至更久,期间和服务端保持着流式连接。这段时间里任何一次网络抖动都可能让任务中断。
节点自动切换是头号原因。 订阅里默认的「自动选择」分组会定时测延迟并切到更快的节点。切换时旧连接全部断开,正在进行的请求随之失败。出口 IP 还可能跟着从一个地区变到另一个地区,短时间内 IP 反复变化也容易触发服务端的安全检查。
处理步骤:
- 在客户端代理页找到 AI 流量所在的分组(机场常会单独建一个 AI 分组,没有就是主分组);
- 把它从「自动选择」「故障转移」改为手动选定的一个节点;
- 跑一个较长的任务,观察是否还断;
- 稳定之后不要再频繁更换。
晚高峰线路拥堵。 公网线路在晚上丢包上升,长连接首当其冲。如果只有晚上断、白天正常,问题在线路,客户端怎么设置都解决不了,可以看晚高峰网速慢的原因。
电脑休眠和网络切换。 合上笔记本、Wi-Fi 换到另一个热点,连接都会断。长任务期间保持电脑唤醒和网络不变。
断了之后也不必从头来。多数工具提供恢复会话的功能,例如 Claude Code 可以用 claude --continue 接着上一次会话继续,其他工具的对应命令查各自文档。
企业网络与证书问题
在公司网络里使用,遇到的往往不是「没有代理」,而是「公司有自己的代理」。
- 公司要求走统一代理: 把
HTTPS_PROXY设为公司 IT 提供的代理地址,而不是自己的本地代理。 - 证书错误: 报错里出现
self signed certificate、unable to verify之类字样,通常是公司网关会对 HTTPS 流量做检查,用的是公司自己签发的根证书,命令行工具不认识它。正确做法是向 IT 索取根证书文件,再让工具信任它。基于 Node.js 的工具可以用NODE_EXTRA_CA_CERTS环境变量指向证书文件,其他工具查官方文档里关于自定义证书的部分。 - 不要关闭证书校验。 网上常见把校验整个关掉的写法,那等于放弃了对中间人攻击的防护,而你的代码和密钥正从这条连接上经过。
- 内网地址不走代理: 用
NO_PROXY列出公司内网域名,避免访问内部代码仓库时被送去代理。
公司设备上的网络策略由公司决定,改动之前先确认符合所在单位的规定。
排查清单
- 在同一个终端里执行
curl -I https://www.google.com,能返回响应头说明终端已经走上代理; - 不通:检查端口号、客户端是否运行、节点是否可用;
- curl 通但工具不通:确认填的是 HTTP 代理而不是 SOCKS,确认是在设置变量的那个窗口里启动的;
- 能用但经常断:固定节点,换时段对比;
- 报证书错误:按上一节处理,不要关闭校验;
- 都正常却仍报错:查看服务方的状态页,可能是服务端问题。
选线路的思路可以参考 AI 用机场怎么选:这类工具流量很小,稳定性比速度重要。
把代理写进工具自己的配置文件
在终端里 export 的变量有一个局限:它只对这个 shell 以及从它启动的程序有效。工具在后台拉起的进程、从编辑器扩展里启动的会话,不一定继承得到,于是出现「前台对话正常,后台任务连不上」的情况。
Claude Code 支持在自己的设置文件里声明环境变量,这样无论从哪里启动都会带上。用户级的设置文件是主目录下 .claude 文件夹里的 settings.json,在其中加入 env 一段:
{
"env": {
"HTTPS_PROXY": "http://127.0.0.1:7890",
"HTTP_PROXY": "http://127.0.0.1:7890"
}
}
几点说明:
- 文件里已有其他内容时,把
env作为并列的一项加进去,注意 JSON 的逗号和括号要配对; - 代理地址必须带
http://前缀,只写127.0.0.1:7890会被判定为格式错误; - 大写和小写两种变量名都能识别,同时设置了多个时只取其中一个,所以不要在不同地方写不一样的地址,排查时会很乱;
- 客户端的端口改了,这里也要跟着改,否则所有请求都会发到一个没人监听的端口上。
在 VS Code 等编辑器里使用它的扩展时,扩展的设置里一般也有填写环境变量的位置,作用相同。其他命令行工具各有自己的配置方式,以各自的官方文档为准。
WSL 和容器里的特殊情况
在 Windows 上,很多人把命令行工具装在 WSL 里,而代理客户端运行在 Windows 上。这时填 127.0.0.1 常常不通,因为在默认的网络模式下,WSL 是一台独立的虚拟机,它的 127.0.0.1 指向自己,不是 Windows。
有三种处理办法:
- 在 Windows 的代理客户端里开 TUN 模式。 WSL 的流量从 Windows 出去时会被一并接管,WSL 里面什么都不用设置。这是最省事的办法。
- 让 WSL 使用镜像网络模式。 较新的 Windows 版本支持这种模式,开启后 WSL 和 Windows 共用网络,
127.0.0.1可以直接访问到 Windows 上的代理端口。具体开启方式见微软的 WSL 文档。 - 把代理地址指向 Windows 主机。 在 WSL 里执行
ip route show default,输出里via后面的地址就是 Windows 主机的地址,把环境变量里的127.0.0.1换成它。同时要在代理客户端里打开允许局域网连接,并确认 Windows 防火墙没有拦截这个端口。主机地址在重启后可能变化,需要重新查看。
Docker 容器里的道理相同:容器内的 127.0.0.1 是容器自己。需要让容器里的工具走宿主机代理时,做法见 Docker 代理设置。
判断这类问题有一个直接的办法:在出问题的那个环境里执行 curl -I -x http://代理地址:端口 https://www.google.com。-x 是让 curl 这一次请求使用指定的代理。能返回响应头,说明这个地址和端口在当前环境里是通的,再把同样的地址写进环境变量即可;提示连接被拒绝或超时,说明地址本身就不对,和工具无关。
常见问题
网页版能用,命令行工具却连不上,是账号问题吗?
多数情况不是。网页走系统代理,命令行工具走终端环境,两者是两条路。先按上面的方法给终端设置代理或开启 TUN,再判断其他可能。
设置了 all_proxy 为 socks5 地址,为什么不生效?
不是所有命令行工具都支持 SOCKS 代理。Claude Code 的文档明确说明不支持 SOCKS,需要改用 HTTPS_PROXY 并填写 http:// 开头的地址,或者改用 TUN 模式。
在远程服务器上通过 SSH 运行这些工具,代理该设在哪里?
工具在哪台机器上运行,请求就从哪台机器发出。在远程服务器上运行,用的是服务器的网络,本地电脑上的代理客户端帮不上忙,需要在服务器那一侧解决网络问题,并确认服务器所在地区符合服务条款。
长任务中途断了,已经做完的修改会丢吗?
已经写入磁盘的文件修改不会因为网络断开而消失。丢的是当时正在生成的那一步。恢复会话后,让工具先检查当前文件状态再继续即可。养成用 git 提交阶段性成果的习惯,可以把损失降到最低。
在 WSL 里把代理设成 127.0.0.1 为什么连不上?
默认网络模式下 WSL 是独立的虚拟机,127.0.0.1 指向 WSL 自己,而代理客户端在 Windows 上。可以在 Windows 的客户端里开 TUN 模式,或者启用 WSL 的镜像网络模式,或者把地址换成 Windows 主机的地址并在客户端里允许局域网连接。
代理地址需要写 http:// 前缀吗?
需要。环境变量里的代理地址要写成完整的形式,包含协议、地址和端口,例如 http://127.0.0.1:7890。省略前缀会被当成格式错误。即使要访问的是 HTTPS 网站,本地代理的地址前缀一般也是 http://,它表示的是连接本地代理所用的协议。
环境变量设好了,后台任务或编辑器扩展里还是连不上怎么办?
说明那些进程没有继承到终端里设置的变量。把代理写进工具自己的设置文件,或者在编辑器扩展的设置里填写环境变量,这样从任何地方启动都会生效。嫌逐处设置麻烦的话,改用 TUN 模式一次解决。
接下来看什么
图形界面的编辑器另有一套设置,见 Cursor 代理设置与连接失败排查;反复出现验证或请求过多提示的网络原因,见 AI 工具频繁验证的原因。
本文中的套餐与价格整理自公开资料,核对日期为 2026年11月14日,未经本站实测,购买前请以官网为准。整理方法见这里。
接着读
ChatGPT 反复验证、Too Many Requests 原因:网络角度解释
从网络角度解释 ChatGPT 反复验证、Too Many Requests 的原因:共享 IP 请求密集、IP 频繁切换、数据中心 IP 信誉等,并说明固定节点、换同地区节点、减少并发等做法,账号与地区政策以官方为准。
Cursor 代理设置教程:Cursor 连接失败、对话中断的原因与排查顺序
Cursor 代理设置与 Cursor 连接失败排查:如何在设置里配置 http.proxy,什么时候改用 TUN 模式,长连接为什么会被节点自动切换打断,并给出一套从易到难的排查顺序。
Docker 代理设置教程:拉取镜像、构建镜像、容器内三种情况分别怎么配
Docker 代理设置分三种场景:docker pull 超时要给守护进程配代理,构建镜像时用 build-arg 传入,容器运行时用环境变量或 config.json。附各场景命令与 127.0.0.1 不通的原因。
GitHub 访问慢、git clone 失败怎么办:git 代理的正确写法
GitHub 访问慢、git clone 失败的解决办法:常见报错含义,git 代理在 HTTPS 与 SSH 下的区别,只对 github.com 生效的写法,SSH 走代理的思路,以及 release 下载慢的原因。