How To: Running Codex CLI on Windows with Azure OpenAI

1  Introduction & Scope

What this guide covers

• End‑to‑end setup of OpenAI Codex CLI on a Windows laptop.
• Running Codex inside Windows Subsystem for Linux 2 (WSL 2).
• Connecting Codex to Azure OpenAI deployments (reasoning/chat & Codex/responses models).
• Workflow for editing a C# project in Visual Studio while Codex assists from WSL.
• Troubleshooting and performance tuning.

Audience — Windows developers who want a local terminal‑based coding agent powered by Azure OpenAI and need tight integration with Visual Studio, Git, and enterprise workflows.

2  System Prerequisites

Optional but handy: nvm‑windows, ripgrep, fd (fdfind), Visual Studio 2022/2024.

3  Installing & Configuring WSL 2

3.1 Install WSL 2 & Ubuntu

# Elevated PowerShell
wsl --install -d Ubuntu

3.2 Update Ubuntu packages

sudo apt update && sudo apt upgrade -y

3.3 Understanding file paths

4  Installing Node.js on Windows & WSL

4.1 Windows (nvm‑windows)

nvm install 24
nvm use 24
node --version   # v24.x.x

4.2 Ubuntu

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version   # v22.x.x or newer

4.3 Verify npm

npm --version

5  Installing Codex CLI

5.1 Global install

# Inside Ubuntu WSL
sudo npm install -g @openai/codex
codex --version  

5.2 Common install errors

• EACCES  →  add sudo or change npm prefix.
• Unsupported platform: win32  →  run in WSL, not PowerShell.
• 404 on install  →  ensure Node ≥ 22 and npm registry reachable.

5.3 Confirm Rust‑native build

codex doctor
# Output should include: "engine: rust" and "version: 0.2.0" (or later)

6  Azure OpenAI: Resource & Deployments

6.1 Create the resource

1. Azure Portal → Create a resource → Azure OpenAI.
2. Select subscription, region, resource group, and a unique resource name (e.g. my‑openai‑resource).

6.2 Generate API keys & get the endpoint

Azure Portal → your OpenAI resource → Keys & Endpoints.
Copy:

• AZURE_OPENAI_API_KEY
• https://<resource‑name>.openai.azure.com/

6.3 Deploy models

7  Building ~/.codex/config.toml

7.1 TOML basics

File lives in /home/<user>/.codex/config.toml.
Each model_provider block defines an Azure endpoint; each profile selects a model + provider.

7.2 Providers & profiles sample

# Default profile is codex (responses API)
profile = "codex"

# Codex provider
[model_providers.azurecodex]
name         = "Azure"
base_url     = "https://<RESOURCE>.openai.azure.com/openai"
env_key      = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api     = "responses"

[profiles.codex]
model          = "codex-mini-latest"
model_provider = "azurecodex"

# GPT‑4o provider
[model_providers.azureo4]
name         = "Azure"
base_url     = "https://<RESOURCE>.openai.azure.com/openai/deployments/o4-mini"
env_key      = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }

[profiles.o4]
model          = "o4-mini"
model_provider = "azureo4"

7.3 Common pitfalls

• Deployment name ≠ model name; the left column in Azure Portal is the deployment.
• wire_api="responses" only for the /responses endpoint.
• API version must be ≥ 2025-03-01-preview for /responses.

8  Environment Variables

8.1 Set the API key

# in Ubuntu WSL
export AZURE_OPENAI_API_KEY="<your-secret-key>"

Add the same line to ~/.bashrc (or ~/.zshrc) for persistence.

8.2 Optional tuning vars

9  Launching Codex CLI

9.1 Basic launch (default profile)

cd /mnt/c/Path/To/Your/Repo
codex

9.2 Switching profiles on demand

• codex --profile codex  → Codex (responses) model
• codex --profile o4  → GPT‑4o deployment

9.3 Enable autonomous edits

codex --profile codex --write --approval=Trusted

9.4 Resetting the session

