Introduction
We have contributed the following five pull requests to add Azure OpenAI support to Codex, letting you enjoy the same Codex experience as in ChatGPT while running securely on Azure:
- PR #769
- PR #1324
- PR #1321
- PR #1778 (awaiting merge – Entra ID token-based authentication related to PR #92)
We are collaborating with OpenAI on additional updates and integrations, so stay tuned. Meanwhile, follow the steps below to get Codex running on your Azure subscription.
Pending OpenAI's NPM release
Until OpenAI publishes a new release from main, please build from source
Prerequisites
- An active Azure subscription with access to Azure OpenAI.
- Contributor permissions in Azure AI Foundry.
homebrewornpmfor installing the CLI.
| Requirement | Details |
|---|---|
| Operating systems | macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2 |
| Git (optional, recommended) | 2.23+ for built-in PR helpers |
| RAM | 4-GB minimum (8-GB recommended) |
Step 1 – Deploy a Codex model in Azure AI Foundry
- Go to Azure AI Foundry @
ai.azure.comand create a new project. - Select a reasoning model such as
codex-mini,o4-mini, oro3. - Click Deploy, choose a name, and wait about two minutes.
- Copy the Endpoint URL and generate an API key.
Step 2 – Install and Run the Codex CLI
npm install -g @openai/codex # Alternatively: `brew install codex`
codex --version # verify installation| Command | Purpose |
|---|---|
| codex | Interactive TUI |
| codex “…” | Initial prompt for interactive TUI |
| codex exec “…” | Non-interactive “automation mode” |
Step 3 – Configure ~/.codex/config.toml
Create a TOML configuration file to tell Codex how to connect to Azure and other tools. Here is an example that configures both Azure OpenAI and an MCP server for Microsoft Learn documentation.
# Set the default model and provider
model = "codex-mini"
model_provider = "azure"
# Configure the Azure provider
[model_providers.azure]
name = "Azure"
# Make sure you set the appropriate subdomain for this URL.
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY" # Or "OPENAI_API_KEY", whichever you use.
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
# Example of configuring an MCP server for MS Learn Docs
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-remote", "https://learn.microsoft.com/api/mcp"]# Linux, macOS, or WSL
export AZURE_OPENAI_API_KEY="<your-api-key>"Step 4 – Giving Codex Memory with AGENTS.md
You can give Codex extra instructions and guidance using AGENTS.md files. Codex looks for AGENTS.md files in the following places and merges them top-down, giving it context about your personal preferences, project-specific details, and the current task:
~/.codex/AGENTS.md– personal global guidance.AGENTS.mdat your repository’s root – shared project notes.AGENTS.mdin the current working directory – sub-folder/feature specifics.
For example, to help Codex understand how to write code for Azure AI Foundry Agents, you could create an AGENTS.md in your project root with the following content, derived from the Azure AI Agents SDK documentation:
# Instructions for working with Azure AI Foundry Agents
You are an expert in the Azure AI Agents client library for Python.
## Key Concepts
- **Client Initialization**: Always start by creating an `AIProjectClient` or `AgentsClient`. The recommended way is via `AIProjectClient`.
- **Authentication**: Use `DefaultAzureCredential` from `azure.identity`.
- **Agent Creation**: Use `agents_client.create_agent()`. Key parameters are `model`, `name`, and `instructions`.
- **Tools**: Agents use tools to perform actions like file search, code interpretation, or function calls.
- To use tools, they must be passed to `create_agent` via the `tools` and `tool_resources` parameters or a `toolset`.
- Example: `file_search_tool = FileSearchTool(vector_store_ids=[...])`
- Example: `code_interpreter = CodeInterpreterTool(file_ids=[...])`
- Example: `functions = FunctionTool(user_functions)`
## Example: Creating a basic agent
```python
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
# 1. Create Project Client
project_client = AIProjectClient(
endpoint=os.environ["PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
)
# 2. Get Agents Client
with project_client:
agents_client = project_client.agents
# 3. Create Agent
agent = agents_client.create_agent(
model=os.environ["MODEL_DEPLOYMENT_NAME"],
name="my-helpful-agent",
instructions="You are a helpful agent that can answer questions.",
)
print(f"Created agent with ID: {agent.id}")
```Step 5 – Explore with your coding agent
codex "write a python script to create an Azure AI Agent with file search capabilities"
# generate a unit test for src/utils/date.ts# refactor this agent to use the Code Interpreter tool instead
Step 6 – Run Codex in GitHub Actions
Codex can execute as part of your CI pipeline. Store your API key in the
repository’s secret store as AZURE_OPENAI_KEY and add a job like this to automatically update your changelog before a release:
jobs:
update_changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Update changelog via Codex
run: |
npm install -g @openai/codex
export AZURE_OPENAI_API_KEY="${{ secrets.AZURE_OPENAI_KEY }}"
codex -p azure exec --full-auto "update CHANGELOG for next release"
Step 7 – Explore more agents with AsyncLoom
- Browse detailed docs and benchmarks for other Azure-hosted agents.
- Create repo-ready configuration guides with one click.
- Experiment with GitHub Copilot Coding Agent, Cognition Devin, SRE Agent, and others.
Troubleshooting
| Symptom | Fix |
|---|---|
401 Unauthorized or 403 Forbidden |
Export your AZURE_OPENAI_API_KEY environment variable correctly.
Confirm that your key has project/deployment access. |
ENOTFOUND, DNS error, or 404 Not Found |
Verify base_url in config.toml uses your resource name and correct domain, e.g.
base_url = "https://<your-resource>.openai.azure.com/openai".
|
| CLI ignores Azure settings | Open ~/.codex/config.toml and ensure:
|
| In Codex, you get a warning that “codex-mini” is not in the list of available models for provider “azure” | This is a known issue, and we have a PR in progress to address this. Ignore this warning and proceed with codex-cli tasks. |
Conclusion
In just a few minutes you can connect an AI coding agent to your Azure tenant, keep intellectual property secure, and accelerate software delivery. Combine Codex CLI, GitHub Actions, and Gitagu’s agent catalog to build a flexible AI-powered engineering workflow. Give it a try and share what you create.
Questions or feedback? Drop a comment below
Hi Govind
Great article—thank you for sharing it!
I ran into an issue when executing codex -p azure and received an error message. Here are my current settings—do you happen to know what might be causing this? i am using WSL.
plee@plee:~$ codex --version
codex-cli 0.4.0
plee@plee:~$ cat .codex/config.json
{
"model": "codex-mini",
"provider": "azure",
"providers": {
"azure": {
"name": "AzureOpenAI",
"baseURL": "https://fine-tuning99.openai.azure.com/openai/",
"envKey": "AZURE_OPENAI_API_KEY"
}
},
...
fixed the issue and want to share it in here.
cat ~/.codex/config.toml:
profile = "azure" [model_providers.azure-ai-foundry] name = "azure" base_url = "https://fine-tuning99.openai.azure.com/openai/" env_key = "AZURE_OPENAI_API_KEY" query_params = { api-version = "2025-04-01-preview" } wire_api = "responses" [profiles.azure] model = "codex-mini" model_provider = "azure-ai-foundry" approval_policy = "on-failure"Afterwards you have to run this in your terminal:
export AZURE_OPENAI_API_KEY=””
Then run:
codex “hi”
Codex Version: codex-cli 0.5.0
For GPT-4.1 model, use api-version = “2025-03-01-preview”
Thank you, Peter. Updated the blog. More changes are coming – including Entra ID support (by Alex). I’ll also update the GIF shortly.
I followed the tutorial, but I’m encountering an error when trying to use codex-mini:
“OpenAI rejected the request. Error details: Status: 400, Code: OperationNotSupported, Type: unknown, Message: 400 The chatCompletion operation does not work with the specified model, codex-mini. Please choose different model and try again. You can learn more about which models can be used with each operation here: https://go.microsoft.com/fwlink/?linkid=2197993.. Please verify your settings and try again.”
Additionally, I noticed that after deploying codex-mini on AI Foundry, the URI field appears to be empty.
Hi Andres, Thanks for giving it a shot. When you test again, please use o4-mini or o3 from Azure OpenAI.
I’ve updated the blog to list the new PRs – two were merged today, including the codex-mini update that adds response-API support. OpenAI is slated to publish a new npm release tomorrow. Once you update codex from the npm package, codex-mini should work as well.
In the meantime, o4-mini or o3 should let you proceed
Thanks for sharing, Govind. I am trying exact same steps from past few days but not able to successfully configure Azure Endpoint and key with the codex cli. I am getting “OpenAI rejected the request. Error details: Status: 404, Code: 404, Type: unknown, Message: 404 ╯
Resource not found. Please verify your settings and try again.”
I am trying to use o4-mini model. I couldn’t find the codex model in Azure foundry.
I was able to run codex cli using my openAI account but want to run it with Azure and it is not working. Thanks in advance.
Thanks for giving it a try, Anoop.
- Make sure your `~/.codex/config.json` matches the sample in the post, and that you are launching with `codex -p azure`.
- Confirm that the `AZURE_OPENAI_API_KEY` environment variable is set.
- If you’re on Windows, test inside WSL.
There’s a known bug on the main branch (PRs #1324 and #1321 are pending approval). Until those are merged, set OPENAI_API_KEY to the same value as AZURE_OPENAI_API_KEY. After the fix lands, this extra step won’t be necessary.
Thanks, Govind. I verified the config.json and other details but still it is not working getting same error of resource not found. Thanks anyway. Maybe will wait till the issue is merged in the main branch. Thanks.
Sorry to hear that. Please try using this URL pattern: https://.cognitiveservices.azure.com/openai – note the “cognitiveservices” segment. Depending on how you configured AI Foundry or your Azure OpenAI resource, the URI may vary. I’ve updated the troubleshooting section of the blog to reflect this. Let me know if it works. Meanwhile, the two PRs were just merged, so codex-mini should be functioning soon.
waiting for codex-mini to work. o4-mini is working perfectly. getting the following:
system
⚠️ OpenAI rejected the request. Error details: Status: 400, Code: OperationNotSupported, Type: unknown, Message: 400 The chatCompletion
operation does not work with the specified model, codex-mini. Please choose different model and try again. You can learn more about which
models can be used with each operation here: https://go.microsoft.com/fwlink/?linkid=2197993.. Please verify your settings and try again.