Blog

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

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.

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.6% 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's Node.js runtime uses the http/https modules, which require HTTP_PROXY environment variables to route through a proxy

Understanding this distinction explains why explicit terminal proxy configuration is essential.

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"

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:

bash
# Set baseUrl to TeamoRouter endpoint
export CODEX_BASE_URL=https://api.teamorouter.com/v1

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

This eliminates the need for special proxy configuration for OpenAI API, as TeamoRouter endpoints are directly accessible from China.

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 "hello" --verbose and check the log output to see if the API request URL matches your configured baseUrl.

Get Started

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

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 KeyView docs
Close article
The Complete Guide to Codex Proxy Configuration: Terminal, npm, Git, and WSL2 Setup · TeamoRouter