Fix Codex Desktop Reconnecting 5/5 on macOS

Abstract

Codex desktop frequently loops through a "Reconnecting..." state with retry counters cycling from 1/5 to 5/5 repeatedly. This article centers on the most prevalent root cause for Chinese network environments: macOS GUI apps launched via Finder/Dock fail to inherit proxy environment variables stored in ~/.zshrc, breaking Codex’s app-server outbound OpenAI connection and triggering infinite WebSocket retries. Verified via GitHub Issue #30695 logged June 30, 2026, this guide provides a validated launchctl setenv remediation workflow, codex doctor validation commands, and troubleshooting checklists for three secondary disconnect scenarios: long task stream drops, premature WebSocket closure, and Windows remote pairing timeouts. Teams seeking alternative Anthropic-compatible domestic endpoints can evaluate unified routing via an API gateway platform like 4sapi.

1. Symptom Validation: Confirm You Match This Bug Profile

First cross-reference your failure behavior against the canonical symptoms documented in Issue #30695:

1. The chat interface continuously displays Reconnecting..., with a retry cycle triggering roughly every 16 seconds.
2. Retry counters loop infinitely between 1/5 and 5/5 with no permanent recovery.
3. Application logs repeatedly output the trace event codex_core::responses_retry.
4. Critical differentiator: The same machine runs Codex CLI normally via terminal, while the desktop GUI fails; or the desktop app launches properly when opened via terminal open, but disconnects immediately when launched from Finder/Dock icons.

If your setup matches the fourth point, the root cause is confirmed as missing proxy environment variables for launchd GUI sessions, and you may proceed directly to the core fix section. If not, skip to the secondary failure elimination checklist later in this paper.

2. Core Root Cause: macOS GUI Does Not Load .zshrc Proxy Config

The complete reproduction chain officially marked as a platform bug by OpenAI’s engineering team:

