AI 与开发工具网络

Claude Code 代理设置、Codex CLI 代理:TUN 与长任务断连

更新于 · 约 13 分钟读完 · 登机口编辑整理

先说明边界

这篇只讲网络层面的设置:流量怎么走代理、为什么会断、怎么排查。各家 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 反复变化也容易触发服务端的安全检查。

处理步骤:

  1. 在客户端代理页找到 AI 流量所在的分组(机场常会单独建一个 AI 分组,没有就是主分组);
  2. 把它从「自动选择」「故障转移」改为手动选定的一个节点;
  3. 跑一个较长的任务,观察是否还断;
  4. 稳定之后不要再频繁更换。

晚高峰线路拥堵。 公网线路在晚上丢包上升,长连接首当其冲。如果只有晚上断、白天正常,问题在线路,客户端怎么设置都解决不了,可以看晚高峰网速慢的原因。

电脑休眠和网络切换。 合上笔记本、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 列出公司内网域名,避免访问内部代码仓库时被送去代理。

公司设备上的网络策略由公司决定,改动之前先确认符合所在单位的规定。

排查清单

  1. 在同一个终端里执行 curl -I https://www.google.com,能返回响应头说明终端已经走上代理;
  2. 不通:检查端口号、客户端是否运行、节点是否可用;
  3. curl 通但工具不通:确认填的是 HTTP 代理而不是 SOCKS,确认是在设置变量的那个窗口里启动的;
  4. 能用但经常断:固定节点,换时段对比;
  5. 报证书错误:按上一节处理,不要关闭校验;
  6. 都正常却仍报错:查看服务方的状态页,可能是服务端问题。

选线路的思路可以参考 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。

有三种处理办法:

  1. 在 Windows 的代理客户端里开 TUN 模式。 WSL 的流量从 Windows 出去时会被一并接管,WSL 里面什么都不用设置。这是最省事的办法。
  2. 让 WSL 使用镜像网络模式。 较新的 Windows 版本支持这种模式,开启后 WSL 和 Windows 共用网络,127.0.0.1 可以直接访问到 Windows 上的代理端口。具体开启方式见微软的 WSL 文档。
  3. 把代理地址指向 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日,未经本站实测,购买前请以官网为准。整理方法见这里。

接着读