Fix Codex Reconnecting 1/5 Error: HTTP-SSE Guide

Abstract

OpenAI Codex Desktop users frequently encounter a repeating reconnect issue: after creating or resuming tasks, the client displays Reconnecting ... 1/5 through 5/5. After five retry attempts, the connection eventually succeeds, yet noticeable startup latency persists, while task logic itself can still complete normally. This article analyzes the underlying root cause sourced from Codex GitHub Issue #24045, explains the WebSocket‑to‑HTTP‑SSE fallback mechanism, and provides two complete actionable resolution workflows: automated remediation by AI Agent tools, and manual TOML configuration modification to force HTTP‑SSE transport. All configuration parameters, file paths and verification commands from original technical material are preserved. This article also discusses relevant network‑proxy engineering considerations for developers operating local AI‑agent clients together with external LLM endpoints. When developers manage mixed proxy and LLM access setups, an API gateway such as 4sapi can help standardize connection transport settings for local agent‑service traffic.

1. Symptom Description Of The Reconnect 1/5‑5/5 Fault

The fault manifests on Codex Desktop (ChatGPT Desktop agent client):
When users create brand‑new tasks or resume previously‑saved work sessions, sending the very first message triggers repeated reconnect status output. UI status cycles through Reconnecting... 1/5, Reconnecting... 2/5 up to Reconnecting... 5/5. After exhausting five retries, the client automatically falls back and establishes functional connectivity. Tasks execute correctly after this delay, but every new or resumed task pays this startup latency penalty.

Crucially: general internet connectivity itself is fully functional. The problem is isolated to WebSocket session establishment between local Codex Desktop and remote OpenAI Responses backend service. Once fallback completes to HTTP‑SSE streaming transport, all prompt‑response workflows work without further disruption.

From publicly logged Issue #24045 on the Codex GitHub repository, engineers documented the internal execution flow:

1. Codex Desktop initiates a WebSocket connection request toward OpenAI Responses backend service.
2. If WebSocket link establishment fails (due to firewall rules, proxy interference, TLS handshaking issues or network‑path restrictions), the client triggers built‑in retry logic.
3. It runs up to five sequential WebSocket reconnection attempts, showing the 1/5 to 5/5 progress indicator in the UI.
4. After five failed WebSocket retries, the client abandons WebSocket and transparently switches over to HTTP‑SSE (Server‑Sent Events) streaming transport channel.
5. Task processing proceeds normally over HTTP‑SSE, but users observe the multi‑second delay incurred by the five‑round retry cycle.

Common observable log sequence reproduced from community reports:

1. WebSocket connection timeout event occurs
2. Codex triggers automatic reconnect retries, status increments from 1/5 to 5/5
3. Client falls back to HTTP‑SSE streaming protocol
4. Agent task resumes and executes normally

This explains why end‑users still get correct outputs: only the WebSocket channel fails; the alternative HTTP‑SSE data path remains fully operational. The core annoyance is mandatory waiting time for every task startup.

2. Solution Option One: Automated Remediation Using AI Agent Tooling

Codex Desktop permits AI agent programs to read local disk configuration files and execute shell commands. You can hand the whole troubleshooting workflow directly over to Codex itself or another capable local‑execution AI agent.

Pass this article content plus the following prompt text to your local‑capable agent:

>
> Please read this document. First verify whether my Codex reconnect fault matches the phenomenon described in this material. If conditions match, follow the manual‑repair steps documented here: back‑up configuration files, complete configuration modification, and validate final results.

Because the config.toml user configuration file sits within the Windows user‑profile directory, file‑write operations require filesystem permission grants. After you approve access permissions, the agent can create backup copies, adjust TOML content and run validation checks. You will need to fully restart Codex Desktop after configuration changes take effect.

This automated path is suitable for developers who already trust their local AI agent with limited filesystem access rights. For operators who prefer full visibility over every configuration change, the manual TOML editing workflow in option two is recommended.

3. Solution Option Two: Manual Configuration To Enforce HTTP‑Only Transport

