AI 工具AI 工具 · 约 11 分钟
Codex CLI 终端代理设置:在终端里怎么走代理
Codex CLI 终端代理设置:Codex CLI 连不上,九成是因为终端程序不读系统代理。办法和其他命令行工具一样:要么给终端设置代理环境变量,要么在代理客户端里打开 TUN。这篇把四个代理变量各自管什么、怎么写进配置随时开关、怎么验证,以及 Codex 调用 npm、git 时的网络问题一次讲清。
Codex CLI 终端代理设置,先说结论:和所有命令行工具一样处理
Codex CLI 是 OpenAI 出的命令行编程助手,在终端里运行。它连不上服务端的原因,和 git、npm、curl 连不上是同一个:命令行程序默认不读系统代理。
代理客户端里打开的“系统代理”只对浏览器和多数图形界面软件有效。
解决办法只有两类:
- 环境变量。在终端里设置
HTTPS_PROXY、HTTP_PROXY(必要时加上ALL_PROXY),指向代理客户端的本地端口。只影响这个终端以及从它启动的程序。 - TUN 模式。在代理客户端里打开 TUN,所有程序的流量都被接管,终端不需要做任何设置。
本文以环境变量为主线展开,因为它对所有命令行工具通用,学会一次以后哪儿都能用;TUN 部分讲它适合在什么时候替代环境变量。
原理层面的区别见 TUN 模式与系统代理。
各 AI 服务有自己的官方支持地区和使用条款,是否可以使用、如何登录和付费,以官方说明为准,请遵守其条款。
本文只讲终端的网络配置,账号注册、订阅付款和账号风控都不在本文范围。
四个代理变量各管什么
这套变量不是哪个软件发明的,而是类 Unix 系统里沿用多年的约定,绝大多数命令行工具和编程语言的网络库都会去读。它们的分工如下:
| 变量 | 作用 | 常见写法 |
|---|---|---|
HTTPS_PROXY | 访问 https 开头的地址时用哪个代理。Codex、包管理器、git 走的几乎都是这一项 | http://127.0.0.1:7897 |
HTTP_PROXY | 访问明文 http 地址时用哪个代理 | 同上 |
ALL_PROXY | 兜底:没有专用变量时使用,也被部分工具用来指定 SOCKS 代理 | socks5://127.0.0.1:7897 或同上 |
NO_PROXY | 哪些地址不走代理,用逗号分隔 | localhost,127.0.0.1 |
容易困惑的几个点:
- 变量名的 HTTPS 和值里的 http 不是一回事。变量名说的是“目标网站是什么协议”,值里的
http://说的是“你和本地代理端口之间用什么协议沟通”。代理客户端的本地端口一般提供 HTTP 代理,所以HTTPS_PROXY=http://...是正确写法,不是笔误。 - 大小写都有人用。有的工具只认小写,比如 curl 对明文 http 只看
http_proxy;有的工具两种都认。最保险的做法是大写、小写各设一遍。 - 端口以客户端显示的为准。Clash 系客户端通常有一个“混合端口”,同时接受 HTTP 和 SOCKS 请求,下文用 7897 举例。你的客户端设置页里写的是多少,就填多少。
- SOCKS 不一定被支持。不是每个程序都能用 SOCKS 代理,所以
HTTPS_PROXY里优先填 http 开头的地址;ALL_PROXY写 socks5 是给认得它的工具准备的。
三种 shell 的写法
先在当前窗口里临时设置,确认能用了再考虑长期生效。
macOS、Linux(zsh、bash)
export HTTPS_PROXY=http://127.0.0.1:7897export HTTP_PROXY=http://127.0.0.1:7897export ALL_PROXY=socks5://127.0.0.1:7897export NO_PROXY=localhost,127.0.0.1
需要小写版本的,再把上面四行的变量名换成小写写一遍。取消时用 unset HTTPS_PROXY 这样的命令逐个清掉。
Windows PowerShell
$env:HTTPS_PROXY="http://127.0.0.1:7897"$env:HTTP_PROXY="http://127.0.0.1:7897"$env:NO_PROXY="localhost,127.0.0.1"
取消用 Remove-Item Env:HTTPS_PROXY。Windows 的环境变量名不区分大小写,设一遍即可。
Windows 命令提示符
写法是 set HTTPS_PROXY=http://127.0.0.1:7897,等号两边不要留空格。命令提示符和 PowerShell 的变量互不相通,在哪个窗口里运行 Codex,就在哪个窗口里设。
部分代理客户端的托盘菜单里有“复制终端代理命令”一类的功能,点一下就能得到适合当前系统的整段命令,端口也是对的。
不同客户端和版本里名称和位置略有不同,找不到就按上面手写。
写进配置,随时开关
每次开终端都手敲几行太麻烦,但让代理变量永远生效也有坏处:代理客户端一旦没开,所有命令行工具都会连接失败,而且你未必第一时间想到原因。
比较顺手的做法是写两个开关命令。
- 打开 shell 的启动文件zsh 是用户目录下的
.zshrc,bash 通常是.bashrc。PowerShell 可以用$PROFILE变量查看配置文件的位置。 - 定义开启命令在 zsh 或 bash 里写一个函数,比如叫
proxy_on,函数体就是上一节的几行 export。 - 定义关闭命令再写一个
proxy_off,函数体是对应的 unset。 - 重新加载新开一个终端,或者执行
source ~/.zshrc让配置生效。 - 养成习惯要用 Codex 前先敲
proxy_on,用完不管也行,关掉窗口就失效了。
如果你的工作几乎全靠终端、代理客户端也一直开着,直接把 export 写进启动文件也可以。
只要记住一条:哪天所有命令行工具同时报连接错误,先看看代理客户端是不是没开。
怎么验证终端已经走了代理
设置完不要直接启动 Codex 试错,先用下面的方法确认网络这一层是通的。这样出了问题,你能分清是网络的事还是 Codex 自己的事。
- 看变量macOS 和 Linux 执行
env | grep -i proxy,PowerShell 执行Get-ChildItem Env:*PROXY*,确认输出里是你刚设的地址和端口。 - 用 curl 访问服务地址执行
curl -I加上 OpenAI 官网的地址,能拿到响应头就说明链路通了。加上-v会打印出 curl 是否使用了代理、连向哪个地址。Windows 的 PowerShell 里要写curl.exe。 - 核对出口用 curl 请求一个会返回来源 IP 的服务,再用浏览器访问同一个服务,两边的 IP 和地区应该一致,而且是你选中的那个节点所在地区。
- 看客户端的连接页启动 Codex 发一条指令,代理客户端的连接页里应当出现对应的连接,并显示命中的规则和节点。
Codex 连接的主要是 openai.com 和 chatgpt.com 这两个后缀下的地址,具体用到哪些以你在连接页里实际看到的为准。
如果连接页里一条相关记录都没有,说明流量根本没进客户端,回头检查变量;有记录但走了直连或者香港节点,就是规则的问题,按 ChatGPT 网络设置 里的方法把这些域名指向手动选择的 AI 策略组。
什么时候改用 TUN
环境变量的局限在于“只对读它的程序有效”。遇到下面几种情况,TUN 更省心:
- 工具不读变量。有些程序有自己的网络栈或自己的代理配置项,不看环境变量。尤其是部分基于 Node.js 的工具,是否读取代理变量取决于它用的网络库和运行时版本,不能想当然。
- Codex 会调用很多子命令。它在工作中可能运行包管理器、git、测试脚本,每个工具的代理规则都不一样,逐个配置很费劲。TUN 一次接管全部。
- 需要 sudo。用
sudo运行的命令默认不继承你的环境变量,TUN 不受这个影响。 - 容器和虚拟机。本机的 TUN 能否接管容器流量和具体网络模式有关,但至少比给每个容器传变量省事,配完同样要验证。
反过来,下面几种情况环境变量更合适:公司电脑没有管理员权限、不能装虚拟网卡;和公司 VPN 共存时 TUN 冲突;只想让某一个窗口走代理,其他程序保持原样。
开 TUN 时有两件事别忘:保持规则模式,不要为了“保险”切到全局;让客户端接管 DNS,否则可能出现个别域名解析异常,见 DNS 设置与 DNS 泄漏。
Windows 和 Mac 上的具体开法见 Windows 怎么用机场 和 Mac 怎么用机场。
Codex 调用的子命令:npm、git、pip
Codex 对话本身能通,不代表它执行的命令也能通。下面是最常见的几个工具和它们的代理习惯:
| 工具 | 是否读代理环境变量 | 另外要知道的 |
|---|---|---|
| curl | 读,明文 http 只认小写变量 | 最适合拿来验证链路 |
| git(https 远程) | 读 | 也可以用 git 自己的 http.proxy 配置;ssh 方式的远程不走这些变量 |
| npm | 读,作为它代理配置的默认值 | npm 自己的 proxy、https-proxy 配置优先;用国内镜像时不需要代理 |
| pip | 读 | 也可以在命令里用 --proxy 参数单独指定 |
一个容易忽略的点:不是所有命令都需要走代理。
项目如果配置了国内的软件包镜像,那些请求直连更快,硬塞进代理反而绕远。
环境变量对所有 https 请求一视同仁;TUN 模式则由规则决定,国内地址自动直连,这是 TUN 在开发场景里的另一个好处。
沙箱也可能拦住网络
Codex 执行命令时会放在自己的沙箱里,并且有一套审批机制。按官方文档的说法,某些沙箱模式下命令默认不能访问网络。
如果你看到 Codex 对话正常、唯独它运行的安装或下载命令失败,而你在同一个终端里手动执行同样的命令却能成功,那多半是沙箱的限制,不是代理的问题。
具体怎么调整审批和沙箱模式,以官方文档为准,这属于 Codex 自身的安全设置。
常见报错按这个顺序查
| 现象 | 网络侧的常见原因 | 先做什么 |
|---|---|---|
| 一启动就报连接失败或超时 | 终端没走代理,或变量指向的端口没有客户端在监听 | 看变量、确认客户端开着、用 curl 测 |
| 提示地区不支持 | 出口落在不在支持列表里的地区,常见是香港 | 看连接页里相关域名走的节点 |
| 登录卡住不返回 | 本机回调地址被送进了代理 | 设置 NO_PROXY,关浏览器代理扩展 |
| 任务中途断开 | 策略组自动切换、晚高峰丢包、电脑休眠 | 策略组改手动选择,固定节点 |
| 对话正常,安装命令失败 | 子命令没拿到代理,或沙箱禁止联网 | 手动执行同一命令对比 |
| 证书错误 | 公司网络在中间做了 HTTPS 检查 | 向公司 IT 确认,不要关掉证书校验 |
排查时一次只改一样东西。地区类提示的处理见 AI 工具提示地区不支持;浏览器能上、终端不行这一类更通用的情况,见 浏览器能上、软件不走代理。
远程服务器上的 Codex
通过 SSH 登录到服务器上运行 Codex,请求是从服务器发出的,你本机的代理设置对它不起作用,要看服务器所在的网络环境。
另外,Codex 也有在官方服务器上执行的云端任务,那部分同样不经过你的本地网络。
本文讨论的都是在你自己电脑的终端里运行的情况。
在编辑器里用 Codex 时
不少人是在 VS Code、Cursor 这类编辑器里使用 Codex 的,要分清两种情况:
- 在编辑器的内置终端里运行 Codex CLI。内置终端启动的是你的 shell,会加载
.zshrc等启动文件,所以写在里面的变量和开关函数同样生效。编辑器设置里的http.proxy不会传给终端里的程序。 - 使用 Codex 的编辑器扩展。扩展的请求从编辑器进程发出,是否遵循编辑器的代理设置,以官方文档为准。最省事的办法是开 TUN,让编辑器和终端都不用单独配置。
macOS 上还有一个细节:从程序坞或启动台打开的图形程序,不会读取 .zshrc 里的变量。所以“在终端里 Codex 正常、扩展却连不上”并不矛盾。
编辑器这一层的设置见 Cursor 网络设置 和 Copilot 网络设置。
几件不建议做的事
- 不要关掉证书校验。遇到证书错误时,网上常见的建议是设置
NODE_TLS_REJECT_UNAUTHORIZED=0。这会让 Node.js 程序不再核对对方身份,任何中间人都能冒充服务器。公司网络里的证书问题,应当由 IT 提供公司根证书。 - 不要把代理变量写进项目文件。放进仓库的脚本或配置会被同事拉下来,端口和他们的不一样,还可能暴露你的使用习惯。代理设置留在自己的 shell 配置里。
- 不要用别人提供的“中转接口”。把 API 密钥或登录凭据交给来路不明的转发服务,等于把账号交出去。
- 不要在任务进行中切换节点。想换节点,等这一轮任务结束;长任务前先确认策略组是手动选择。
选机场时看什么
给 Codex 这类终端工具用,机场要满足三条:
- 支持通用客户端。要有本地代理端口、能开 TUN、能自己加分流规则,这些都是通用客户端的能力。只能用官方客户端的机场,先问清楚有没有本地端口可用。可以在 Clash 机场推荐 里筛选。
- 支持地区有多个节点。美国、日本、新加坡至少两个地区,每个地区能找到一主一备。
- 线路稳。编程助手的一轮任务可能持续很久,线路质量比带宽更重要。
公开资料标注支持 ChatGPT、同时支持通用客户端的有 BoostNet、二猫云、悠兔、宇宙云、暮光网络 等;WgetCloud 的公开资料建议用优质档及以上跑 AI 工具。
这些都是公开资料标注,本站没有逐家验证,需自行验证:先买最短周期,配好后在晚高峰让 Codex 跑一个较长的任务,看中途是否断开。
更多候选见 AI 机场推荐。
一句话:Codex 走代理,靠的是终端的环境变量或 TUN,不是浏览器里的那个系统代理开关。
参考来源
本文涉及的客户端功能、协议和服务规则,以下面的官方文档和项目页面为准:
- openai/codex 官方仓库(GitHub):Codex CLI 项目主页与安装
- OpenAI 文档:Codex CLI:Codex CLI 官方用法
- OpenAI 文档:Agent approvals & security:沙箱默认限制网络访问
- everything curl:Proxy environment variables:HTTPS_PROXY、ALL_PROXY 等变量的含义
常见问题
Codex CLI 登录时浏览器打开了,但终端一直等不到结果,怎么回事?
登录流程通常是浏览器完成授权后,把结果交回本机上的一个临时地址。
如果你设置了代理变量却没有把本机地址排除,或者浏览器扩展拦截了这个跳转,终端就收不到回调。
先加上 NO_PROXY=localhost,127.0.0.1,关掉浏览器里的代理扩展再试一次。
HTTPS_PROXY 和 ALL_PROXY 都要设吗?
建议 HTTP_PROXY 和 HTTPS_PROXY 一定设,ALL_PROXY 按需。多数程序优先看前两个;ALL_PROXY 是兜底,部分工具在没有找到专用变量时才读它。
三个都指向同一个本地端口最省心,排查时也不容易乱。
为什么 Codex 能对话,但它执行的 npm install 失败了?
可能有两个原因。一是子命令没拿到代理变量,比如通过 sudo 运行,或者那个工具有自己的代理配置。
二是 Codex 自身的沙箱限制了命令的网络访问,这和代理无关,属于它的安全设置,按官方文档调整审批或沙箱模式即可。
用 Windows 的 PowerShell,设置变量的写法有什么不同?
PowerShell 用 $env:HTTPS_PROXY="http://127.0.0.1:端口" 这种写法,只对当前窗口有效。想长期生效,在系统的环境变量设置里添加,或写进 PowerShell 的配置文件。另外在 PowerShell 里测试时用 curl.exe,避免调用到同名的别名。
TUN 模式和环境变量能一起开吗?
能,流量会先被环境变量送到本地端口,再由客户端按规则处理,TUN 只是兜住那些不读变量的程序。
但排查问题时最好先只留一种,确认是哪一层出的错。两种做法的取舍可以参考 Claude Code 终端代理 里的对照表。
Codex CLI 用哪个地区的节点?
以 OpenAI 公布的支持国家和地区为准,美国、日本、新加坡、台湾通常在列表内,香港通常不在。
终端和浏览器最好落在同一个地区、同一个节点上,策略组用手动选择。详细取舍见 AI 工具用哪个地区的节点。
遇到证书错误,能设置 NODE_TLS_REJECT_UNAUTHORIZED=0 解决吗?
能让报错消失,但不该这么做。它会让程序不再核对服务器身份,任何中间人都可以冒充。
证书错误多见于公司网络对 HTTPS 做了检查,正确做法是向 IT 要公司根证书并按规定配置。
终端里的 Codex 正常,编辑器扩展里的 Codex 却连不上?
两者走的是不同进程。终端读环境变量,扩展跟随编辑器的网络设置;macOS 上从程序坞打开的编辑器也不会读 .zshrc 里的变量。
给编辑器单独设置代理,或者直接开 TUN。