Codex CLI configuration

Connect Codex CLI to AIMirrorX with an API key, a custom Responses provider and a complete config.toml example.

Using the desktop app? See Codex App desktop configuration.

Before you start

Create an API key in the AIMirrorX console. Your account needs a model and channel supporting Responses, streaming and tool calls. A Chat Completions-only model cannot use this configuration directly.

This guide configures a custom API provider for Codex CLI. Model access and pricing depend on your account. The model ID below is a placeholder, not an available model name.

1. Install Codex CLI

With Node.js installed, run:

npm install -g @openai/codex
codex --version

Skip this step if Codex CLI is already installed. See the official CLI documentation for platform requirements. On Windows, use a native terminal or WSL; when running in WSL, configure the files and environment inside WSL.

2. Set your API key

In the same terminal where you will start Codex, use this on macOS, Linux or WSL:

export AIMIRRORX_API_KEY="YOUR_AIMIRRORX_API_KEY"

Windows PowerShell:

$env:AIMIRRORX_API_KEY = "YOUR_AIMIRRORX_API_KEY"

Replace YOUR_AIMIRRORX_API_KEY with your AIMirrorX key. These commands affect only the current terminal session and its child processes. Set the variable again in a new terminal. Keep real keys out of project configuration and Git.

3. Edit config.toml

Open ~/.codex/config.toml, or $HOME\.codex\config.toml in Windows PowerShell. If CODEX_HOME is set, use config.toml in that directory.

model = "YOUR_RESPONSES_MODEL_ID"
model_provider = "aimirrorx"

[model_providers.aimirrorx]
name = "AIMirrorX"
base_url = "https://api.aimirrorx.com/v1"
env_key = "AIMIRRORX_API_KEY"
wire_api = "responses"
requires_openai_auth = false

Replace YOUR_RESPONSES_MODEL_ID with an account model ID supporting Responses. You can query your model list, then check its protocol capabilities:

curl https://api.aimirrorx.com/v1/models \
  -H "Authorization: Bearer $AIMIRRORX_API_KEY"

Being listed does not guarantee Responses or tool-call support.

Field	Value or purpose
`model`	Actual model ID, not a display name
`model_provider`	Must match `aimirrorx` in the provider table name
`base_url`	`https://api.aimirrorx.com/v1`; do not append `/responses`
`env_key`	The variable name `AIMIRRORX_API_KEY`, not the key itself
`wire_api`	Use the `responses` protocol
`requires_openai_auth`	`false` uses the AIMirrorX key from the environment variable

Merge these fields into existing settings without duplicating keys or tables. Put the top-level model and model_provider before TOML table headers. You do not need to edit auth.json for this method.

4. Start and verify

In the terminal containing your key, enter your project and start Codex:

cd /path/to/your/project
codex

Try a simple request such as “Summarize the project in this directory.” Check the active provider and model before development work. Restart an existing Codex session after changing its configuration.

Troubleshooting

Symptom	What to check
Missing variable or 401	Set `AIMIRRORX_API_KEY` in the current terminal and check key validity; use an AIMirrorX key
403 or model unavailable	Check token model restrictions, account permissions, balance and channel status
404	End the base URL with `/v1`; avoid duplicated `/v1` or `/responses` paths
Unsupported Responses, tool calls or parameters	Use a model/channel with those capabilities; renaming the model does not add protocol support
Another provider or ChatGPT login appears	Check project settings, launch arguments and profiles for overrides; confirm `requires_openai_auth = false`
Windows and WSL differ	Configure the user directory and environment where Codex actually runs