为什么你的Codex 重连到 5/5 才开始工作?理解重试、协议回退与代理链路

4 阅读9分钟

Codex 重连机制:区分重试、传输回退与代理路由

有些 Codex 用户会遇到这样的现象:发送第一条消息后,界面反复显示 Reconnecting…,计数接近 5/5 时才开始响应;同一会话接下来的交互又恢复正常。

一种常见解释是:前五次没有走代理,失败后才改用 HTTP 代理。这个判断把传输协议和网络路由混在了一起。要解释等待发生在哪里,需要分别看三个问题:客户端在重试什么,何时切换传输,以及不同传输是否使用了相同的网络配置。

01 “5/5”表示重试预算,不是启动流程

Reconnecting 表示客户端正在尝试恢复连接或响应流。计数描述恢复进度,并不代表模型需要完成五次连接才能开始工作。

OpenAI 的《Configuration Reference》区分了两项配置:request_max_retries 控制 HTTP 请求重试,默认值为 4;stream_max_retries 控制流式中断后的重试,默认值为 5。它们作用于不同阶段,不能混为一个次数。

这也意味着,仅凭 5/5 无法确定根因。连接建立失败、响应流中断或可重试的服务错误,都可能进入恢复逻辑。需要结合错误类型和后续传输变化判断。

重试次数也不等于总连接次数。首次尝试通常不算一次“重试”,客户端还可能包含预连接、认证恢复等步骤,因此不宜把界面计数直接当成抓包中的连接数量。

等待时间则由连接超时、重试间隔和服务端的退避提示共同影响。失败可能很快返回,也可能等到超时;重试之间还会暂停。因此,同样显示 5/5,不同环境中的实际等待可能相差很大。

02 一条可验证的路径:WebSocket 失败后回退到 HTTPS

对于“首轮等待较长、重连后恢复、后续交互正常”的现象,传输回退是一条值得检查的路径。

在 OpenAI Codex 的 0.166.0 版本中,模型提供方配置包含 WebSocket 支持能力;相应的流式错误处理代码会检查重试预算。满足条件、且仍能切换传输时,客户端转入 HTTP 路径,并产生如下提示:

Falling back from WebSockets to HTTPS transport.

随后重置相关重试计数,继续尝试请求。这一行为可以在该版本的流式重试实现中核对。它说明,部分启动等待来自失败恢复,而不是模型已经开始处理任务却迟迟没有输出。

有条件的传输回退:WebSocket 重试耗尽后改用 HTTPS

图 1:一条经过源码核对的恢复路径,不代表所有连接错误都会经历完整的五次重试。

另一个细节解释了为什么后续轮次可能变快:该版本将 HTTP 回退状态保留在当前会话中。一旦启用回退,后续轮次继续使用 HTTP,不必每次重新尝试 WebSocket。新会话的行为则需要重新判断。会话级传输状态

这是对现象的机制解释,具体故障仍要由日志确认。部分错误可以触发更早的切换,也有错误会直接终止;版本、提供方能力和启用的功能不同,恢复流程可能不同。不能把“固定五次后回退”当成所有 Codex 客户端的协议保证。

03 协议回退,不等于第五次才启用代理

讨论网络问题时,需要区分三个层次。

层次解决的问题典型内容
模型 API提交什么任务,接收什么结果Responses 请求、文本事件、工具调用
传输方式请求与事件如何交换WebSocket、HTTPS + SSE
代理路由数据经过哪条网络路径本地代理、企业网关、直连与绕过规则

SSE(服务器发送事件)是在 HTTP 响应中持续推送事件的方式。WebSocket 则建立持久、双向的消息通道。二者都可以携带模型生成过程中的文本和工具事件,也都可能经过代理。

模型 API、传输方式与代理路由的关系

图 2:切换 WebSocket 与 HTTPS/SSE,不等于切换“直连”和“代理”。

一种可能的故障是:HTTPS 流式请求正常,但 WebSocket 的握手、连接保持或转发失败。另一种可能是两条传输路径使用的网络库或配置不同,导致代理生效情况不一致。这些都是需要验证的假设,界面上的重试次数无法独立证明其中任何一种。

还要区分代理中的 CONNECT 方法。它常用于建立通向目标服务的隧道,和界面的 Reconnecting 计数属于不同层次。“走 HTTP 代理”也不意味着请求正文在使用普通明文 HTTP。

因此,更准确的排查问题是:WebSocket 路径是否失败,回退后的 HTTPS 路径是否成功,两者分别经过了什么网络配置。把这三个问题分开,才能确定应修复代理、网关还是客户端配置。