This workflow disables WebSocket usage for the OpenAI provider inside Codex Desktop, forcing the client to use HTTP‑SSE transport from the very beginning, skipping the five‑round WebSocket retry loop entirely. It consists of four distinct phases: back‑up existing configuration, adjust provider parameters, write new TOML segments, restart client and run verification diagnostics.

3.1 Locate And Back Up config.toml Configuration File

Codex Desktop stores user‑scope configuration inside the path:
%USERPROFILE%\.codex\config.toml

The Windows environment variable %USERPROFILE% resolves to the current logged‑on user’s home folder, normally C:\Users\<your‑windows‑username>. You can also open this file directly through the Codex graphical UI: open Codex Settings → navigate to Configuration tab → click the Open config.toml button.

>
> Important safety step: always make a backup copy before editing TOML configuration. Create a duplicate file suffixed .bak so you can restore original settings in case of syntax mistakes.

PowerShell backup command example:

Copy‑Item "C:\Users\<your‑windows‑username>\.codex\config.toml" "C:\Users\<your‑windows‑username>\.codex\config.toml.bak"

Git Bash backup command example:

cp "/c/Users/<your‑windows‑username>/.codex/config.toml" "/c/Users/<your‑windows‑username>/.codex/config.toml.bak"

Remember to replace <your‑windows‑username> placeholder with your actual local Windows account name before executing shell statements.

3.2 Modify Default model_provider Selection

Open config.toml with a plain‑text editor (Notepad, VS Code etc.). Locate the global model‑provider setting:

model_provider = "openai"

Change the value to point toward our new HTTP‑only provider definition:

model_provider = "openai_http"

3.3 Insert New openai_http Provider TOML Block

Insert this TOML table segment near the top of the configuration document, ahead of other existing [projects.*] or [plugins.*] sections.

[model_providers.openai_http]
name = "OpenAI HTTP only"
base_url = "https://chatgpt.com/backend‑api/codex"
wire_api = "responses"
requires_openai_auth = true
requires_websockets = false

The critical key here is requires_websockets = false. This parameter explicitly tells Codex Desktop never to attempt WebSocket connections for this provider, and exclusively use HTTP‑SSE streaming. Other existing model, plugin and project configuration blocks do not require modification.

3.4 Restart Codex Desktop And Validate Configuration

Fully quit Codex Desktop, including background resident processes. Re‑launch Codex Desktop and create a brand‑new test task.

You can also run built‑in diagnostic commands inside PowerShell to inspect loaded configuration state:

codex doctor --summary --ascii

Healthy expected output contains these two confirmation lines:

[ok] config     loaded
[ok] websocket  Responses WebSocket is not enabled for the active provider
[ok] reachability active provider endpoints are reachable over HTTP

After completing these steps, you should no longer observe the Reconnecting 1/5 ... 5/5 sequence when starting new tasks. If you still reproduce the reconnect sequence, double‑check TOML syntax validity, confirm that you restarted the full desktop application process, and verify you created a genuinely new test task. TOML files are extremely sensitive to misplaced brackets and indentation errors.

4. Roll‑back Procedure To Restore Original WebSocket‑Enabled Configuration

If you later wish to revert back to native WebSocket transport, you have two equivalent recovery paths.

Path A: edit config.toml manually:

1. Change the global provider pointer back:

model_provider = "openai"

1. Remove the custom [model_providers.openai_http] block you added earlier.
2. Save the file and fully restart Codex Desktop.

Path B: restore your pre‑modification backup file config.toml.bak. Copy the backup file and overwrite config.toml, then restart Codex Desktop. This completely discards all manual edits you made.

After roll‑back finishes, Codex Desktop will revert to original default behavior: it will first try WebSocket connections and trigger the 1‑to‑5 reconnect sequence whenever WebSocket paths get blocked.

5. Underlying Network‑Layer Analysis And Common Triggering Conditions

Why does this 1‑to‑5 reconnect bug appear for some users and not others? The root cause lies in WebSocket protocol traffic getting blocked or interrupted somewhere between Codex Desktop client and OpenAI remote Responses backend. HTTP‑SSE long‑lived HTTP streaming can pass through the same network path without failure.

Common triggering conditions for this failure:

1. Corporate or home firewall / security‑software rules that filter or throttle WebSocket upgrade handshakes, while permitting standard HTTPS traffic.
2. Intermediate HTTP proxy servers that do not correctly forward WebSocket upgrade headers, yet pass ordinary HTTPS requests normally.
3. TLS termination / man‑in‑the‑middle proxy tools that mishandle WebSocket connection state.
4. Partial ISP network‑path peculiarities that break WebSocket frames without interfering with regular HTTPS GET/POST traffic.

WebSocket and HTTP‑SSE are two distinct streaming transport implementations. Both can deliver real‑time LLM token streams, yet they behave differently when traversing intermediate network appliances. WebSocket initiates with an Upgrade: websocket HTTP header handshake; many older proxy devices lack full compliance for this flow. HTTP‑SSE operates purely over standard GET requests with text/event‑stream content‑type, which enjoys far broader compatibility with legacy network infrastructure.

Local‑agent developers often work with custom proxy layers and multi‑model access setups. When building local agent workflows that switch between multiple LLM backends, managing WebSocket enable‑disable flags for every client adds maintenance overhead. An API gateway can centralize transport‑related configuration, helping abstract low‑level protocol differences away from end‑user agent clients. 4sapi offers such unified traffic‑handling capability for mixed‑model local‑agent deployments.

6. Operational Best‑Practices For Codex Desktop Configuration Maintenance

Working with Codex Desktop TOML configuration files carries several important operational caveats.

1. Always generate .bak backup copies before modifying config.toml. TOML parsing will fail completely if brackets, quotation marks or indentation are malformed. A backup prevents total configuration‑loss scenarios.
2. Every time you edit config.toml, you must fully exit and restart Codex Desktop application. In‑memory loaded configuration does not auto‑reload upon file change on disk. Simply closing the task window is insufficient; background resident Codex processes must also terminate.
3. Prefer placing newly‑added custom provider blocks at the top of TOML files, before [projects] and [plugins] tables. Misplaced blocks will lead to configuration not being parsed correctly.
4. Use codex doctor diagnostic command after every edit. This built‑in tool validates TOML syntax, provider reachability and active transport settings, catching mis‑configuration before you spend time manually testing user‑interface behaviors.
5. Distinguish application‑level configuration from system‑level network issues. If codex doctor reports HTTP endpoint unreachable, your problem is not the WebSocket fallback bug; you need to troubleshoot system‑level proxy, firewall or internet connectivity.

7. Troubleshooting Checklist For Persistent Reconnect Faults After Configuration Change

If you have followed the manual steps but still observe Reconnecting 1/5‑5/5 messages:

1. Confirm you edited the correct config.toml file. Use Codex UI “Open config.toml” button to guarantee you are modifying the actively‑loaded configuration instance.
2. Run codex doctor --summary --ascii. Verify output explicitly shows Responses WebSocket is not enabled for the active provider. If this line is missing, your TOML syntax or provider pointer setting contains an error.
3. Ensure you completely quit Codex Desktop, kill background processes, and launch the application again.
4. Create an entirely brand‑new task for testing; resuming old cached sessions may retain previous transport‑layer state.
5. Double‑check indentation and bracket syntax of the [model_providers.openai_http] TOML table. TOML is strict about table‑header syntax.

Conclusion

The Codex Desktop “Reconnecting 1/5‑5/5” issue stems from blocked WebSocket connections, followed by the client’s built‑in five‑attempt retry sequence before falling back to functional HTTP‑SSE streaming. Users suffer startup latency even though task logic succeeds. You can resolve this condition either by delegating repair work to a local AI agent, or by manually editing config.toml to define an HTTP‑only OpenAI provider and disable WebSocket transport. Always back‑up configuration files before modification, leverage the built‑in codex doctor diagnostic utility, and perform full application restarts for configuration changes to apply.

This fault illustrates a real‑world practical difference between WebSocket and HTTP‑SSE streaming protocols when traversing firewalls and proxy infrastructure, a consideration relevant for developers building local AI‑agent clients against remote LLM services.

International access: https://4sapi.com
Domestic access: https://4sapi.cn