The Complete Guide to Codex Proxy Configuration: Terminal, npm, Git, and WSL2 Setup

When using Codex for AI-powered coding in network-restricted environments, proxy configuration is unavoidable. From terminal environment variables to npm mirror registries, from Git proxy settings to WSL2 network modes — if even one piece is misconfigured, Codex can get stuck in "connecting" limbo. This guide systematically walks through each configuration layer and shows how TeamoRouter can dramatically simplify the entire workflow.

No card at all? You can also top up with USDT, USDC or ETH: click Pay with crypto in the top-up dialog and send it from Binance, OKX or any wallet. The minimum is $5 and no browser extension is needed. Step by step: Pay for Claude and GPT APIs with crypto (USDT).

Why Codex Needs Proxy Configuration

Codex communicates with AI services through OpenAI's API and GitHub. Due to network restrictions in certain regions, direct connections are often unstable or completely unreachable. This requires proxy configuration at multiple levels:

Terminal level: Environment variables for Codex CLI's HTTP requests
Package manager level: npm/pip source settings for dependency installation
Git level: Network channels when Codex pulls code and pushes changes
IDE level: Plugin network configurations in editors like VS Code
WSL2 level: Network bridging between Windows Subsystem for Linux and the host

The Simpler Way: Unified Model Access with TeamoRouter

Before troubleshooting each proxy layer individually, there's a cleaner option — use TeamoRouter as a unified API gateway.

TeamoRouter provides API endpoints that are directly accessible from within China. Simply update Codex's baseUrl configuration, and you eliminate the need for OpenAI API proxy configuration. You'll still need terminal, npm, and Git proxies for accessing GitHub and other resources, but the model communication layer becomes far simpler.

With TeamoRouter, you can also access Claude Code and Gemini CLI through the same configuration — one setup, multiple agent tools.

Key advantages:

Cache hit rate >99% for lightning-fast responses
Floating rate as low as 10%-20% of official pricing
SLA 99.98% for business continuity
5000 QPM quota for high-frequency team calls
100% Agent API protocol compatibility, one-line config change

Why the Browser Works but Codex Doesn't

Many developers find that their browser can access OpenAI fine, but Codex in the terminal can't connect. Here's why:

Browsers use system-level proxy or VPN settings, handling both HTTP and HTTPS traffic automatically
Codex CLI runs in a terminal environment that doesn't inherit system proxy settings by default
Browsers have automatic PAC proxy scripts and WebRTC fallback mechanisms; terminals don't
Codex CLI runs as a native binary (the npm package only launches it), and it needs HTTP_PROXY environment variables to route through a proxy

Understanding this distinction explains why explicit terminal proxy configuration is essential. Also make sure your proxy exits in a region OpenAI supports, or the API returns a 403 — see OpenAI "Country, region, or territory not supported" (403): causes and fixes.

Terminal Proxy Configuration

Terminal proxy is the foundation. Add these variables to your shell config file (~/.zshrc, ~/.bashrc, or ~/.bash_profile):

bash

# HTTP/HTTPS proxy
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

# Bypass proxy for internal addresses
export NO_PROXY=localhost,127.0.0.1,::1,10.0.0.0/8,192.168.0.0/16
export no_proxy=localhost,127.0.0.1,::1,10.0.0.0/8,192.168.0.0/16

Apply with source ~/.zshrc and verify:

bash

# Verify proxy is active
curl -I https://api.openai.com

# Check current proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY

Note: 127.0.0.1:7890 is the default port for Clash, ShadowSocks, and similar proxy tools. Adjust based on your actual proxy setup.

To set a proxy temporarily for a single command:

bash

HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 codex "your prompt"

Codex also loads variables from ~/.codex/.env (%USERPROFILE%\.codex\.env on Windows) when it starts (source), so a proxy set there applies even when your shell has none. If you stop using a proxy, remove it from that file as well: a leftover HTTPS_PROXY=http://127.0.0.1:7890 there after the proxy app was closed is a known cause of Connection refused (os error 61) (#38885).

Codex's Built-in Network Proxy

Searching for "Codex network proxy" often turns up a different feature. Recent Codex versions include a local network proxy (codex-rs/network-proxy) that controls what network access the commands Codex runs in its sandbox get. It is not how Codex itself reaches OpenAI or your model provider.

It is turned on with [features.network_proxy] and configured under [permissions.<profile>.network] in ~/.codex/config.toml.
It listens locally: an HTTP proxy on 127.0.0.1:3128 and a SOCKS5 proxy on 127.0.0.1:8081 by default.
It enforces an allow/deny list of hosts, with a limited mode for read-only access. If no domain is allowed, it blocks requests until you add an allowlist.
With allow_upstream_proxy = true, it forwards through your own HTTP(S)_PROXY / ALL_PROXY.

So if your goal is to get Codex through a proxy to reach the API, use the environment variables above; the network proxy only matters when commands inside the sandbox can't reach the network.

npm Proxy Configuration

Codex automatically installs dependencies at runtime. If npm doesn't use a proxy, installations will be painfully slow or fail entirely.

Global npm proxy settings:

bash

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

View and remove proxy settings:

bash

# View
npm config get proxy
npm config get https-proxy

# Remove
npm config delete proxy
npm config delete https-proxy

npm mirror registry (recommended for China):

bash

