Fix Codex Reconnecting Loop on macOS: Proxy Guide

Abstract

Many macOS Codex desktop‑app users encounter infinite “Reconnecting…” retry cycles, while the Codex CLI from terminal works perfectly. This well‑documented GitHub‑issue (#30695) bug originates from macOS launchd behaviour: GUI applications launched via Finder or Dock do not load interactive shell configuration files such as .zshrc. Proxy variables defined inside .zshrc are visible for terminal‑spawned CLI sessions, yet invisible to GUI‑mode Codex. Without proxy configuration, the desktop app cannot route traffic and triggers continuous WebSocket reconnection attempts. This article walks through symptom identification, root‑cause analysis, validated launchctl setenv repair steps, important caveats, alternative failure‑mode elimination, log‑debugging workflows, and frequently‑asked questions. When working with local‑proxy setups for LLM API traffic, developers may leverage an API gateway such as 4sapi to standardise proxy‑environment handling across CLI and GUI workloads.

1. Symptom Confirmation: Identify the launchd‑proxy‑variable Bug Pattern

Before applying fixes, validate whether your issue matches the known failure pattern tracked in GitHub issue #30695.

Observable Symptoms

1. The Codex GUI repeatedly displays Reconnecting…, roughly one retry cycle every 15 seconds.
2. Retry counters cycle: 1/5 → 2/5 … →5/5, then loop back to start.
3. Application logs contain repeated codex_core::responses_retry events.
4. Critical differentiator: Codex CLI works perfectly inside terminal, but the desktop GUI fails.
   • Codex launched via open shell command from terminal works fine.
   • Codex started from Finder or Dock icons immediately enters reconnect loops.

If your setup matches these points, you are hitting the macOS launchd shell‑configuration isolation bug. If symptoms diverge, proceed to the alternative‑failure‑mode elimination section later in this article.

2. Root‑Cause Deep‑Dive: Why GUI Apps Ignore .zshrc Proxy Settings

This is a fundamental macOS operating‑system behaviour, not exclusive to Codex. Any GUI developer‑tool that relies on HTTP_PROXY / HTTPS_PROXY environment variables can run into identical failure modes.

Full reproduction sequence:

1. Your local‑network access to OpenAI requires a local proxy service, for example http://127.0.0.1:7890.
2. You define proxy environment variables (HTTP_PROXY, HTTPS_PROXY) within ~/.zshrc.
3. Terminal‑spawned processes source .zshrc automatically. Therefore Codex CLI inherits proxy variables and operates normally.
4. GUI applications started via Finder or Dock are spawned by launchd. launchd‑launched GUI processes do not load interactive‑shell dot‑files such as .zshrc.
5. The Codex app‑server component receives no proxy‑environment values. It attempts direct outbound connections to OpenAI endpoints, which time‑out completely.
6. Time‑out triggers WebSocket‑transport failure, and the app enters endless Reconnecting… retry loops.

The core difference: CLI inherits shell‑dotfile environment; launchd‑spawned GUI processes operate within a separate launchd‑managed environment namespace.

3. Validated Repair Workflow: Three‑Step launchctl setenv Fix

This procedure injects proxy‑environment variables directly into the launchd user‑session environment, so GUI‑spawned processes can read them. Replace 127.0.0.1:7890 with your actual local‑proxy address and port.

Step 1: Inject proxy variables into launchd user‑session environment

Run these commands inside your terminal shell. Note that environment‑variable names are case‑sensitive; you must set both uppercase and lowercase variants, as different software components read different casing.

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

Perform a complete application exit: right‑click Codex in Dock → Quit. Closing individual windows is insufficient. launchd‑updated environment variables only apply to newly‑spawned child‑processes; existing running Codex instances keep their old environment.

Step 3: Validate repair status

Run the built‑in Codex diagnostic tool inside terminal:

codex doctor --json

Success indicators visible in logs after repair

1. WebSocket handshake returns HTTP 101 Switching Protocols.
2. Transport initialises with reconnectAttempt=0.
3. No new responses_retry retry‑events are generated in runtime logs.

Important operational caveats

1. launchctl setenv is session‑scoped. After logout or system reboot these variables disappear. Values must be re‑applied. For persistence, wrap these commands inside a LaunchAgent plist that runs automatically at login‑time, or define a convenient shell alias for manual execution.
2. Revert‑unset syntax, run one per variable if you need to clean‑up:

launchctl unsetenv HTTP_PROXY
launchctl unsetenv HTTPS_PROXY
launchctl unsetenv http_proxy
launchctl unsetenv https_proxy
launchctl unsetenv NO_PROXY

3. Documented ineffective workaround: setting supports_websockets = false for custom provider configurations cannot resolve this launchd‑proxy‑variable bug. This misconfiguration triggers direct model‑side “websocket‑not‑supported” errors instead of reconnect loops, tracked under GitHub issue #30224.

4. Eliminate Other “Reconnecting…” Failure Modes

If Codex CLI also suffers connection failures, or you operate without local proxy services, your problem falls outside the .zshrc‑launchd mismatch bug. Three further well‑known failure categories exist:

Distinguish application freeze from reconnect loops: total UI freeze, no input‑responsiveness, massive app‑server initialize handshake timed out log entries belong to issue #30624 family. This is not the reconnect‑loop bug. Temporary workaround: launch Codex pointing toward system Chrome instead of built‑in embedded browser view.

5. Debug Toolkit: Log Locations and Keyword‑based Troubleshooting

Collect application logs to precisely classify failure sources under macOS.

Log‑file locations

# Codex application logs
ls ~/Library/Logs/com.openai.codex/
# Codex session records
ls ~/.codex/sessions

Search‑keywords inside log files for fast classification

1. responses_retry → points to proxy‑network‑connection issues (this article’s main topic, #30695).
2. initialize handshake timed out → app‑server handshake timeout (#30624 freeze‑family issues).

Version cross‑check before opening GitHub issues

CLI and desktop‑app binary versions can drift out‑of‑sync. Capture both version strings before reporting bugs:

codex --version
/Applications/Codex.app/Contents/Resources/codex --version

Attach version metadata, relevant log snippets, and network‑context information when filing GitHub issues. Use the connectivity tag for GitHub‑issue labelling. Sanitise logs: remove API‑keys, private‑IP addresses and sensitive host‑names before public sharing.

6. Frequently Asked Practical Questions

Q: Why does Codex CLI work from terminal but GUI Codex break?

Terminal‑shell processes load .zshrc and inherit proxy‑environment variables. Finder‑/Dock‑launched GUI children come from launchd and skip interactive shell‑dot‑files. launchctl setenv injects variables directly into launchd user‑session environment space for GUI‑process consumption.

Q: Must I re‑run launchctl commands every single computer reboot?

Yes, raw launchctl setenv is volatile across log‑outs and reboots. Persistent configuration can be achieved with a custom LaunchAgent plist stored under ~/Library/LaunchAgents/, which executes the proxy‑setup commands automatically during login‑phase. Native Codex‑app built‑in proxy‑configuration UI is not available at time‑of‑writing.

Q: My macOS system‑network‑settings already define proxy, but Codex GUI still fails.

As of release 26.623.x, the Codex desktop app does not consume macOS system‑network‑proxy settings; it only respects environment‑variable‑driven proxy‑configuration. This explains the mismatch many users observe.

Q: After reconnect resumes, do prior‑session agent‑contexts survive?

Session‑state persistence is supported for resume‑reconnection flows. Note GitHub issue #30424 reports rare edge‑cases where SSH‑tunnel resumption may create split‑agent‑session branches after network‑interruption recovery.

Q: Are there alternative non‑proxy‑driven deployment paths for mainland‑network environments?

Codex desktop application requires direct OpenAI‑service connectivity; local proxy cannot be bypassed. If you only need code‑agent capability without the Codex desktop‑client, consider alternative agent‑tool stacks such as Anthropic‑powered Claude‑Code‑toolkit. Always evaluate network‑reachability requirements for every candidate agent‑tool.

7. Summary

Endless “Reconnecting…” loops within Codex desktop‑app on macOS most often trace back to the launchd‑environment isolation bug (GitHub #30695). Proxy‑variables stored inside .zshrc are only visible to terminal‑spawned CLI processes, while Finder‑Dock‑launched GUI‑applications inherit launchd‑session environment and miss these proxy‑settings.

The validated remediation injects proxy‑environment variables directly into launchd user‑namespace using launchctl setenv for both uppercase‑and‑lowercase variable‑name variants. Keep in mind that raw launchctl setenv is session‑volatile and will not survive reboot/log‑out events.

If the three‑step proxy‑repair workflow yields no improvement, eliminate other root‑causes: long‑task stream‑disconnect, WebSocket‑early‑termination, remote‑pairing time‑out, SSH‑auth dead‑loops, and embedded‑browser handshake‑time‑out freezes. Leverage Codex built‑in codex doctor diagnostics and application‑log keywords (responses_retry, initialize handshake timed out) to classify failure modes precisely. Always cross‑check CLI‑and‑GUI binary versions before opening GitHub‑issues and sanitise logs before public‑issue submission. Track upstream GitHub‑issue #30695 for official native‑UI‑proxy‑configuration feature updates.