04 编码 Agent 为什么需要 WebSocket

编码任务通常包含多轮模型与工具交互:模型读取文件、提出修改、运行测试,再根据结果继续处理。每轮都需要交换新的输入和执行结果,传输开销会在长调用链中累积。

OpenAI 在《WebSocket Mode》中说明,Responses API 的 WebSocket 模式适合工具调用密集的工作流。持续连接结合增量输入,可以减少多轮衔接的开销;请求仍使用 Responses 的语义,以 response.create 事件提交。

收益来自传输方式与服务端状态管理的配合。它不意味着 HTTP 每轮都必须重新握手、传输完整历史,也不意味着只有 WebSocket 才能流式输出。

HTTP 可以复用连接,SSE 可以持续推送响应。OpenAI 的《Conversation state》也给出了 HTTP 模式使用 previous_response_id 延续响应链的方式。因此,“HTTP 无状态,所以每轮必须重发全部上下文”并不成立:应用层可以自行管理状态。

WebSocket 的连接内缓存有助于低延迟续接,但连接断开后仍需恢复上下文。性能优势依赖可用的网络链路;如果握手持续失败,等待重试的时间就可能超过原本节省的传输时间。

05 排查顺序:先确认链路,再修改配置

先记录现象发生在哪个阶段

区分首条请求、长时间空闲后和执行中断三种情况。首轮失败、后续正常,值得检查会话级回退;已有输出后断流,则还要看中间设备的超时、服务错误或网络波动。

同时记录客户端类型、版本、登录方式和实际使用的 Provider(模型提供方)。桌面端、CLI(命令行工具)、IDE(集成开发环境)插件和远程环境,不一定继承相同的环境变量或代理设置。

日志中若出现明确的 WebSocket 失败及 HTTPS 回退提示,可以据此定位传输切换。若显示认证失败、配额或证书错误,就应先处理对应问题,不能一律归结为 WebSocket。

再核对进程实际使用的代理

浏览器能联网,只能说明浏览器的路径可用;终端中的设置,也不会自动改变已经启动的桌面进程。

对于需要显式代理的 CLI 测试,可以在当前 PowerShell 会话中设置环境变量,再从同一会话启动 Codex:

# 示例端口,替换为本机代理实际提供的 HTTP 代理端口
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
codex

这里设置的是当前终端环境。要结合代理日志确认请求是否真正经过代理,还应检查 NO_PROXY 等绕过规则。桌面端、IDE、WSL(Windows 的 Linux 子系统)或远程主机,需要分别核对其进程环境;远程环境中的 127.0.0.1 指向远程机器自身。

最后用传输对照缩小范围

对于已经完整定义、且当前确实使用的自定义 Provider,可以依据官方配置参考,在原配置表中调整:

# 位于现有的 [model_providers.<实际提供方 ID>] 表内
supports_websockets = false

这是针对当前提供方的诊断性调整,不是应当无条件追加到配置顶层的通用开关。修改前保留原值,按客户端要求重启后对照观察。如果等待消失,说明 WebSocket 相关路径值得进一步排查;这仍不能单独确定是代理未生效还是网关转发失败。

使用内置提供方或桌面托管连接时,应按对应版本支持的配置方式处理,不要仅为测试传输就盲目切换 Provider。网上流传的其他开关也应先核对文档与配置层级,减少重试次数则不能修复本来不通的链路。

06 Claude Code 不能直接套用同一组重试次数

Claude Code 也需要处理流式请求和网络故障,但模型请求、MCP 连接及远程会话属于不同通道,不能用其中一条通道的重试次数推导整个产品。

Anthropic 的《Streaming messages》明确说明,Messages API 使用 SSE 流式返回文本、工具调用和思考增量。仅凭 Claude Code 具备 WebSocket 相关功能,无法推导其全部模型交互都是“WebSocket 下行、HTTP 上行”的固定结构。

其《Enterprise network configuration》也明确支持标准代理环境变量,并说明桌面托管连接等场景的配置作用域。排查时应检查具体通道、运行环境和版本,而不是预设它与 Codex 共享相同的“五次回退”机制。

07 结语

Codex 重连到 5/5 后开始工作,可能对应 WebSocket 重试耗尽、切换 HTTPS 后恢复的路径。会话级回退状态还能解释部分“第一轮慢,后续正常”的现象。

确定原因仍需要错误信息、传输变化和代理日志共同支持。重试计数描述恢复过程,传输回退决定如何交换数据,代理配置决定数据经过哪里。将这三个层次分开,才能把反复等待转化为可验证、可修复的问题。