CapaKraken/docs/azure_codex_setup.md

Azure OpenAI / Codex CLI Setup

This document collects the steps you need when working with the Codex CLI and the Azure OpenAI service. The examples assume that you have two deployments available in your Azure OpenAI project:

• gpt-5.4
• gpt-5.4-pro

Both of these models are currently active in our environment and can be referenced from the CLI configuration.

---

1. Prerequisites

1. Azure Subscription – an active subscription with access to the Azure OpenAI resource.
2. Model Deployment – make sure at least one of the Codex-compatible models has been deployed. In our case the deployments are named gpt-5.4 and gpt-5.4-pro.
3. Endpoint & key – note down the endpoint URL and the API key from the Azure portal; you will need them for the configuration file.
4. Supported OS – macOS 12+, Ubuntu 20.04+, or Windows 11 via WSL2.
5. Tools – Node.js + npm installed on your machine.

---

2. Install and configure the Codex CLI

npm install -g @openai/codex

Create a configuration folder in your home directory:

mkdir -p ~/.codex

and then create a config.toml inside that folder with the following content (replace the placeholders with your actual values):

# ~/.codex/config.toml

# default model to use; switch between "gpt-5.4" and "gpt-5.4-pro" as needed
model = "gpt-5.4"
model_provider = "azure"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://<your-resource-name>.openai.azure.com/"
env_key = "AZURE_OPENAI_API_KEY"

The model field can be changed at any time to gpt-5.4-pro when you want the higher‑tier model; the CLI reads this file on each invocation.

Finally, export your API key into the environment:

export AZURE_OPENAI_API_KEY="<your-key-here>"

On Windows (PowerShell) use:

setx AZURE_OPENAI_API_KEY "<your-key-here>"

or set it in the System environment variables via the Control Panel.

---

With that in place you can run codex --help and start using the CLI against your Azure deployment.

Note: the CLI will automatically pick the model specified in config.toml. To switch models you may either edit the file or pass --model gpt-5.4-pro on the command line.

---

This repository does not actually contain the .codex folder – it lives in your home directory – but the sample file above is provided for reference. You can copy it into your own environment when you set up the CLI.