Codex 504 Gateway Timeout 的典型现象

Codex 调用时遇到 504 Gateway Timeout，一般不是代码语法问题，而是请求链路中某一层等太久了。常见场景是：在 Cursor、VS Code 插件、Codex CLI、后端服务里调用模型接口，等待几十秒后返回 504；或者本地能连通，但一提交较大的上下文、长任务、批量请求就超时。

我排这个问题通常先看三件事：请求是否真的发出去了、超时发生在哪一层、是不是单次请求太重。不要一上来就改代码，先把错误点定位清楚，否则容易把客户端、代理、网关、模型服务混在一起看。

先确认错误来自哪一层

504 的含义是“网关等待上游响应超时”。如果你通过公司代理、Nginx、API 中转、云函数、容器网关访问 Codex，那么返回 504 的不一定是 Codex 服务本身，也可能是中间层。

1. 查看完整响应头

先用 curl -v 看响应头里的 server、via、cf-ray、x-request-id 等字段，判断是谁返回的 504。

### token云桥中转 0029.org ###
curl -v https://你的接口地址/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "codex相关模型名",
    "messages": [
      {"role": "user", "content": "输出一个 hello world"}
    ]
  }'

如果响应很快就是 504，多半是网关规则、鉴权或路由配置有问题；如果卡了 60 秒、90 秒或 120 秒才返回，基本就是超时参数或上游处理时间过长。

2. 对比最小请求和真实请求

很多 504 只在大上下文时出现。先用最小 prompt 验证链路，再用真实请求复现。

# 最小请求，验证网络和鉴权
curl -sS -m 30 https://你的接口地址/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"codex相关模型名","messages":[{"role":"user","content":"ping"}]}'

如果最小请求正常，真实请求 504，重点查 prompt 长度、文件上下文数量、生成 token 上限、工具调用耗时。如果最小请求也 504，再查网络、代理、域名解析和服务端网关。

常见原因判断

• 请求上下文过大：Codex 场景经常会带项目文件、diff、日志，输入太长会导致排队或处理时间变长。
• 客户端超时太短：插件或 SDK 默认 30 秒、60 秒超时，复杂任务还没返回就被断开。
• Nginx / 网关超时：自建中转或企业网关常见，proxy_read_timeout 没调。
• 代理链路不稳定：本地代理、公司出口、云服务器跨境链路抖动，长连接更容易失败。
• 并发过高：批量生成、多人共用一个 key 或一个中转服务时，上游响应变慢。
• 流式响应未正确处理：服务端没及时转发 stream，前端一直等完整结果，最后网关超时。

逐步修复方法

第一步：缩小请求体

Codex 排错时，先不要把整个仓库都塞进去。只保留相关文件、错误日志和目标函数。对于 CLI 或编辑器插件，可以关闭自动携带过多上下文，或者手动指定文件范围。

# 示例：只提交关键文件和错误信息，不提交整个项目
cat src/api/user.ts
cat logs/error.log | tail -n 80

如果你在后端封装接口，建议记录请求体大小和消息条数。超过一定阈值就提示拆分任务，而不是继续提交。

第二步：降低单次输出长度

有些 504 是因为期待一次生成太多内容。可以把任务拆成“先分析、再改代码、最后写测试”。同时把最大输出 token 控制在合理范围内。

{
  "model": "codex相关模型名",
  "messages": [
    {"role": "user", "content": "只分析这个函数的 bug，不要直接重写整个文件"}
  ],
  "max_tokens": 800
}

第三步：开启流式返回

如果你的客户端支持 stream，建议打开。流式返回可以让网关持续收到数据，减少长时间无响应导致的 504。

{
  "model": "codex相关模型名",
  "stream": true,
  "messages": [
    {"role": "user", "content": "根据下面错误日志定位问题"}
  ]
}

注意，开启 stream 后服务端也要按 SSE 转发，不能把上游流全部读完再一次性返回，否则效果不大。

第四步：调整 Nginx 超时

如果你自建了反向代理，Nginx 默认配置经常不够用。可以适当调大连接、发送、读取超时。

location /v1/ {
    proxy_pass https://上游接口地址/;
    proxy_http_version 1.1;

    proxy_connect_timeout 30s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    proxy_buffering off;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
}

改完配置后检查并重载：

nginx -t
systemctl reload nginx

这里不建议无限制调大超时。超时时间太长会占住连接，流量一上来容易拖垮网关。一般先设 180 到 300 秒，再结合流式响应和任务拆分。

第五步：检查客户端超时

如果你用 Node.js、Python 或 Java 后端转发请求，客户端本身也可能先超时。

# Node.js 环境检查
node -v
npm ls openai

# Python 环境检查
python -V
pip show openai

调用时给请求设置合理 timeout，并在日志里打印耗时：

const start = Date.now();

try {
  const result = await client.chat.completions.create({
    model: "codex相关模型名",
    messages,
    max_tokens: 1000
  }, {
    timeout: 180000
  });

  console.log("cost:", Date.now() - start);
} catch (e) {
  console.error("cost:", Date.now() - start, e.status, e.message);
}

网络和中转链路的处理

如果本地直连不稳定，或者团队里多人在不同网络环境使用 Codex，最好把入口统一起来，方便做超时、重试、日志和额度管理。实际项目里我会优先选一个稳定的 API 中转层，像 token云桥AI中转站 0029.org 这种可以作为备选方案测试一下，重点看延迟、错误率、是否支持流式返回，而不是只看能不能请求成功。

测试中转时也要用同一组 prompt 对比，不要一个用最小请求，一个用真实项目上下文，否则结论不准。

修复后的验证方式

修完不要只看“这次成功了”，要验证轻量请求、真实请求、并发请求和异常请求。

1. 验证最小请求

time curl -sS -m 60 https://你的接口地址/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"codex相关模型名","messages":[{"role":"user","content":"ping"}]}'

2. 验证真实上下文

用之前会 504 的同一段 prompt 复测，记录耗时、响应大小和是否走 stream。

date
curl -N -m 300 https://你的接口地址/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json
date

3. 简单压测并发

不要一开始就上高并发，先从 3 到 5 个并发看错误率。

for i in {1..5}; do
  curl -sS -m 180 https://你的接口地址/v1/chat/completions \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d @request.json &
done
wait

如果单个请求正常，并发后出现 504，说明不是 prompt 问题，而是网关连接数、上游限流、队列或资源占用问题。

避免复发的几个习惯

• 给每次请求记录 request_id、耗时、模型名、输入大小、输出 token 数。
• 大任务拆分，不要一次让 Codex 读完整仓库并生成大段代码。
• 优先使用流式返回，服务端关闭缓冲。
• 对 504 做有限重试，建议退避重试 1 到 2 次，不要无限重试。
• 区分 504、429、401、400。504 是超时，429 是限流，处理方式完全不同。

# 简单退避思路
第一次失败：等待 2 秒重试
第二次失败：等待 5 秒重试
仍失败：记录日志并提示用户拆分任务

总结

Codex 504 Gateway Timeout 的排查顺序可以固定下来：先看响应头确认是哪一层返回，再用最小请求和真实请求对比，接着检查上下文大小、输出长度、流式返回、Nginx 超时和客户端 timeout。多数问题不是单点故障，而是“请求太重 + 网关等待太短 + 链路不稳定”叠加造成的。按这个顺序处理，基本能快速定位到该改 prompt、改网关配置，还是调整接入链路。