Fastest path: in the same terminal where you launch codex, run export HTTPS_PROXY="http://127.0.0.1:7890" (replace the port with your proxy client's HTTP port), then run codex. socks5 is not supported — you must use the HTTP port.
Why a proxy is required on restricted networks
OpenAI's API domain (api.openai.com) is blocked in mainland China and on many corporate networks. Codex CLI communicates with OpenAI over a persistent WebSocket / SSE stream. When that connection can't be established, Codex repeatedly shows Reconnecting… 1/5 and eventually reports stream disconnected.
The only solution is to route Codex's network requests through a local proxy that can reach OpenAI. Codex reads the standard proxy environment variables (HTTPS_PROXY, HTTP_PROXY, ALL_PROXY) — no extra plugins needed.
If your main symptom is a Reconnecting loop and you're not sure of the cause, start with the Stuck on Reconnecting? Complete Fix Checklist — it walks you through diagnosing network vs. bug issues step by step.
Setting the proxy in the terminal
This is the most universal and recommended approach. Set the environment variables in the same terminal session before starting codex:
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="http://127.0.0.1:7890"
$ codexMatch the port to your proxy client: Clash commonly uses 7890 for HTTP, some clients use 7897 — check your client's settings panel to confirm.
Persisting the proxy across sessions
To avoid exporting manually every time, add the three lines to ~/.zshrc (zsh) or ~/.bashrc (bash), then reload:
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="http://127.0.0.1:7890"$ source ~/.zshrc
# bash users: source ~/.bashrcUsing a .env file
If you'd rather not touch your global shell config, put the three variables in a .env file inside the ~/.codex/ working directory. Codex loads it automatically on startup:
HTTPS_PROXY=http://127.0.0.1:7890
HTTP_PROXY=http://127.0.0.1:7890
ALL_PROXY=http://127.0.0.1:7890The socks5 pitfall
As of 2026, Codex does not support socks5 proxies. If ALL_PROXY is set to socks5://127.0.0.1:7891, Codex will silently fail and loop on Reconnecting with no obvious error message.
Most proxy clients (Clash, Surge, etc.) expose both a socks5 port and an HTTP port simultaneously. Use the HTTP port:
# ✗ Do NOT use socks5
export ALL_PROXY="socks5://127.0.0.1:7891"
# ✓ Use the HTTP port instead
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="http://127.0.0.1:7890"Confirm the exact HTTP port in your client's settings before copying the command. Clash commonly uses 7890; some clients use 7897 or another port — they vary.
VS Code extension proxy
The Codex VS Code extension does not inherit your terminal's export. You must configure the proxy in VS Code's own settings:
- Open settings with Ctrl+, (macOS: ⌘+,).
- Search for
proxyin the search box. - Find Http: Proxy and set it to
http://127.0.0.1:7890(replace with your port). - Fully restart VS Code (not just Reload Window) to apply the change.
If reconnecting persists after restarting, verify the proxy itself works by running curl -x http://127.0.0.1:7890 -I https://api.openai.com/v1/models in a terminal. A 401 response means the connection works.
Windows + WSL2 networking
When running Codex inside WSL2, WSL's network is isolated from Windows by default — even if a Windows system proxy is active, the codex process inside WSL cannot reach the Windows loopback proxy port.
Enable mirrored networking (recommended)
Add the following to %USERPROFILE%\.wslconfig to make WSL2 share the Windows network interface:
[wsl2]
networkingMode=mirroredSave the file, then run wsl --shutdown in PowerShell and reopen your WSL terminal. After this, 127.0.0.1:7890 inside WSL reaches the Windows-side proxy.
socks5 is still unsupported inside WSL2. Make sure to use the HTTP proxy port and export the proxy variables inside the WSL terminal as well.
Faster npm installs with a mirror
If npm install -g @openai/codex is slow or times out, temporarily switch to a mirror registry:
$ npm config set registry https://registry.npmmirror.com
$ npm install -g @openai/codex@latestOnce installed, restore the official registry to avoid issues with packages that may not be fully mirrored:
$ npm config set registry https://registry.npmjs.orgThe mirror only speeds up package downloads. Codex's runtime communication with the OpenAI API still requires a proxy — these are two separate concerns.
Using a third-party API relay (brief overview)
If you have access to an API relay service, you can configure a custom base_url in the [model_providers] section of ~/.codex/config.toml so Codex sends requests to your relay rather than directly to OpenAI. Note that:
- You still need a ChatGPT subscription (Plus or above) or an OpenAI API key to call the model — a relay doesn't bypass authentication.
- This site does not endorse or recommend any specific relay vendor; evaluate risks independently.
For full config.toml field documentation, see the Config guide.
Connectivity verification checklist
After configuring, work through these checks in order to confirm the proxy is actually working:
| Check | Command | Expected result |
|---|---|---|
| Proxy can reach OpenAI | curl -I -x http://127.0.0.1:7890 https://api.openai.com/v1/models |
HTTP/2 401 — 401 means the network is reachable; it's just not authenticated |
| Current shell has proxy variables | env | grep -i proxy |
Three lines including HTTPS_PROXY=http://127.0.0.1:7890 |
| Codex connects successfully | Run codex and send a simple message |
See ● connected and receive a reply |
Once you see ● connected — gpt-5.3-codex, everything is working. Add the proxy exports to ~/.zshrc to make them permanent so the next session starts connected.
Frequently asked questions
I set the proxy but it's still Reconnecting — how do I debug?
Check three things: 1) Is the proxy socks5? It must be HTTP — use the HTTP port. 2) Did you export and launch codex in the same terminal? 3) Run curl -x http://127.0.0.1:PORT -I https://api.openai.com/v1/models to confirm that port actually reaches the internet.
Still stuck? See the full Reconnecting checklist.
My proxy port isn't 7890 — what do I enter?
Use whatever HTTP port your proxy client exposes. Check the client's Settings or Ports panel. Common values: 7890 (Clash default), 7897 (some clients). Replace 7890 in all commands with your actual port.
Do I need a ChatGPT Plus subscription to use Codex?
Yes. As of 2026, using the Codex CLI model requires a ChatGPT Plus subscription (or higher) or an OpenAI API key (billed per token). A proxy only solves network connectivity — it does not bypass the subscription requirement.
My company's NO_PROXY list is blocking things — how do I handle it?
Check with env | grep -i no_proxy. If api.openai.com is included in the exclusion list, it won't go through the proxy. You may need to unset NO_PROXY in your personal terminal or coordinate with your network team.