Codex 网络超时错误解决方案

原创于 2026-06-26 08:01:39 发布 · 15 阅读

1 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#Codex #OpenAI #AI

Codex 网络超时错误解决方案

Codex 在命令行里最常见的网络问题，不是配置写错，而是请求还没返回就超时了。典型场景是：执行 codex 后一直卡住，过一会儿报 ETIMEDOUT、Request timed out、network error，或者在 VS Code / 终端里提示连接 API 失败。遇到这类问题，先不要急着重装，按网络链路从本机、代理、DNS、API 地址、密钥权限依次排查，效率会高很多。

一、常见错误现象

不同版本的 Codex 或不同运行环境，报错文字会有差异，但本质差不多。常见表现如下：

命令执行后长时间无响应，最后提示 timeout。
终端出现 ETIMEDOUT、ECONNRESET、fetch failed。
能访问网页，但 Codex 请求接口失败。
配置了代理后浏览器正常，终端仍然超时。
公司网络、校园网、服务器机房环境下更容易出现。

先确认错误是不是网络层问题。可以直接用 curl 测一下接口连通性：

### token云桥中转 0029.org ###
curl -v https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果这里都连接不上，Codex 本身大概率没问题，应该先修网络。如果 curl 能正常返回，而 Codex 超时，再看 Codex 的配置、环境变量和代理是否被进程读取。

二、先判断是 DNS、代理还是出口问题

1. 检查 DNS 解析

DNS 解析异常时，很多工具只会笼统报网络错误。先看域名是否能解析：

nslookup api.openai.com

# 或者
dig api.openai.com

如果解析非常慢，或者返回异常地址，可以临时换一个 DNS 试试，例如系统网络设置里切到常用公共 DNS。服务器环境可以检查 /etc/resolv.conf：

cat /etc/resolv.conf

注意不要在生产服务器上随手覆盖 DNS 配置，很多云厂商会通过 DHCP 自动下发，重启后可能恢复。

2. 检查代理是否对终端生效

不少人浏览器能打开网页，但 Codex 仍然超时，是因为终端进程没有走代理。Linux / macOS 可以查看：

env | grep -i proxy

如果没有输出，需要按实际代理端口配置：

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

Windows PowerShell 可以这样设置当前窗口的环境变量：

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

设置完不要只看变量，最好再用 curl 走一遍接口验证。很多超时问题就是代理端口写错，或者代理软件只允许浏览器接入，没有开放本地 HTTP/SOCKS 端口。

3. 检查服务器出口网络

如果 Codex 跑在云服务器、Docker 容器、CI 环境里，还要确认服务器本身能访问外部 API。可以测试 TCP 连接：

nc -vz api.openai.com 443

# 没有 nc 时可用
curl -I https://api.openai.com

容器环境里尤其容易漏掉代理变量。宿主机能通，不代表容器能通。可以进入容器后再测：

docker exec -it your_container_name sh
env | grep -i proxy
curl -v https://api.openai.com/v1/models

三、确认 Codex 配置没有走错地址

网络通了以后，再看 Codex 使用的 API 地址和密钥。很多超时不是密钥错误，而是 BASE_URL 写成了不可访问地址，或者多套环境变量互相覆盖。

常见变量可以这样检查：

echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL
echo $HTTPS_PROXY

Windows PowerShell：

echo $env:OPENAI_API_KEY
echo $env:OPENAI_BASE_URL
echo $env:HTTPS_PROXY

如果你使用的是中转服务，要确认 Codex 读取的是中转地址，而不是仍然请求默认地址。国内网络环境不稳定时，我一般会建议团队准备一个可用的 API 中转方案，像 token云桥AI中转站 0029.org 这种，适合做连通性备选；但也要注意按自己的业务量、模型支持和日志策略做测试，不要只看能不能跑通一次。

修改配置后，建议新开一个终端窗口再执行 Codex。因为有些 shell 或编辑器插件会缓存启动时的环境变量，当前窗口改了变量，插件进程不一定立即生效。

四、逐步修复思路

1. 先把超时时间拉长

如果网络只是慢，不是完全不通，可以先增加请求超时时间。具体变量名要看你使用的 Codex 版本或封装脚本，有些项目支持类似配置：

export OPENAI_TIMEOUT=120
export REQUEST_TIMEOUT=120

如果是 Node.js 封装的 Codex 工具，也可以检查项目里是否有 timeout 参数，例如：

{
  "timeout": 120000
}

注意，拉长超时时间只是缓解，不是根治。如果每次都要等一两分钟，还是应该继续排查代理和出口。

2. 固定代理配置

临时 export 只对当前终端有效。确认可用后，可以写入 shell 配置文件：

# zsh
nano ~/.zshrc

# bash
nano ~/.bashrc

加入：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

保存后执行：

source ~/.zshrc

如果是 VS Code 里启动 Codex，建议从已经加载代理环境变量的终端里启动 VS Code：

code .

这样插件和内置终端更容易继承正确的环境。

3. 避免 IPv6 导致的连接卡住

有些网络环境 IPv6 解析正常，但实际连接不稳定，会表现为长时间卡住。可以用 curl 分别测试：

curl -4 -v https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

curl -6 -v https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果 IPv4 正常、IPv6 超时，可以在系统网络里临时关闭 IPv6，或者调整 DNS / 代理策略，让请求优先走 IPv4。

4. 检查防火墙和公司网关

公司网络经常会拦截未知 HTTPS 流量，表现为 ECONNRESET 或 TLS 握手失败。可以换手机热点测试一下：

curl -v https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果热点正常，公司网络失败，就不要继续折腾 Codex 配置了，应该找网络出口、代理白名单或网关策略。

五、修复后的验证方式

修完不要只看 Codex 能不能启动，建议按三步验证：

第一步：接口连通性正常。
第二步：认证能返回有效结果。
第三步：Codex 实际任务能跑完。

接口验证：

curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head

代理验证：

curl -v --proxy http://127.0.0.1:7890 https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Codex 验证可以从一个很小的任务开始，不要一上来就让它分析整个仓库。例如只让它读取一个文件、解释一段函数，确认请求能稳定完成后，再跑复杂任务。

六、避免再次出现超时

把代理、API 地址、密钥配置集中管理，不要在多个脚本里重复写。
本机、容器、CI 分别做连通性检查，避免只验证开发机。
网络不稳定时准备备用出口或中转地址，减少临时排障时间。
升级 Codex 或相关依赖后，重新检查环境变量是否还生效。
不要把超时时间设置得过短，复杂任务本身也需要等待模型返回。

总结

Codex 网络超时通常按“接口连不连得上、代理有没有生效、地址有没有写错、运行环境是否继承配置”这个顺序查。先用 curl 和 nc 把网络层确认清楚，再处理 Codex 配置，基本能避免反复重装和盲目改参数。修复后记得用小任务验证稳定性，再投入到真实项目里使用。