1. Access to OpenAI’s remote endpoints requires a local HTTP/HTTPS proxy (example address: http://127.0.0.1:7890).
2. Proxy environment variables HTTP_PROXY and HTTPS_PROXY are only declared inside the interactive shell file ~/.zshrc.
3. Terminal CLI processes initialize an interactive shell and load ~/.zshrc, so CLI proxy routing works flawlessly.
4. GUI applications opened via Finder or Dock spawn processes managed by launchd, which does not source interactive shell configuration files.
5. Codex’s backend app-server process cannot read proxy variables, sends all traffic directly to OpenAI, hits full connection timeouts, and enters an infinite WebSocket reconnect loop.

This is a fundamental macOS system limitation, not exclusive to Codex; any GUI developer tool relying on local proxy routing will encounter identical connectivity failures.

3. Verified 3-Step Repair Workflow: launchctl setenv

Step 1: Inject Full Proxy Variables Into launchd User Environment

Replace the sample proxy address 127.0.0.1:7890 with your actual local proxy port endpoint. Both uppercase and lowercase variable names must be declared separately, as different internal Codex components reference case-variant environment keys.

launchctl setenv HTTP_PROXY "http://127.0.0.1:7890"
launchctl setenv HTTPS_PROXY "http://127.0.0.1:7890"
launchctl setenv http_proxy "http://127.0.0.1:7890"
launchctl setenv https_proxy "http://127.0.0.1:7890"
launchctl setenv NO_PROXY "localhost,127.0.0.1"

Step 2: Fully Quit and Restart Codex

Complete shutdown via Cmd + Q or right-click the Dock icon and select Quit; simply closing the application window is insufficient. launchd environment variables only apply to newly spawned processes after a full application restart.

Step 3: Validate the Fix with Codex Doctor

Execute the diagnostic CLI tool to confirm successful proxy propagation and WebSocket handshake recovery:

codex doctor --json

Signs of successful remediation recorded in GitHub issue logs:

1. WebSocket handshake returns HTTP 101 Switching Protocols status code.
2. Transport initialization logs show reconnectAttempt=0 with zero queued retries.
3. No new responses_retry error events are generated in subsequent runtime logs.

Critical Notes for Persistent Configuration

1. launchctl setenv is session-scoped; all injected variables reset after system reboot or user logout. For permanent persistence, wrap the five commands into a LaunchAgent .plist file that runs automatically on login, or create a terminal alias for one-click reapplication.
2. Rollback command for clearing proxy variables: run launchctl unsetenv [VARIABLE_NAME] for each declared proxy key individually.
3. A commonly ineffective workaround: setting supports_websockets = false for custom model providers does not resolve this timeout issue. It triggers a direct model compatibility error traced under secondary ticket #30224, limited by Codex-Responses-Lite header restrictions.

4. Secondary Troubleshooting: Three Other Reconnecting Failure Modes

If your CLI client also disconnects repeatedly, or you operate on a network without mandatory local proxy routing, cross-reference these three distinct failure categories:

A separate frequently confused fault state: full Codex app freeze (distinct from looping Reconnecting errors). If the UI becomes unresponsive when rendering inline browser previews, thousands of app-server initialize handshake timed out log entries appear, tracked under #30624. The official team has no planned patch for this freeze bug; the temporary workaround is disabling embedded browser preview rendering and relying on external local browser windows instead.

5. Diagnostic Toolkit for Root Cause Localization

5.1 Locate Codex Runtime Logs (macOS)

# Navigate to desktop application log directory
ls ~/Library/Logs/com.openai.codex/
# Inspect session state records
ls ~/.codex/sessions/com.openai.codex/

Two critical log keywords to classify failure root cause:

1. responses_retry: Confirms proxy / outbound network timeout (the primary bug covered in this guide).
2. initialize handshake timed out: Points to app-server internal handshake failure (the separate app freeze bug family, #30624).

5.2 Cross-Version Validation Check

Mismatched desktop GUI and CLI binary versions can introduce unpatched connectivity bugs; verify both builds with these commands:

# Check CLI version
codex --version
# Check desktop app bundled binary version
/Applications/Codex.app/Contents/Resources/codex --version

When submitting connectivity bug feedback via the Codex desktop in-app feedback form, attach the full log dump and tag the ticket with connectivity to streamline triage. Redact all API keys and internal LAN addresses before sharing logs, per OpenAI’s official security documentation.

6. Frequently Asked Troubleshooting Clarifications

Q: Why does Codex CLI run perfectly while the desktop GUI fails?

Terminal CLI loads the interactive zshrc shell environment with proxy variables, while Finder/Dock-launched GUI processes run under launchd without sourcing interactive shell configs. The launchctl setenv workflow bridges this environment gap for GUI workloads.

Q: Can I automate the proxy variable injection on every login?

Yes. Create a custom .plist LaunchAgent file stored under ~/Library/LaunchAgents/ to execute the full set of launchctl setenv proxy commands automatically on user login, eliminating manual reconfiguration after every reboot.

Q: My macOS system-wide proxy settings are active—why does Codex still fail to connect?

As documented in #30695, Codex desktop build 26.623.x does not inherit native macOS global system proxy preferences, requiring explicit launchd environment variable injection as outlined above.

Q: Will unfinished task progress persist after repeated Reconnecting cycles?

After successful reconnection, most standard chat context resumes normally. However, GitHub ticket #30424 documents edge cases where interrupted SSH remote pairing workflows may generate divergent split agent task histories after WebSocket dropouts.

Q: Are there alternative network routing options for domestic network environments?

Users operating without a local proxy tunnel can switch to Anthropic-compatible domestic API endpoints via an API gateway such as 4sapi to bypass direct OpenAI connection instability entirely, eliminating the need for local proxy environment variable management in Codex.

7. Conclusion

The infinite Codex desktop "Reconnecting 5/5" loop has a clear, validated primary resolution path for macOS users: resolve missing launchd proxy environment variables via the three-step launchctl setenv workflow, validated against GitHub Issue #30695. After applying the fix, confirm full recovery with codex doctor --json to verify stable WebSocket 101 handshakes and zero recurring retry events.

If the proxy environment root cause does not match your failure symptoms, cross-reference the three secondary disconnect categories (long task stream drops, premature WebSocket closure, Windows remote pairing timeout) and apply their corresponding network and workflow mitigation strategies. The included log inspection toolkit and version validation commands enable rapid root cause classification without lengthy trial-and-error testing.

All troubleshooting logic and failure traces in this guide are sourced from public OpenAI GitHub issue records logged through July 2, 2026. Monitor the official #30695 ticket for upstream permanent platform patches; once OpenAI releases a native fix for launchd shell config inheritance, the manual launchctl setenv workaround detailed here will no longer be required.