How to Set Up Azure OpenAI for the Codex Extension in VS Code

A Battle-Tested Guide — Including Every Pitfall You’ll Hit Along the Way

---

Why This Guide Exists

Most tutorials show you a happy path. This isn’t that.

This guide was written after going through every single error you can hit when connecting the OpenAI Codex VS Code extension to Azure OpenAI — 401s, 404s, missing deployments, broken URLs, silent environment variable failures — all of it. By the end, you’ll know not just what to do but why each step matters and exactly what breaks if you get it wrong.

---

What Is Codex (VS Code Extension)?

The OpenAI Codex extension for VS Code is an AI coding agent — not just a copilot that completes lines, but an agent that can read your project, understand context, write multi-file changes, and execute terminal commands on your behalf. It uses the same underlying model as ChatGPT’s Codex mode.

By default, it connects to OpenAI’s cloud directly. But if you’re in an enterprise, you may want — or be required — to route everything through Azure OpenAI, which gives you:

• Data residency inside your Azure tenant
• Private networking and RBAC
• Predictable cost management
• Compliance with enterprise security policies

---

Prerequisites

Before you start, make sure you have:

• [ ] VS Code installed
• [ ] The OpenAI Codex extension installed from the VS Code Marketplace
• [ ] An Azure subscription with access to Azure AI Foundry (formerly Azure OpenAI Studio)
• [ ] A deployed gpt-5.2-codex (or compatible) model in Azure AI Foundry
• [ ] Node.js installed (required by the Codex extension internally)
• [ ] PowerShell (Windows) or Terminal (macOS/Linux)

---

Step 1 — Deploy Your Model in Azure AI Foundry

Go to https://ai.azure.com, open your project, and navigate to Deployments.

Deploy the gpt-5.2-codex model (or gpt-5-codex). Make note of:

Value	Where to Find It
Resource name	Subdomain in the endpoint URL, e.g. sg-code from https://sg-code.openai.azure.com
Deployment name	What you named it, e.g. gpt-5.2-codex
API Key	Under the deployment’s “Keys and Endpoint” section
Deployment type	Should be Global Standard for Responses API support

⚠️ Pitfall #1 — Wait for Propagation Global Standard deployments can take 10–30 minutes to fully propagate after creation. If you get a 404 “API deployment does not exist” immediately after deploying, just wait. This is not a config error.

---

Step 2 — Find Your config.toml

The Codex extension shares configuration with the Codex CLI. The config lives at:

Windows:   C:\Users\<YourName>\.codex\config.toml
macOS/Linux: ~/.codex/config.toml

To open it directly from VS Code: click the gear icon in the Codex panel (top-right) → Codex Settings → Open config.toml.

If the file doesn’t exist, create the .codex folder and the file manually.

---

Step 3 — Write the Correct config.toml

Here is the configuration that actually works for Azure OpenAI:

model = "gpt-5.2-codex"
model_provider = "azure"
model_reasoning_effort = "medium"
model_verbosity = "medium"

[model_providers.azure]

name = “Azure OpenAI” base_url = “https://YOUR_RESOURCE_NAME.openai.azure.com/openai” env_key = “AZURE_OPENAI_API_KEY” query_params = { api-version = “2025-04-01-preview” } wire_api = “responses”

[windows]

sandbox = “elevated”

[projects.’c:\users\yourname\desktop\your-project’]

trust_level = “trusted”

Replace YOUR_RESOURCE_NAME With your Azure resource subdomain, update the project path.

---

Step 4 — Set the API Key as an Environment Variable

⚠️ Pitfall #2 — Never Hardcode the API Key This is the single biggest mistake people make. The env_key field does not accept a raw string key — it expects the name of an environment variable that holds the key. If you paste your key directly as the value, it will be treated as a variable name, looked up in your environment, not found, and you’ll get a 401 Unauthorized every time.

Set it temporarily (current session only):

PowerShell:

$env:AZURE_OPENAI_API_KEY = "your-api-key-here"

macOS/Linux:

export AZURE_OPENAI_API_KEY="your-api-key-here"

Set it permanently (recommended):

PowerShell (User-level, survives restarts):

[System.Environment]::SetEnvironmentVariable(
  "AZURE_OPENAI_API_KEY",
  "your-api-key-here",
  "User"
)

macOS/Linux — add to ~/.zshrc or ~/.bashrc:

export AZURE_OPENAI_API_KEY="your-api-key-here"

Then run source ~/.zshrc.

---

Step 5 — Launch VS Code the Right Way

⚠️ Pitfall #3 — Launching VS Code from the App Launcher If you open VS Code by clicking its icon in the taskbar, Start menu, or Dock, it launches in a new process that does not inherit environment variables from your terminal session. The Codex extension will start, look for AZURE_OPENAI_API_KEY, find nothing, and fail silently with 401.

Always launch VS Code from the terminal where you set the variable:

# Set the variable, then immediately launch VS Code
$env:AZURE_OPENAI_API_KEY = "your-key"
code .

If you’ve set the variable permanently (Step 4), open a new terminal window first — the new process will inherit the user-level environment — then run code ..

---

Step 6 — Verify Everything Before Retrying

Once VS Code is open, check inside the VS Code terminal:

echo $env:AZURE_OPENAI_API_KEY

