Codex on Windows: Common Issues and Solutions for PowerShell, WSL2, PATH, and Proxy

When using Codex for AI-powered coding on Windows, developers frequently encounter issues like PowerShell execution policy blocks, complex WSL2 configuration, unresponsive PATH settings, and confusing proxy setups. This guide breaks down each common pitfall with proven solutions and practical command examples.

Most Common Windows Codex Issues

Based on community feedback, the most frequently encountered problems on Windows include:

1. PowerShell execution policy blocks: Windows prevents script execution by default, causing Codex installation to fail
2. Command not found: The terminal can't find the codex command after installation
3. WSL2 configuration complexity: Extra network and toolchain configuration needed for Codex in WSL2
4. Proxy misconfigurations: Windows and WSL2 proxies operate independently
5. Node.js version compatibility: Different version management (nvm-windows vs nvm on Linux)
6. Path containing spaces: Chinese characters or spaces in Windows user/directory paths cause installation errors

Quick Windows Setup with TeamoRouter

Using TeamoRouter on Windows is the simplest approach. No need to deal with OpenAI API proxy issues — just configure the baseUrl directly.

Configuring TeamoRouter on Windows:

# Set environment variables in PowerShell
$env:CODEX_BASE_URL="https://api.teamorouter.com/v1"
$env:CODEX_API_KEY="your-teamorouter-key"

# Set as system environment variables (persistent)
[System.Environment]::SetEnvironmentVariable('CODEX_BASE_URL', 'https://api.teamorouter.com/v1', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('CODEX_API_KEY', 'your-teamorouter-key', [System.EnvironmentVariableTarget]::User)

Does Windows Support Codex?

Absolutely. Codex officially supports Windows, macOS, and Linux. On Windows, you can use it through:

• PowerShell: Native Windows terminal, full Codex command support
• CMD: Traditional command-line interface, fully functional
• WSL2: Linux subsystem environment for a near-native Linux experience
• Git Bash: Lightweight terminal bundled with Git for Windows

Installing Codex in PowerShell

Install Node.js (if not already installed):

# Install Node.js via winget
winget install OpenJS.NodeJS.LTS

# Verify installation
node --version
npm --version

Install Codex:

# Install Codex globally
npm install -g @openai/codex

Set execution policy (if you encounter permission errors):

# Check current execution policy
Get-ExecutionPolicy

# Set to RemoteSigned (allows local scripts, remote scripts need signature)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Installing Codex in WSL2

WSL2 offers one of the best environments for running Codex on Windows.

Install WSL2:

# Run PowerShell as Administrator
# Install WSL
wsl --install

# Set WSL2 as default
wsl --set-default-version 2

# List installed Linux distributions
wsl -l -v

Install Codex in WSL2:

# Update package manager
sudo apt update && sudo apt upgrade -y

# Install Node.js (using NodeSource)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
node --version
npm --version

# Install Codex globally
npm install -g @openai/codex

# Verify installation
codex --version

PATH Issues

Codex command not found in PowerShell:

# Check npm global install path
npm config get prefix
# Usually at C:\Users\<username>\AppData\Roaming\npm

# Manually add to PATH (persistent in PowerShell)
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Users\$env:USERNAME\AppData\Roaming\npm",
    "User"
)

# Apply immediately (current session)
$env:Path = [Environment]::GetEnvironmentVariable("Path", "User")

Codex command not found in WSL2:

# Check npm global bin path
npm bin -g
# Usually in /usr/local/bin or /home/<user>/.npm-global/bin

# Add to PATH (~/.bashrc)
export PATH=$PATH:/home/$(whoami)/.npm-global/bin
source ~/.bashrc

PowerShell Execution Policy Issues

PowerShell's execution policy is a Windows-specific security feature that can block Codex-related scripts.

Common error:

Cannot load file codex.ps1 because running scripts is disabled on this system.

Solutions:

# Method 1: Change execution policy (recommended)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Method 2: Bypass for a single script (not recommended)
powershell -ExecutionPolicy Bypass -File "codex.ps1"

Execution policy levels:

• Restricted: Default, blocks all script execution
• RemoteSigned: Local scripts run, remote scripts need signature (recommended)
• AllSigned: All scripts must be signed
• Unrestricted: All scripts can run (not recommended)

Proxy Differences Between Windows and WSL2

Windows and WSL2 proxy configurations are completely independent — this is one of the most common sources of confusion.

Windows system proxy:

# Temporary PowerShell proxy
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

# System-level proxy (Control Panel → Internet Options → Connections → LAN Settings)

WSL2 proxy configuration (cannot share Windows proxy variables):

# Get Windows host IP
export host_ip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')

# Set proxy to host machine
export HTTP_PROXY=http://$host_ip:7890
export HTTPS_PROXY=http://$host_ip:7890

Key difference: Windows proxy uses 127.0.0.1, WSL2 proxy must use the host machine IP (in WSL2, 127.0.0.1 points to WSL2 itself, not the Windows host).

Node.js / Git Environment Issues

Node.js version management on Windows:

Windows uses nvm-windows, which differs from the nvm used on Linux/macOS.

# Install nvm-windows via winget
winget install nvm-windows

# Install a specific version
nvm install 22.0.0

# Use a specific version
nvm use 22.0.0

# List installed versions
nvm list

Git for Windows configuration:

# Install Git
winget install Git.Git

# Configure proxy (same as Linux)
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

Common Node.js compatibility issues:

# Node.js version too old for Codex compatibility
# Upgrade to LTS version
nvm install 22.0.0
nvm use 22.0.0

# npm cache issues
npm cache clean --force
npm install -g @openai/codex

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.

FAQ

Q: Codex shows "command not found" on Windows. What should I do? A: Check that the npm global install path is in your PATH. It's usually at C:\Users\<username>\AppData\Roaming\npm and needs to be added manually to the system PATH.

Q: Which is better for running Codex — WSL2 or PowerShell? A: Both work well. WSL2 provides an environment closer to production Linux and simpler Node.js management. PowerShell runs natively without a VM layer. Choose based on your project environment.

Q: What advantages does TeamoRouter offer on Windows? A: No need to configure a proxy specifically for the OpenAI API. Just set the baseUrl to the TeamoRouter endpoint. The environment variable configuration is identical to Linux/macOS, making cross-platform migration seamless.

Q: How do I permanently change the PowerShell execution policy? A: Run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser. This only affects your user account, not other system users.

Q: How does Codex perform on Windows? A: Codex is a lightweight CLI and performs well on Windows. However, if using WSL2, file system I/O (especially across /mnt/c operations) has some performance overhead. Consider keeping projects in WSL2's native file system (~/project).