How to Fix Constant Codex Reconnecting: From Local Proxy & SOCKS5H to TUN Mode

When building complex software via VibeCoding, few things are as frustrating as having Codex stop mid-refactor with an endless stream of Reconnecting... alerts and raw terminal crashes:

stream disconnected before completion:
IO error: peer closed connection without sending TLS close_notify

The typical knee-jerk reaction is to blame the proxy node: "The server must be down, let me switch nodes." Yet after hopping across half a dozen servers, the disconnection loop persists.

In reality, persistent Codex disconnections are rarely caused by server outages. Over 90% of failures stem from improper local port routing and TLS keep-alive handshakes. Based on real-world troubleshooting, the root cause breaks down into two distinct layers that you can systematically fix without changing proxy nodes.

---

1. Layer One: Codex Is Not Reaching Your Local Proxy Port

When accessing remote LLM APIs from behind restrictive firewalls, Codex depends on your local proxy client. If your proxy software is running but Codex has no environment variables pointing to it, the client attempts a direct connection, ultimately timing out and resetting.

1. Identify Your Actual Local Listening Port

Never assume your proxy port is 7890. Different clients (Clash, Mihomo, Surge, v2ray) use different default mixed-port or HTTP port configurations across operating systems.

On Windows:

Open PowerShell or Command Prompt:

netstat -ano | findstr "LISTEN"

Or inspect your proxy client dashboard to verify the exact mixed-port.

On macOS:

Run in Terminal:

# Check system proxy status
scutil --proxy

# Or list listening proxy processes directly
lsof -nP -iTCP -sTCP:LISTEN | grep -Ei "clash|mihomo|surge|v2ray|xray"

Locate the exact port currently in LISTEN state (represented as <PORT>).

2. Inject Proxy Variables into Codex Configuration

Codex loads environment variables from a user-level configuration file:

• Config Path:
  • Windows: %USERPROFILE%\.codex\.env
  • macOS / Linux: ~/.codex/.env

Create or append the following configuration (replace <PORT> with your real local port):

HTTP_PROXY="http://127.0.0.1:<PORT>"
HTTPS_PROXY="http://127.0.0.1:<PORT>"
NO_PROXY="localhost,127.0.0.1,::1"

Restart Codex completely:

• Windows: Exit from system tray and verify process shutdown in Task Manager.
• macOS: Press Cmd + Q to fully exit before relaunching.

---

2. Layer Two: Still Getting TLS unexpected-eof? Upgrade to SOCKS5H

If proxy variables are set but Codex still drops connections with: IO error: peer closed connection without sending TLS close_notify

This indicates Codex successfully reaches your local proxy, but the HTTP CONNECT tunnel terminates prematurely during long token streams. Furthermore, standard http:// proxies often perform DNS lookups on the local operating system, making them vulnerable to DNS pollution or TCP resets.

The Solution: Switch to SOCKS5H for Remote DNS Resolution

If your client supports SOCKS5 (Clash mixed-port natively handles both HTTP and SOCKS5), change the protocol scheme to socks5h:

Update ~/.codex/.env:

HTTP_PROXY="http://127.0.0.1:<PORT>"
HTTPS_PROXY="socks5h://127.0.0.1:<PORT>"
ALL_PROXY="socks5h://127.0.0.1:<PORT>"
NO_PROXY="localhost,127.0.0.1,::1"

Why socks5h:// matters: Standard socks5:// resolves hostnames locally before connecting. In contrast, socks5h:// delegates DNS queries directly to the remote server, preventing local DNS poisoning and handshake disruptions.

Restart Codex completely after saving the file.

---

3. The Ultimate Fail-Safe: Enable TUN Virtual Network Adapter Mode

In rare scenarios, certain compiled native binaries or subagent processes within Codex ignore user-space .env proxy declarations.

If stream drops still occur on socks5h, the cleanest, most permanent solution is TUN Mode:

1. Open your proxy client settings (Clash Verge, Mihomo Party, Surge, etc.).
2. Enable TUN Mode (Virtual Network Adapter Routing).
3. Clear HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY entries from ~/.codex/.env.

Once TUN mode is active, the OS-level virtual network interface transparently captures and routes all TCP/UDP traffic generated by Codex. You no longer need to maintain complex environment variables, eliminating TLS connection teardowns at the root.