Connect Codex to OptScale AI#

Connect Codex CLI or Codex Desktop to OptScale AI to route model requests through the OptScale AI Gateway. The OptScale AI provider configuration is the same on Linux, macOS, and Windows.

For shared model naming rules and limitations, see External Tools.

Prerequisites#

Before configuring Codex, confirm that:

Codex CLI or Codex Desktop is installed.
An organization exists and at least one Active provider is configured.
Allowed providers are assigned to the user connecting Codex to OptScale AI.
The OptScale AI deployment is accessible over HTTPS with a valid TLS certificate.

In Chat, copy Base URL, API key, and Model name from Connect this model to external tools → OPENAI-COMPATIBLE. For details, see Get connection values from Chat.

Configure the API key#

We recommend storing the OptScale AI API key in the OPTSCALE_API_KEY environment variable instead of adding it directly to config.toml.

This approach:

reduces the risk of accidentally exposing the API key when sharing, copying, or committing configuration files;
keeps credentials separate from the Codex configuration, so the API key can be updated or rotated without modifying config.toml.

Codex retrieves the API key from the OPTSCALE_API_KEY environment variable configured below.

Linux and macOS#

Open a terminal and run:

export OPTSCALE_API_KEY='<API_KEY>'

Replace <API_KEY> with the API key copied from OptScale AI.

Verify that the variable is set without displaying the key:

if [ -n "$OPTSCALE_API_KEY" ]; then echo "API key is set"; fi

Expected output:

API key is set

Note

export sets the environment variable for the current shell session. Start Codex from that session. To make the variable available in future sessions, add it to the appropriate shell configuration.

Windows#

Open PowerShell and run:

[Environment]::SetEnvironmentVariable(
    "OPTSCALE_API_KEY",
    "<API_KEY>",
    "User"
)

Replace <API_KEY> with the API key copied from OptScale AI.

Verify that the variable is set without displaying the key:

if ([Environment]::GetEnvironmentVariable("OPTSCALE_API_KEY", "User")) {
    "OPTSCALE_API_KEY is set"
}

Expected output:

OPTSCALE_API_KEY is set

If Codex is already running, restart it after setting the environment variable so that it can use the new value.

Configure Codex#

Open the user-level Codex configuration file:

Linux and macOS

~/.codex/config.toml

Windows

%USERPROFILE%\.codex\config.toml

If Codex Desktop already stores application settings in this file, keep the existing configuration.

At the top level of config.toml, add:

model = "<MODEL_NAME>"
model_provider = "optscale_ai"

Add the OptScale AI provider configuration:

[model_providers.optscale_ai]
name = "OptScale AI"
base_url = "<BASE_URL>"
env_key = "OPTSCALE_API_KEY"
wire_api = "responses"

Replace:

<MODEL_NAME> with the Model name copied from OptScale AI.
<BASE_URL> with the Base URL copied from OptScale AI.

For example:

model = "OpenAI_12345678-1234-1234-1234-123456789abc/gpt-4.1"
model_provider = "optscale_ai"

[model_providers.optscale_ai]
name = "OptScale AI"
base_url = "https://my.optscale.ai/llm_proxy/12345678-1234-1234-1234-123456789abc/v1"
env_key = "OPTSCALE_API_KEY"
wire_api = "responses"

The env_key setting contains the name of the environment variable that stores the API key, not the API key itself.

If config.toml already contains other sections, keep model and model_provider at the top level of the file, outside any section.

Save the configuration file.

Start Codex#

Codex CLI#

Navigate to the project directory and start Codex:

cd <PROJECT_DIRECTORY>
codex

Codex Desktop#

Start Codex Desktop.
Click Select project.
Select the project directory.
Start a new chat for the project.

Verify the connection#

In Codex CLI or Codex Desktop, send the following prompt:

Reply with exactly: OptScale AI connection works.

The expected response is:

OptScale AI connection works.

In the Admin Console, open Analytics → Traces and confirm that a row appears for the selected Provider and Model. Requester is the user for whom the connection was configured.