Skip to content

alt text

Codex Extension in VS Code

Note

This documentation file was written with Codex's help.

This guide describes how to configure the Codex VS Code extension for Azure OpenAI. For AGENTS.md, custom agents, and skills, see Agents and Skills for Codex. For MCP servers, see MCP Servers for Codex.

Prerequisites

Installation

1. Install the authentication dependency

Install the Python MSAL client and its secure token-cache extension:

py -m pip install --user msal msal-extensions

Install the Python MSAL client and its secure token-cache extension:

python3 -m pip install --user msal msal-extensions

2. Create the MSAL Authentication Script

Download the Python script and save it to a known location:

Link to Script

We suggest C:\Tools\cnh-token.py on Windows or /Users/<username>/Tools/cnh-token.py on macOS.

3. Configure Codex on Windows/macOS

Open a terminal in PowerShell and create the Codex configuration folder:

mkdir $HOME\.codex

Create the Codex configuration file:

New-Item -ItemType File -Path "$HOME\.codex\config.toml" -Force

Open the newly created config.toml file and add the following configuration:

model = "gpt-6-luna"
model_provider = "azure"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://aiml-apim-dev.azure-api.net/ai/coding-assistants/codex"
wire_api = "responses"
request_max_retries = 0
stream_max_retries = 0

[model_providers.azure.auth]
command = "py"
args = [
    "C:\\Tools\\cnh-token.py"
]
timeout_ms = 120000

[profiles.fast]
model = "gpt-6-luna"
model_reasoning_effort = "low"

[profiles.balanced]
model = "gpt-6-sol"
model_reasoning_effort = "medium"

[profiles.deep]
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[windows]
sandbox = "elevated"

Close and reopen VS Code after setting the environment variable so the extension can read it.

Open Terminal and create the Codex configuration folder: 

mkdir -p "$HOME/.codex"

Create the Codex configuration file:

touch "$HOME/.codex/config.toml"

Open the newly created config.toml file and add the following configuration:

model = "gpt-6-luna"
model_provider = "azure"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://aiml-apim-dev.azure-api.net/ai/coding-assistants/codex"
wire_api = "responses"
request_max_retries = 0
stream_max_retries = 0

[model_providers.azure.auth]
command = "python3"
args = [
    "/Users/<username>/Tools/cnh-token.py"
]
timeout_ms = 120000

[profiles.fast]
model = "gpt-6-luna"
model_reasoning_effort = "low"

[profiles.balanced]
model = "gpt-6-sol"
model_reasoning_effort = "medium"

[profiles.deep]
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

Close and reopen VS Code after setting the environment variable so the extension can read it.

code .

4. Install the Codex Extension

  1. Open VS Code.
  2. Open the Extensions pane.
  3. Search for Codex - OpenAI's coding agent.
  4. Install the extension from the VS Code Marketplace.

5. Configure the Codex Extension

  1. Open the Codex pane in VS Code.
  2. Confirm that the Azure OpenAI provider appears in the provider list.
  3. Set permissions to Custom.
  4. Review the allowed actions and set them according to the work you want Codex to perform.

Codex uses the same $HOME\.codex\config.toml configuration on Windows or $HOME/.codex/config.toml configuration on macOS from both the CLI and VS Code extension. If the provider does not appear, verify the TOML syntax, restart VS Code, and confirm the authentication script was able to execute.

Troubleshooting

Windows setup didn't finish

Windows users may encounter a message in the Codex extension box that says "Windows setup didn't finish. Setup could not complete". Instead of clicking "Retry setup", you will need to reopen your config.toml file. Add the following block of code above the section that says [model_providers.azure]:

[windows]
sandbox = "elevated"

Save the file, then restart VS Code.

Agents and Skills

For details on AGENTS.md, custom agents, and skills, see Agents and Skills for Codex.

MCP Servers

For details on MCP servers and Codex configuration, see MCP Servers for Codex.

Further Reading

Codex Config File Basics