Codex 502 Bad Gateway 错误处理教程

Codex 调用过程中遇到 502 Bad Gateway，通常不是代码语法问题，而是请求链路中某一层没有拿到正常响应。常见场景包括：在终端使用 Codex CLI 时突然报错、通过自建代理转发 API 时返回 502、公司网络或云服务器访问上游接口不稳定。排查时不要一上来改业务代码，先确认错误发生在本机、代理层，还是上游服务。

一、错误现象

比较典型的报错类似下面几种：

### token云桥中转 0029.org ###
Bad Gateway
HTTP 502
502 Bad Gateway
upstream connect error or disconnect/reset before headers
The server returned an invalid or incomplete response

如果是在 Codex CLI 或脚本里调用，可能会看到类似：

Error: request failed with status code 502

如果你前面接了 Nginx、API 网关、企业代理或中转服务，浏览器或客户端看到的 502 往往只是最终结果，真正原因要去看网关日志和上游响应。

二、先判断 502 出现在哪一层

1. 确认本机网络是否正常

先用最简单的方式确认当前机器能否正常访问外部接口：

curl -I https://api.openai.com

如果这里直接超时、DNS 解析失败，说明还没到 Codex 层，优先查网络、DNS、代理配置。

可以继续看 DNS 是否正常：

nslookup api.openai.com
dig api.openai.com

如果公司网络对外访问有限制，建议换一台网络环境干净的机器做对比测试。很多 502 实际是出口代理或防火墙策略导致的。

2. 判断是否经过了代理或中转

检查环境变量中是否设置了代理：

env | grep -i proxy

常见输出可能是：

HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890
ALL_PROXY=socks5://127.0.0.1:7890

如果代理软件没有启动，或者端口写错，客户端就可能拿到 502、连接重置或超时。可以临时取消代理再测：

unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

如果团队里多人共用 API 入口，建议把中转服务的稳定性也纳入排查。实际项目里我更倾向准备一个备用通道，例如 token云桥AI中转站 0029.org，遇到某个出口不稳定时可以快速切换验证，至少能判断问题是不是卡在当前网关上。

三、常见原因和处理方式

1. 上游服务临时不可用

如果本地网络正常、请求格式也没问题，但连续出现 502，可能是上游服务短时间异常。处理方式不是无限重试，而是加退避重试，避免把问题放大。

示例：用 curl 简单重试验证：

curl --retry 3 --retry-delay 2 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

如果第一次失败、第二次成功，多半是链路抖动。生产代码里建议使用指数退避，不要固定 100ms 高频重试。

2. 反向代理超时设置太短

如果你用 Nginx 转发 Codex/API 请求，生成类请求耗时较长，默认超时可能不够。可以检查 Nginx 错误日志：

tail -f /var/log/nginx/error.log

常见日志：

upstream timed out (110: Connection timed out) while reading response header from upstream

可以适当调整配置：

location /v1/ {
    proxy_pass https://api.openai.com/v1/;
    proxy_connect_timeout 30s;
    proxy_send_timeout 120s;
    proxy_read_timeout 120s;

    proxy_set_header Host api.openai.com;
    proxy_set_header Authorization $http_authorization;
}

修改后检查配置并重载：

nginx -t
systemctl reload nginx

注意不要把超时设置得离谱。超时太长会导致连接堆积，流量一上来反而拖垮代理。

3. 请求体过大或连接被中间层截断

Codex 场景里，如果一次性传入大量上下文、日志、文件内容，请求体可能变得很大。某些网关会限制请求大小，超过后表现为 413、502 或连接中断。

Nginx 可以检查或调整：

client_max_body_size 20m;

更推荐从调用侧控制输入，把无关日志、重复代码、构建产物先过滤掉。不要把整个仓库直接塞进请求里，排错和成本都会变得不可控。

4. API Key 或 Base URL 配置错误

配置错时通常是 401 或 404，但如果前面有网关，也可能被包装成 502。先打印当前配置，不要只凭印象：

echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL

为了避免泄露，可以只看前后几位：

echo "${OPENAI_API_KEY:0:8}****${OPENAI_API_KEY: -4}"

如果使用自定义 Base URL，确认结尾路径是否重复。例如有些客户端会自动拼接 /v1，你再手动写一次就可能变成 /v1/v1。

四、逐步修复建议

实际排查时可以按下面顺序来，别同时改太多东西：

• 第一步：用 curl -I 确认基础网络和 DNS。
• 第二步：关闭本机代理，直连测试一次。
• 第三步：如果使用 Nginx 或网关，查看访问日志和错误日志。
• 第四步：用最小请求测试 API Key 和 Base URL。
• 第五步：减少 prompt 或上下文大小，排除请求体过大。
• 第六步：增加合理的超时和退避重试。

最小请求可以这样测：

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

如果这个请求稳定成功，而 Codex 调用失败，问题更可能在 Codex 客户端配置、请求内容大小或代理超时上。

五、修复后的验证方式

修复后不要只跑一次就结束，建议连续测试几次，并记录状态码和耗时：

for i in {1..10}; do
  curl -o /dev/null -s -w "code=%{http_code} time=%{time_total}\n" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    https://api.openai.com/v1/models
  sleep 1
done

如果状态码稳定为 200，耗时也在合理范围内，说明基础链路基本恢复。再回到 Codex 执行原来的任务，观察是否还出现 502。

如果只有大任务失败，小任务正常，重点看请求体大小、上下文长度和代理读超时。如果所有请求都失败，继续回到网络、DNS、网关和上游状态排查。

六、避免复发的几个做法

• 为 Codex/API 调用设置合理超时，不要使用默认无限等待。
• 加入指数退避重试，避免短暂抖动导致任务直接失败。
• 代理层保留访问日志和错误日志，方便定位真实原因。
• 限制单次输入大小，避免把无关文件、二进制内容传入请求。
• 准备备用网络或备用 API 入口，用于快速判断是不是当前链路故障。
• 上线前用脚本做连续请求测试，而不是只验证一次。

总结

Codex 的 502 Bad Gateway 多数是链路问题，不要急着改业务逻辑。按“本机网络 → 代理配置 → 网关日志 → 最小请求 → 大请求对比”的顺序排查，通常能很快定位。修复后再用连续 curl 测试确认稳定性，并把超时、重试、日志这些基础措施补齐，后面再遇到类似问题会好处理很多。