OpenAI’s Codex CLI is fast and pleasant, and on Windows it behaves best inside WSL. It reads environment variables and a config.toml, and it assumes a Unix-like shell — exactly what WSL provides. This guide installs and runs Codex in WSL, including pointing it at a cheaper model, with the WSL details that matter.
If WSL isn’t installed, start with the WSL install guide. For the provider config in depth, see Codex CLI custom provider setup.
Step 1: Install Codex CLI in WSL
Recent Codex CLI ships as a Rust binary, though install methods vary (some via npm). Follow the Codex repository instructions inside WSL so the binary and its config live in the Linux environment. If it’s via npm, install Node first with nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts
# then install Codex per the repo (npm or release binary)
codex --versionStep 2: Sign in or add a cheap provider
With an OpenAI account, sign in per the docs. To run on a cheaper model, add a provider in ~/.codex/config.toml:
model = "deepseek-chat"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "chat"Export the key in your shell profile so it persists:
echo 'export DEEPSEEK_API_KEY="sk-your-key"' >> ~/.bashrc
source ~/.bashrc
codexSwap the block for Qwen, GLM, or Kimi.
Step 3: Work in the Linux file system
For big repos, copy the project into your Linux home so Codex’s file operations stay fast:
cp -r /mnt/c/Users/YourName/myproject ~/myproject
cd ~/myproject
codexSee access your Windows files from WSL for the file-bridge details.
Codex in WSL essentials
| Install per repo | Rust binary or npm, inside WSL |
|---|---|
| ~/.codex/config.toml | Provider config in Linux home |
| wire_api = "chat" | Required for third-party providers |
| key in ~/.bashrc | Persist across shells |
| project in ~ | Faster file operations |
WSL gotchas
codex: command not found— reopen the shell after install so PATH updates.- Format/streaming errors — set
wire_api = "chat"for non-OpenAI providers. - Key not found — export it in
~/.bashrcandsourceit; inline only lasts the session. - Slow on big repos — move the project into your Linux home.
Codex CLI on WSL checklist
- WSL installed; Codex installed inside WSL
- config.toml in ~/.codex (Linux home)
- Cheap provider block with wire_api = "chat" (optional)
- API key exported in ~/.bashrc
- Active project in Linux home; tested
Wrapping up
On Windows, run Codex CLI in WSL for the cleanest experience: install it inside the Linux environment, keep config.toml in ~/.codex, and optionally add a cheap provider with wire_api = "chat" plus a key in ~/.bashrc. Keep active projects in your Linux home for speed.
For the provider details, see Codex CLI custom provider setup and the per-model guides like DeepSeek with Codex CLI.