If it prints your key → you’re good. If it’s blank → the variable isn’t loaded and Codex will fail.

Then reload the window: Ctrl+Shift+P → Developer: Reload Window

---

The Complete Error Glossary

This is what every error actually means and how to fix it:

❌ 401 Unauthorized — invalid subscription key or wrong API endpoint

Possible Cause	Fix
env_key contains the raw key string, not a variable name	Change to env_key = "AZURE_OPENAI_API_KEY"
Environment variable not set	Run $env:AZURE_OPENAI_API_KEY = "..." in terminal
VS Code not launched from terminal	Close VS Code, set env var, run code .
Wrong API key	Verify key in Azure AI Foundry → Deployments

---

❌ 404 Not Found — Resource not found (URL ends without api-version)

Possible Cause	Fix
api-version embedded in base_url incorrectly	Move it to query_params = { api-version = "2025-04-01-preview" }
Extra garbage like &_unused= in the URL	Clean the base_url to just the base endpoint

---

❌ 404 Not Found — API deployment does not exist

Possible Cause	Fix
Using /v1 path on a non-v1 deployment	Remove /v1 from base_url, use query_params for api-version
Deployment too newly created	Wait 10–30 minutes and retry
Wrong deployment name in model =	Must match exactly what you named it in Azure AI Foundry

---

❌ "low" is not supported — Supported values are: 'medium'

Possible Cause	Fix
Codex sends default verbosity low which this model doesn’t support	Add model_verbosity = "medium" to your config

---

The Anatomy of a Correct Base URL

Understanding this saves hours of debugging:

https://sg-code.openai.azure.com/openai/responses?api-version=2025-04-01-preview
│         │                       │       │         │
│         │                       │       │         └── Added by query_params
│         │                       │       └── Added by wire_api = "responses"
│         │                       └── This is your base_url
│         └── Your resource name (unique to your Azure deployment)
└── Azure OpenAI domain

So in config.toml:

• base_url = https://sg-code.openai.azure.com/openai (nothing more)
• wire_api = "responses" (adds the /responses path segment)
• query_params = { api-version = "2025-04-01-preview" } (adds the query string)

Codex assembles the full URL from these three parts. If you put the api-version inside base_urlit gets doubled or corrupted.

---

Windows-Specific Notes

⚠️ Pitfall #4 — Windows Bug with AZURE_OPENAI_API_KEY There is a known bug in some Codex CLI versions on Windows where AZURE_OPENAI_API_KEY alone isn’t picked up. As a workaround, also set OPENAI_API_KEY to the same value:

$env:AZURE_OPENAI_API_KEY = "your-key"
$env:OPENAI_API_KEY = "your-key"

⚠️ Pitfall #5 — WSL vs Native Windows If you’re using WSL (Windows Subsystem for Linux), environment variables set in PowerShell are not automatically available inside WSL. Set them inside your WSL terminal separately, or add them to ~/.bashrc / ~/.zshrc inside WSL.

---

Security Best Practices

Once it’s working, keep these in mind:

Never commit your API key to Git. Add .codex/ to your .gitignore if you ever put keys in project-level config files.

Rotate keys regularly. Azure AI Foundry lets you regenerate keys. Update your environment variable when you do.

Use Key Vault for team environments. For shared CI/CD pipelines, store the key in Azure Key Vault and fetch it at runtime rather than hardcoding it anywhere.

Set project trust intentionally. The trust_level = "trusted" setting in your config grants Codex the ability to read project-scoped config files. Only mark directories you own and control as trusted.

---

Quick Reference Card

# ~/.codex/config.toml — Working Azure OpenAI Configuration

model = "gpt-5.2-codex"          # Must match your Azure deployment name exactly
model_provider = "azure"          # Must be "azure" — not "openai-custom"
model_reasoning_effort = "medium" # "low" | "medium" | "high"
model_verbosity = "medium"        # Required for gpt-5.2-codex — "low" not supported

[model_providers.azure]

name = “Azure OpenAI” base_url = “https://YOUR_RESOURCE.openai.azure.com/openai” # No trailing slash, no /v1 env_key = “AZURE_OPENAI_API_KEY” # Variable NAME, not the key itself query_params = { api-version = “2025-04-01-preview” } # api-version goes here ONLY wire_api = “responses” # Required for Responses API

[windows]

sandbox = “elevated”

Checklist before every session:

• [ ] echo $env:AZURE_OPENAI_API_KEY prints your key
• [ ] VS Code was launched from the terminal, not the app launcher
• [ ] Deployment is at least 30 minutes old
• [ ] model = value matches the deployment name in Azure exactly

---

Summary

Setting up Codex with Azure OpenAI is straightforward once you understand the architecture — but the gap between “it looks right” and “it works” is filled with subtle mistakes around URL construction, environment variable scoping, and process inheritance.

The core insight: Codex builds the final API URL from three separate config pieces (base_url + wire_api + query_params). Understanding that eliminates 80% of the 404 errors people hit.

The other 20% is almost always the environment variable not being available to VS Code because it was opened the wrong way.

Get those two things right, and everything else falls into place.

---

Based on real troubleshooting experience connecting the OpenAI Codex VS Code extension to Azure AI Foundry (Global Standard deployment, gpt-5.2-codex, api-version 2025-04-01-preview, Windows environment).