Codex 报 stream ended before terminal event，通常意味着什么

这类错误通常表示客户端期待收到完整的流式事件序列，但连接在最终完成事件之前结束。根因可能是上游断线、Nginx timeout、HTTP/2 重置，或者第三方兼容层只实现了“能流文字”，没有完整实现 Codex 需要的事件。

一、为什么会出现这个问题

• 错误可能由 Nginx、Cloudflare、应用网关、第三方平台或真正的模型上游任意一层返回。
• 代理 read timeout、buffering、连接复用等默认值并不适合 AI 长请求。
• 流式 SSE 在中间层被缓存、提前关闭或事件格式被改写。
• 只看客户端最后一行错误，无法判断真正的故障来源。

二、推荐的排查顺序

1. 确认错误来自哪一层

保留响应头、request id、Cloudflare Ray ID、Nginx access/error log 和应用日志，同一时间点对齐分析。

2. AI 路由单独配置

SSE、长文本、Agent、视频任务不要直接套普通网站的 timeout 和 buffering。对 /v1/ 等接口单独设置更容易维护。

3. 只对暂时性错误重试

502/503 等可以有限重试；401、403、参数错误等确定性问题不应该盲目重试。

三、可以直接复制的排查示例

location /v1/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
    proxy_set_header Connection "";
}

四、使用建议

如果普通非流式请求稳定、只有流式失败，就优先排查 SSE 事件和中间代理，而不是模型本身。