Codex CLI Reconnecting Fix: WebSocket Fallback and Recovery Guide (June 2026)¶

Q: Is the Re-connecting loop fixed in the latest stable version?

Not fully. As of v0.136.0, reconnect-related issues are still open, especially WebSocket fallback delays, idle reconnect failures, and subagent-triggered stream disconnects.

Q: Why does Codex reconnect five times and then answer normally?

That usually means the WebSocket path failed or timed out, then Codex fell back to HTTP/SSE and completed the turn. Update first, then test an HTTP/SSE-only profile if the delay happens every turn.

Q: Should I disable WebSockets?

Only use that as a reversible workaround when WebSocket retries are the repeated delay and HTTP/SSE works afterward. Keep it in a separate profile so it can be removed quickly.

Q: What should I include when reporting a new reconnect issue?

Include your current codex --version, platform, auth method, whether MCP or an IDE extension was attached, and links to the closest open official issue if one already matches your symptoms.

Codex CLI Complete Guide

For / Key Points

For users seeing Codex CLI reconnecting or "Re-connecting" loops in real work, especially with WebSocket fallback, proxies, MCP, VS Code, Windows/WSL, long-running sessions, or subagents.

The current search intent has shifted: many 2026 reports are WebSocket startup/fallback problems, not only the older multi-session hang
If Codex shows Reconnecting... 1/5 through 5/5 and then answers, the session is usually falling back to HTTP/SSE; it is slow and confusing, but not always a hard failure
The latest stable baseline is v0.136.0 (released 2026-06-01), while v0.137.0-alpha.4 exists as a pre-release on 2026-06-03
Start with low-risk checks first: update Codex, classify the symptom, reduce to one session, then inspect auth, WebSocket/proxy, MCP, IDE extension, and subagent factors
API key sign-in is an official alternative for CLI workflows, but it is not a blanket fix for every reconnect case

June 3, 2026 status

The latest stable Codex release is v0.136.0 (released 2026-06-01 on the official GitHub Releases page). The same page also lists v0.137.0-alpha.4 as a pre-release on 2026-06-03. v0.136.0 includes ChatGPT auth-refresh improvements before the five-minute expiry window, remote-control WebSocket server-token changes, and Windows sandbox cleanup, but reconnect problems should still be treated as improved, not fully closed.¹