• Hard reset: press Ctrl+D or type exit, then relaunch.
• Soft reset: type “Forget everything so far”.

10  Performance Optimisations on /mnt/c Repos

10.1 Install fast search tools

sudo apt install -y ripgrep fd-find
ln -sf "$(which fdfind)" ~/.local/bin/fd   # optional short alias

10.2 Raise Codex search timeout

export CODEX_COMMAND_TIMEOUT_MS=30000
# or put in ~/.bashrc

10.3 Exclude heavyweight paths

# in ~/.codex/config.toml, inside a profile
exclude_globs = ["bin/", "obj/", "*.png", "*.jpg", "node_modules/"]

10.4 When to consider moving the repo

If recursive searches still hit timeouts and you do not require Visual Studio
to open the repo directly from NTFS, clone or move it to ~/work/ for ext4 speed.

11  Working with Visual Studio C# Projects

11.1 Keep repo on Windows for VS

C:\Dev\MyProject    # opened by Visual Studio
/mnt/c/Dev/MyProject # accessed by Codex

11.2 Typical Codex commands

• “Summarise Program.cs”
• “Add XML docs to all public methods in *.cs”
• “Generate unit tests for UserService.cs”
• “Refactor controllers to use dependency injection”

11.3 Reviewing & committing Codex edits

git diff          # inspect changes
git add .
git commit -m "Codex refactor: DI in controllers"
git push origin feature/codex-refactor

12  Command Reference & Shortcuts

13  Troubleshooting

13.1 404 errors

• Symptom: “stream error: unexpected status 404”
• Causes: wrong deployment name, missing /responses vs. /deployments/<id>, or mismatched api-version.
• Fixes:
  • Verify deployment name in Azure Portal (left‑most column).
  • For Codex models use base_url ... /openai + wire_api="responses".
  • Use api-version ≥ 2025‑03‑01‑preview for /responses.

13.2 rg: command not found / timeouts

• Install ripgrep and fd-find in WSL:

sudo apt install -y ripgrep fd-find
ln -sf "$(which fdfind)" ~/.local/bin/fd   # optional alias

• Raise timeout (30 s): export CODEX_COMMAND_TIMEOUT_MS=30000

13.3 Unsupported platform / old Node

• Codex CLI v0.2.x needs Node 22+ and Linux. Run inside Ubuntu WSL: node --version

13.4 Sandbox or write‑mode refusals

• Add --write or set CODEX_SANDBOX=write to allow edits.
• Skip prompts with --approval=Trusted or CODEX_APPROVAL=Trusted.

14  Security & Best Practices

14.1 Protect API keys

• Store keys in environment variables or OS‑level secret store; never commit to Git.
• Use separate keys for dev vs. CI.

14.2 Branch strategy for Codex edits

• Create feature branches (feature/codex‑refactor).
• Let Codex commit into that branch; merge via pull request.

14.3 Audit Codex changes

• Always run git diff or VS Diff before pushing.
• Add unit tests for large refactors.

14.4 Cost & rate‑limit management

• Use Azure quota alerts to monitor spend.
• Prefer smaller context models (e.g., o4-mini) for bulk tasks.

15  Next Steps & Advanced Topics

15.1 Integrate Codex with VS Code

• Use VS Code terminal to launch Codex tasks.
• Create tasks.json entries that call codex --write.

15.2 Run Codex tasks in CI

• Install Codex CLI in GitHub Actions or Azure Pipelines.
• Run lint‑style prompts or auto‑refactor before build stage.

15.3 Using Entra ID (Azure AD) tokens

• Replace static keys with:

export AZURE_OPENAI_API_KEY=$(az account get-access-token \
  --scope https://cognitiveservices.azure.com/.default \
  | jq -r .accessToken)

15.4 Automating recurring Codex chores

• Bash scripts: codex --profile codex --write --approval=Trusted \
<<EOF
Refactor ...
EOF
• Schedule via Windows Task Scheduler or cron in WSL.