Make stream reconnect delay/backoff configurable in config.toml

Resolved 💬 4 comments Opened Mar 29, 2026 by constansino Closed May 16, 2026

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Hard-coded exponential backoff for retryable stream reconnects makes some provider setups unusable.

Today Codex exposes stream_max_retries, but not the reconnect delay strategy. The outer reconnect loop uses a fixed exponential backoff starting around 200ms and doubling on each retry, so by the time a session reaches the low teens it is already waiting many minutes between attempts.

That is a poor fit for providers / gateways that frequently fail with retryable transient errors but often recover after a few quick retries. One concrete case is OpenAI-compatible upstreams that may briefly return 403 Forbidden with an "insufficient balance / quota" message and then succeed again shortly afterward once the upstream gateway refreshes state or routes to a healthy backend.

In that setup, users can already raise stream_max_retries, but they cannot express the retry cadence they actually need. By retry 10+ the built-in exponential backoff dominates and the CLI can end up waiting far longer than the upstream outage itself.

Proposed behavior:

Keep the current default behavior for existing users.
Add provider-scoped TOML settings so users can choose the reconnect delay behavior explicitly.
Support at least:

a configurable base delay in milliseconds
a configurable backoff mode (exponential or fixed)

Example desired config:

[model_providers.custom]
stream_max_retries = 100
stream_retry_delay_ms = 500
stream_retry_backoff = "fixed"

That would allow the common "retry every 500ms" workflow without requiring a local patch.

I have a PR ready that implements exactly this shape while preserving the current default behavior.

View original on GitHub ↗

4 Comments

github-actions[bot] contributor · 5 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

#16096

Powered by Codex Action

constansino · 5 months ago

I have the patch implemented here:

What it adds:

[model_providers.custom]
stream_max_retries = 100
stream_retry_delay_ms = 500
stream_retry_backoff = "fixed"

I attempted to open the upstream PR as well, but GitHub's fork API is currently failing for openai/codex from this account (502 Server Error, followed by Repository is already being forked). As soon as GitHub successfully creates the canonical fork, I'll open the upstream PR and link it here.

etraut-openai contributor · 3 months ago

This feature hasn't received enough upvotes, so closing.

LeonidasZhak · 1 month ago

Request for reconsideration: support the built-in OpenAI provider, not only custom providers

Please reconsider reopening this issue, or explicitly track this requirement as part of #19821.

The scope is now broader than the original custom-provider use case. On the current macOS Codex Desktop bundle (codex-cli 0.144.2) using ChatGPT authentication and the built-in OpenAI provider, transient network interruptions still produce the user-visible Reconnecting... 1/5 through 5/5 sequence. The five attempts can be consumed too quickly to survive ordinary Wi-Fi, VPN, proxy, sleep/wake, or route transitions.

The documented retry controls do not solve this for normal Desktop users:

stream_max_retries, request_max_retries, and stream_idle_timeout_ms are provider-scoped.
The built-in openai provider ID is reserved and cannot be overridden.
Attempting to configure model_providers.openai.stream_max_retries is rejected with: Built-in providers cannot be overridden.

That leaves the mainstream ChatGPT-authenticated Desktop path with a hard-coded retry budget and cadence, even though the same knobs exist for custom providers.

Since this issue was closed for insufficient upvotes, #19821 has accumulated additional reports across platforms showing the same practical failure mode: Codex spends the complete 1/5–5/5 budget on a failing WebSocket path before a working HTTP/SSE fallback. This is evidence of an unresolved resilience and configurability gap, not merely a niche custom-gateway preference.

Requested behavior

Expose retry-policy configuration for the built-in OpenAI provider, while preserving current defaults for backward compatibility.
Allow users to increase the retry budget without defining a custom provider or changing authentication/billing paths.
Use bounded exponential backoff with jitter:

configurable initial delay
configurable maximum delay
configurable retry count
reset after a successful connection
honor server Retry-After when present

Retry only transient transport and retryable server failures; do not loop on deterministic authentication, authorization, or malformed-request errors.
Show the next retry delay and offer Retry now and Cancel.
For repeated WebSocket transport failures, use an early HTTP/SSE fallback or a short-lived circuit breaker rather than paying the full failing WebSocket budget on every turn.

A larger retry count without backoff risks hammering the same failing path. Exponential backoff without a cap or user-visible timing can make Codex appear hung. The reliable policy needs all three: a configurable retry budget, bounded backoff with jitter, and adaptive transport fallback.

Suggested acceptance criteria

A ChatGPT-authenticated Desktop/CLI user can configure the built-in provider's retry count and bounded backoff.
A regression test verifies increasing delays up to the configured cap, with jitter within documented bounds.
A regression test verifies that successful reconnection resets the backoff.
Non-retryable 4xx/authentication errors fail immediately.
Repeated WebSocket failures can transition to HTTP/SSE without exhausting every configured stream retry.
The UI reports the current attempt and approximate time until the next retry.

The request is not for unlimited retries. It is for a resilient, bounded, observable retry policy that standard Codex Desktop users can actually configure.