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:

python -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:

```ps1
mkdir $HOME.codex

Create the Codex configuration file:

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

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

model = "gpt-5.6-terra"
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 = "python"
args = [
    "C:\\Tools\\cnh-token.py"
]
timeout_ms = 120000

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

[profiles.balanced]
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"

[profiles.deep]
model = "gpt-5.6-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-5.6-terra"
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-5.6-luna"
model_reasoning_effort = "low"

[profiles.balanced]
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"

[profiles.deep]
model = "gpt-5.6-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.

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