Current open reports now include WebSocket fallback behavior (#19821, #23665, #24045), subagent-triggered stream failures (#24475), and older idle/session persistence issues (#15841, #15870).²⁵⁹¹⁰¹¹¹²

This article therefore separates current facts from historical context. Treat older v0.50.0 sections as background, not as the latest state of the tool.

Fast Diagnosis¶

What you see	Most likely bucket	First action
`Reconnecting... 1/5` through `5/5`, then the answer eventually appears	WebSocket startup timeout followed by HTTP/SSE fallback, often with proxies or constrained networks	Update to the latest stable release, then consider the HTTP/SSE profile workaround only if the delay happens every turn
`Reconnecting...` followed by `401`, `403`, or login/account messages	Authentication or account state	Run `codex logout`, clear stale local auth state, and log in with one intended auth method
Reconnect after 1-2 hours idle, especially in the app or IDE extension	Idle app/extension connection state	Restart the app or extension, then attach diagnostics to the closest open issue
Reconnect starts only when subagents/background agents are launched	Multi-agent or app-server stream pressure	Re-run as a single-agent task or split the work; include request IDs when reporting
Multiple terminals hang at once	Historical multi-session/session recovery pattern	Stop every Codex process, wait 60 seconds, then restart one session

The following is a historical record from October 2025 (v0.50.0).

Codex CLI (v0.50.0) experienced persistent "Re-connecting..." loop issues as reported in GitHub Issues (#5575, #5679, #5505). This article provides an evidence-based summary of the situation at the time and environment-specific practical workarounds.

Historical context: Unresolved in v0.50.0

Version 0.50.0 (available late October 2025) did not fully resolve the "Re-connecting" issue. The causes were multifaceted: upstream connection instability, session recovery processing, VS Code extension interference, authentication settings, and WSL2/network environment issues.

This was not just your environment. Many users reported similar symptoms (GitHub Issue #5575), and the OpenAI team was actively working on fixes.

Current low-risk triage order

Update first: confirm whether you are already on the latest stable release (codex --version)
Reduce variables: reproduce with a single session and without optional integrations if possible
Check auth caching: Codex officially caches login state in ~/.codex/auth.json or your OS credential store³
Then isolate: auth method, MCP, IDE extension, and Windows/WSL boundary

Problem Symptoms¶

Symptoms reported in GitHub Issue #5679:

Typical Occurrence Pattern¶

Start a task with Codex CLI
After typically 1-3 steps, "Re-connecting..." suddenly appears repeatedly
Even after successful reconnection, the loop occurs again after a few steps
Re-login, plugin reinstallation, and switching networks do not resolve the issue

Affected Users¶

Codex CLI users prior to v0.47.x
Especially users in WSL2/Windows environments
Users running long-duration tasks
Users running multiple sessions simultaneously (primary trigger)

What's Happening (as of v0.50.0)¶

Multifaceted Causes¶

From Issue #5575 and related issues, the following composite factors were confirmed:

Upstream Connection Instability
After WebSocket/SSE stream disconnection, recovery processing failed, getting stuck on "Re-connecting"
Simultaneous hang-ups when running multiple sessions concurrently (reported at once-daily frequency)
VS Code Extension Interference
Issue #5505: Cases where the extension side repeatedly "Re-connecting"
Compatibility issues with extension versions and settings
Authentication Setting Conflicts
Issue #3835: Behavior becomes unstable when OAuth and API keys coexist
Connection errors occur if API keys remain in environment variables
WSL2/Network Environment
WSL2-specific network stack issues
Interference from VPN/proxy/security products

Version History and Current Status¶

0.48.0 (late October 2025): Event output enhancements, auto-compact, WSL-related updates
0.50.0 (late October 2025): Early fixes, but reconnect loops still persisted
0.117.0 (2026-03-26): Rust-era stability improvements referenced in many March 2026 reports
0.125.0 (2026-04-24): Latest stable release as of 2026-04-27
0.136.0 (2026-06-01): Latest stable release as of 2026-06-03
Current status: reconnect-related issues remain open, especially around WebSocket fallback, proxy behavior, idle sessions, and subagent streams

About version dates

Use the Codex GitHub Releases page for official version dates. This article no longer treats community-reported release dates as authoritative.

Where to track the latest status

Use the official Codex GitHub Releases page for shipped fixes, and the currently open reconnect issues for unresolved cases. Closed October 2025 issues are useful historical context, but current open issues are the better source of truth now.

Practical Workarounds (Priority Order)¶

Try the following workarounds in order from 1 to 6. Do not start by deleting configuration or changing auth if your session simply recovers after the five WebSocket retries.

Workaround Comparison Table (quick situational reference)¶

Method	Best use case	Time needed	Success signal
Method 1	Any reconnect report on an old build	~2 minutes	You are on v0.136.0 or newer stable
Method 2	Multiple sessions hang simultaneously and block progress	~2 minutes	One fresh session responds to `HELLO`
Method 3	`Reconnecting... 1/5` to `5/5` every turn before HTTP/SSE eventually works	~5 minutes	The session starts on HTTP/SSE without waiting through WebSocket retries
Method 4	`401`, `403`, login loops, or frequent auth switching	~5 minutes	`codex login status` matches the intended auth method
Method 5	MCP, IDE extension, or subagents make the problem appear	~10 minutes	CLI-only / MCP-off / single-agent run works
Method 6	Windows or WSL-specific intermittent drops	~3 minutes	Native Windows or WSL path is isolated cleanly

Method 1: Update and Classify the Pattern¶

codex --version

# Standalone installer upgrade for macOS/Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm install remains valid if that is how you installed Codex
npm install -g @openai/codex@latest

After updating, run a short prompt. If the only symptom is Reconnecting... 1/5 through 5/5 followed by a successful answer, treat it as a WebSocket fallback delay first, not as a corrupted local install.

Why this matters in 2026

Newer open issues describe WebSocket setup timing out, Codex retrying, then falling back to responses_http / SSE where the turn succeeds.⁹¹¹ That pattern needs different handling from the older all-session hang.

Method 2: Stop All Instances -> Single Restart¶

This is still the lowest-risk first step and is consistent with the historical multi-session failure reports in Issue #5575.

# 1) Completely terminate all Codex processes (Ctrl+C)
# 2) Wait 60 seconds (confirm complete termination of background processes)
# 3) Restart only one instance
codex

# 4) Confirm response with short text
# Type "HELLO" at the prompt and check responsiveness

Why start here

This step is fast, reversible, and removes concurrency noise before you start changing auth or configuration.

Method 3: Use an HTTP/SSE Profile for Repeated WebSocket Fallback (Advanced)¶

If Codex repeatedly waits through Reconnecting... 1/5 to 5/5 before a successful HTTP/SSE fallback, especially behind a proxy, a reported workaround is to define a separate provider profile with WebSockets disabled. The official config reference includes model_providers.<id>.supports_websockets, and the recent issue thread describes this as a practical workaround for proxy environments.⁹¹³¹⁴

Add this to user-level ~/.codex/config.toml, not a project-local config:

[profiles.http_sse]
model_provider = "openai-http"

[model_providers.openai-http]
name = "OpenAI HTTP/SSE"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

Then test with a new session:

codex --profile http_sse

Use this as a reversible workaround

Do not overwrite the built-in openai provider ID; OpenAI's config docs reserve built-in IDs. If this profile causes 401, slower responses, or model-availability changes in your account, remove the profile and return to the default provider.¹³

Method 4: Refresh Cached Authentication State¶

Codex's official auth docs state that login details are cached locally in ~/.codex/auth.json or your OS credential store. If reconnect failures are clearly auth-related, refreshing that cached state is a reasonable next step.³

# 1) Logout
codex logout

# 2) Delete authentication file (clear remnants)
rm -f ~/.codex/auth.json

# 3) Temporarily disable API key in environment variables (avoid conflicts)
unset OPENAI_API_KEY

# 4) Re-login with your intended auth method
codex login
# or: printenv OPENAI_API_KEY | codex login --with-api-key

About Authentication Conflicts

Codex officially supports both ChatGPT sign-in and API key sign-in. The important part is to avoid ambiguity about which method you intend to use after clearing the cache. OpenAI's auth docs also recommend API key auth for programmatic CLI workflows.³⁴

If you configured cli_auth_credentials_store = "keyring" or auto, some cached credentials may live in your OS credential store instead of ~/.codex/auth.json. In that setup, codex logout is the official first step because deleting the file alone may not clear every saved credential.³⁴

Method 5: Isolate MCP, IDE Extension, and Subagents¶

MCP-related compatibility issues reported in Issue #5619 and Issue #5208:

Toggle Experimental MCP Client¶

Edit ~/.codex/config.toml:

# Toggle ON/OFF to check behavior
experimental_use_rmcp_client = false  # or true

Temporarily Disable Problematic MCP Servers¶

# Comment out suspected MCP servers
# [mcp_servers.problematic_server]
# command = "..."

Known MCP Issues

Specification inconsistencies around SSE/HTTP2 have been reported extensively recently. Particularly, cases where streaming connection handshakes fail.

Avoid VS Code Extension Interference¶

Network blocking issue on the extension side reported in Issue #5041:

Temporarily disable VS Code extension
Run codex in CLI only mode
If the issue resolves, check extension settings and version

Known Extension Bug

There is a known issue where the VS Code extension blocks network access. Prioritize CLI-only operation verification.

Reduce Subagent / Background-Agent Load¶

Recent reports show reconnect loops and stream disconnected before completion when subagents or background agents are dispatched, even when normal single-agent work succeeds.¹²

Re-run the same request as a single-agent task.
Split a repo-wide task into smaller prompts.
Capture the request IDs printed by Codex if the stream fails after 5/5.

Method 6: Reset or Re-scope Windows / WSL¶

Recommended procedure from Issue #5084 and Official Windows Guide:

# Execute in PowerShell
wsl --shutdown

# Wait 1 minute, then restart WSL2

About Windows Environment

OpenAI's current Windows docs recommend the native Windows sandbox by default and WSL2 when you need a Linux-native environment or your workflow already lives in WSL2. If you are troubleshooting, avoid mixing repository files across C:\ and WSL paths during the same reproduction.⁸

Version Management and Redeployment¶

Updating to Latest Version¶

# Standalone installer for macOS/Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm, if that is your existing install path
npm install -g @openai/codex@latest

# Homebrew, if that is your existing install path
brew upgrade codex

# Verify version after upgrading
codex --version

Homebrew Cask Delays

Issue #5601: Homebrew Cask version reflection may be delayed. If not the latest version, download binaries directly from GitHub Releases.

Complete Reinstallation When Corrupted¶

# Complete redeployment via npm (corruption reset)
npm uninstall -g @openai/codex
npm install -g @openai/codex@latest

# If also clearing authentication information
rm -rf ~/.codex

Submitting Diagnostic Information (Enhanced in 0.50.0)¶

The /feedback command was enhanced in 0.50.0 release, making it easier to submit diagnostic information to the development team.

# Execute within Codex session
/feedback

Information submitted:

Request ID
Error logs
System environment information
Connection state snapshot

Recommended Information for Issue Reports

When sharing reproduction logs, including the following information will facilitate fixes:

Occurrence date/time and frequency
Number of concurrent sessions
Connection path (VPN/Proxy presence)
IDE/extension usage
codex --version output
Request ID obtained with /feedback
Log files (~/.codex/log/codex-tui.log)

Active Issues to Watch as of June 2026¶

Issue	Status	Summary	Reported
#19821	Open	WebSocket connect failures consume retries before HTTP fallback	2026-04-27
#23665	Open	WebSocket fallback does not recover automatically after transient failures	2026-05-20
#24045	Open	Recoverable reconnect loop before HTTP/SSE fallback on new/resumed thread	2026-05-22
#24475	Open	Subagent/background-agent tasks trigger reconnect loop and stream disconnect	2026-05-25
#15841	Open	Reconnect failure after 1-2 hours idle	2026-03-26
#15870	Open	No resumable session after early transport failure	2026-03-26
#15014	Open	WebSocket fallback + timeout (v0.115.0)	2026-03-18
#13041	Open	WebSocket 1008 Policy close -> HTTPS fallback	2026-02-27

Major Reconnecting Spike: March 6-10, 2026¶

Issue #14209 (50 comments): Server-side instability caused many users to simultaneously enter Re-connecting loops. Related issues #13725 and #13832 were reported during the same period. All closed, but server-side issues may recur.

Legacy Issues (v0.50.0 era, all CLOSED)¶

Issue	Summary
#5575	Simultaneous hang-up of all instances
#5679	Repeated Re-connecting loops
#5619	MCP/SSE streaming connection failure
#5505	VS Code extension reconnection loop
#5041	VS Code extension network blocking
#3216	Infinite loop within `codex exec`

Summary¶

The Codex CLI "Reconnecting" / "Re-connecting" issue should still be treated as active as of 2026-06-03, even though the stable release has moved forward to v0.136.0. The official evidence now lives in three places:¹²⁵⁹¹⁰¹¹¹²

shipped fixes on the Codex GitHub Releases page
unresolved WebSocket/fallback cases such as #19821, #23665, and #24045
idle/session/subagent cases such as #15841, #15870, and #24475

Treat the problem as improved but not closed. The article is still a good answer to the search query, but only if readers can quickly decide whether they have a recoverable WebSocket fallback delay, an auth issue, a multi-session hang, or an integration-specific failure.

Immediate Action Checklist (Recommended Execution Order)¶

Step 1: Update to latest stable and classify the symptom (codex --version, then a short test prompt)

Step 2: If every turn waits through Reconnecting... 1/5 to 5/5 and then works, test the HTTP/SSE profile workaround in a new session⁹¹³¹⁴

Step 3: If multiple sessions hang, stop all -> 60 seconds -> single restart (confirm communication with HELLO)

Step 4: If auth errors appear, refresh auth: codex logout -> rm ~/.codex/auth.json -> unset OPENAI_API_KEY -> codex login³⁴

Step 5: If integrations trigger it, run CLI-only / MCP-off / single-agent before changing global settings

This checklist resolves many cases

The most important improvement is matching the fix to the symptom. A recoverable WebSocket fallback delay, an auth loop, and a subagent stream failure look similar in the UI but need different fixes.

Recent Connection Stability Improvements (v0.115.0-v0.136.0)¶

Version	Improvement	PR
v0.136.0 (2026-06-01)	ChatGPT auth refreshes before the five-minute expiry window; remote-control WebSockets use server tokens; sandbox cleanup improved	GitHub Releases
v0.135.0 (2026-05-28)	`codex doctor` adds richer environment/thread diagnostics; `/status` shows remote connection details	GitHub Releases
v0.134.0 (2026-05-26)	Remote reliability improvements include reconnecting stale exec-server WebSocket clients	GitHub Releases
v0.125.0 (2026-04-24)	WebSocket app-server clients are less likely to disconnect during bursts of turn and tool-output notifications; Windows sandbox startup also improved	#19246, #19044
v0.117.0 (2026-03-26)	Stop auth refresh storms after permanent token failure	#15530
v0.117.0	Proactive auth refresh using access token expiration	#15545
v0.116.0 (2026-03-19)	WebSocket prewarm timeout + clean fallback	#14838
v0.115.0 (2026-03-16)	Local proxy serves CONNECT as HTTP/1.1 (improved proxy compatibility)	—

Check GitHub Releases for the latest progress.¹

FAQ (Frequently Asked Questions)¶

Is the \"Re-connecting\" loop fixed in the latest stable version?

Not fully. As of v0.136.0 (released 2026-06-01), reconnect-related issues are still open in the official repository, especially WebSocket fallback delays, idle reconnect failures, and subagent-triggered stream disconnects.¹²⁹¹⁰¹¹¹²

Why does Codex reconnect five times and then answer normally?

That pattern often means the WebSocket path failed or timed out, then Codex fell back to HTTP/SSE and completed the turn. If it happens every turn, update first, then test an HTTP/SSE-only profile as a reversible workaround.⁹¹¹¹⁴

Should I disable WebSockets?

Only for the specific pattern where WebSocket retries are the repeated delay and HTTP/SSE works afterward. Keep it in a separate profile so you can remove it quickly if it causes auth, model, or performance side effects.⁹¹³¹⁴

Should I switch from ChatGPT sign-in to API key auth?

Use API key auth when you want a scripted or programmatic CLI workflow. That recommendation comes from the official auth docs. It is an alternative auth path, not a universal cure for every reconnect loop.³

What should I include when reporting a new reconnect issue?

Include the current codex --version, your platform, your auth method, whether MCP or an IDE extension was attached, and links to the closest open official issue if one already matches your symptoms.