Codex Connection Timeout: Network Troubleshooting Guide for China

Nothing is more frustrating than having Codex CLI fully installed, typing your first command, and watching it hang until Connection Failed, ETIMEDOUT, or Network Error appears. In regions with restricted internet access, this is the norm rather than the exception. This article walks through every root cause of Codex timeout and explains how TeamoRouter eliminates the problem at its source.

Common Symptoms of Codex Timeout

These errors don't all share the same root cause — sometimes the terminal proxy is missing, sometimes the npm registry is unreachable, and sometimes the API itself is being DNS-hijacked. Each path needs separate diagnosis.

Why Codex Requests Fail

Codex CLI's default API endpoint is https://api.openai.com/v1/responses. Under restrictive networks, this path faces three layers of blocking:

1. DNS pollution: api.openai.com may resolve to a spoofed IP, or the request gets intercepted by a middlebox.
2. SNI blocking: Even with correct DNS, the TLS handshake SNI probe can trigger a connection reset.
3. IP range throttling: OpenAI's server IP ranges may be rate-limited during peak hours, causing prolonged timeouts.

This is why simply "turning on the proxy" is rarely sufficient — it only solves part of the problem, and proxy conflicts with Codex CLI's local ports create additional headaches.

Terminal Proxy vs Browser Proxy

Many users find they can open chat.openai.com in their browser, but the terminal Codex CLI still times out. This is because the browser and terminal use completely different network paths:

Common misconception: You enabled a VPN in system settings and assume Codex CLI in the terminal is also using it. Most CLI tools do not read system proxy settings automatically.

Terminal Proxy Setup

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
codex

npm Proxy Setup

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

Git Proxy Setup

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

Proxies themselves introduce problems: added latency, instability, frequent disconnects on network switches, and many public proxy nodes throttle OpenAI traffic.

Troubleshooting npm, Git, and OpenAI Separately

npm Network Check

npm ping

# If timeout, set mirror
npm config set registry https://registry.npmmirror.com
npm ping

Git Network Check

ssh -T git@github.com

# If timeout, set proxy
git config --global http.proxy http://127.0.0.1:7890

OpenAI API Reachability Check

curl -s -o /dev/null -w "%{http_code}" \
  https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","input":"test"}' \
  --max-time 10

# 000 = connection not established (network issue)
# 401 = unauthorized (network ok, API Key issue)
# 200 = working

Common Error Codes Explained

How to Configure a Base URL to Fix API Timeout

The cleanest solution isn't configuring proxies layer by layer — it's pointing the API endpoint at a gateway that's directly reachable from your network. TeamoRouter provides a directly accessible API endpoint compatible with Codex's Responses API:

# Configure TeamoRouter gateway
export OPENAI_BASE_URL="https://api.teamorouter.com/v1"
export OPENAI_API_KEY="sk-teamo-xxxxxxxx"

# Verify connectivity (should return non-000 immediately)
curl -s -o /dev/null -w "%{http_code}" \
  https://api.teamorouter.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","input":"test"}' \
  --max-time 10

Benefits of this approach:

• No proxy needed: TeamoRouter is directly reachable from domestic networks without VPN
• Single config point: One baseUrl handles all API calls — CLI, npm, Git
• Unified billing: Cache hit rate > 99%, floating 1-2x discount, no charge for failed requests

FAQ

Browser can reach OpenAI but Codex CLI times out — why?

The browser and terminal use different network paths. The browser respects system proxy settings (or VPN extensions), but the terminal CLI ignores them by default — you need to set the https_proxy environment variable separately. A better solution is to configure TeamoRouter's baseUrl directly and eliminate all proxy configuration.

I set up a proxy but it still times out — what now?

First verify the proxy itself: curl -x http://127.0.0.1:7890 https://api.openai.com/v1/responses .... If the proxy also fails, the proxy node itself is being throttled. Switch to a TeamoRouter gateway instead.

Does TeamoRouter need a proxy?

No. TeamoRouter's API endpoint is directly accessible from domestic networks — configure the baseUrl once with no additional proxy required.

Codex Desktop App times out — how do I debug it?

The Codex Desktop App uses the system's network configuration, differently from terminal proxy settings. First check your system proxy. If that doesn't resolve it, enter TeamoRouter's baseUrl directly in the App settings.

npm install works but Codex times out at runtime — why?

npm is using a mirror (like npmmirror) correctly, but the OpenAI API direct path still has issues. You need to configure a baseUrl or proxy at the Codex environment level.

Get Started

The simplest fix is switching gateways:

1. Sign up for TeamoRouter and get an API Key
2. Set OPENAI_BASE_URL and OPENAI_API_KEY
3. Run curl to verify connectivity — expect a non-000 status code

Get Your Free Codex Setup →

Access Codex, Claude Code, and Gemini CLI stably through TeamoRouter.