# Use Taobao mirror
npm config set registry https://registry.npmmirror.com

# Restore official registry
npm config set registry https://registry.npmjs.org

Verified npm proxy configuration:

bash

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm config set registry https://registry.npmmirror.com

Git Proxy Configuration

Git proxy is critical when Codex needs to access GitHub repositories.

Global proxy settings:

bash

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

# Verify
git config --global --get http.proxy
git config --global --get https.proxy

Domain-specific proxy (GitHub only):

bash

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

Remove proxy:

bash

git config --global --unset http.proxy
git config --global --unset https.proxy

WSL2 Proxy Configuration

WSL2 has a unique network architecture that requires special handling.

Method 1: Host proxy forwarding

Run your proxy tool (e.g., Clash) on the Windows host, then get the host IP in WSL2:

bash

# In WSL2
export host_ip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
export HTTP_PROXY=http://$host_ip:7890
export HTTPS_PROXY=http://$host_ip:7890

Add auto-configuration to WSL2's ~/.bashrc:

bash

# WSL2 auto proxy
function set_proxy() {
    export host_ip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
    export HTTP_PROXY=http://$host_ip:7890
    export HTTPS_PROXY=http://$host_ip:7890
    export http_proxy=http://$host_ip:7890
    export https_proxy=http://$host_ip:7890
    echo "Proxy set to $HTTP_PROXY"
}

function unset_proxy() {
    unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy
    echo "Proxy unset"
}

Method 2: Run proxy directly in WSL2

Install Clash or another proxy tool inside WSL2 for a more straightforward setup:

bash

# Install clash in WSL2
wget https://github.com/Dreamacro/clash/releases/...
# After configuration
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

IDE Proxy Configuration

VS Code proxy settings:

Configure in VS Code's settings.json:

json

{
    "http.proxy": "http://127.0.0.1:7890",
    "http.proxyStrictSSL": false,
    "http.proxySupport": "on"
}

Or search for "proxy" in the VS Code settings UI.

Codex base URL Configuration

Regardless of proxy setup, ensure Codex can correctly connect to the API endpoint. With TeamoRouter, it's even simpler: point base_url at the TeamoRouter endpoint in ~/.codex/config.toml, then set your API Key (see the Codex install guide).

toml

# ~/.codex/config.toml: set baseUrl to TeamoRouter endpoint
model_provider = "teamorouter"
model = "gpt-6.1-sol"

[model_providers.teamorouter]
name = "TeamoRouter"
base_url = "https://api.teamorouter.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

bash

# Set API Key
export OPENAI_API_KEY=your-teamorouter-key

This eliminates the need for special proxy configuration for OpenAI API, as TeamoRouter endpoints are directly accessible from China. For which GPT-6 model to put in model and what it costs, see GPT-6 Sol API pricing, model ID and Codex CLI setup.

Common Error Troubleshooting

Error	Likely Cause	Solution
`connect ETIMEDOUT`	Proxy connection timeout	Check proxy address and port
`connect ECONNREFUSED`	Proxy service not running	Start your proxy tool
`self signed certificate`	SSL certificate error	Set `NODE_TLS_REJECT_UNAUTHORIZED=0` (testing only)
`network read timeout`	Unstable network	Switch to a more stable proxy node
`getaddrinfo ENOTFOUND`	DNS resolution failure	Set `export NODE_OPTIONS=--dns-result-order=ipv4first`

Summary

Proxy configuration is a fundamental skill for using Codex in restricted network environments. Configure all five layers — terminal, npm, Git, WSL2, and IDE — to ensure a smooth development workflow. TeamoRouter can fundamentally simplify the model communication proxy layer, letting you focus on writing code instead of wrestling with network configuration.

FAQ

Q: I've configured the proxy but still get timeouts. What should I do? A: First verify your proxy tool is running (curl -I https://www.google.com), then check that the HTTP_PROXY port matches your proxy tool's port.

Q: npm install is too slow. What can I do? A: Configure a mirror registry with npm config set registry https://registry.npmmirror.com while ensuring your npm proxy settings are correct.

Q: Do I still need these proxies if I use TeamoRouter? A: TeamoRouter solves model API access from China. You still need terminal, npm, and Git proxies for accessing GitHub and other resources. However, you can skip the OpenAI API-specific proxy configuration entirely.

Q: Can WSL2 and Windows share the same proxy? A: No, they can't share directly. WSL2 needs its own proxy configuration, typically via host IP forwarding (Method 1) or running a proxy inside WSL2 (Method 2).

Q: How do I verify Codex's baseUrl is configured correctly? A: Run codex doctor. It shows the active model provider and runs a connectivity check (GET /models) against that provider's base URL, so you can confirm the baseUrl is set up correctly.

Get Started

Sign up for TeamoRouter and get an API Key
Follow the Codex install guide to configure baseUrl and API Key
Run your first Codex task

You can also top up your TeamoRouter balance with USDT: click Pay with crypto in the top-up dialog and pay with USDT, USDC or ETH from Binance, OKX or any exchange app — no browser wallet needed, and the checkout shows which networks your amount supports (BEP20 works from $5). See how to pay with USDT.

Get Your Free Codex Setup →

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

Ready to connect?Log in · top up · create an API key — three steps to start.

Get API Key View docs

Models in this article

GPT 6.1 SolPricing, latency, uptime →

Keep reading

All posts