Codex

Codex CLI selects model providers from local configuration. To use Moxus AI, add a custom provider to Codex config.toml and let Codex read the API key from either an environment variable or auth.command.

This page applies to Codex CLI or local Codex environments that support config.toml and custom model_providers. Codex versions can differ. If your version reports unsupported fields, follow the current Codex error message and built-in help.

Values

Field	Value
Base URL	`https://moxus.cloud/v1`
API Key	`sk-your-key`
API key environment variable	`MOXUS_API_KEY`
Provider name	`custom`
Default request mode	Responses API
Model	Copy the exact model name from Models and pricing

Install Codex CLI

Install first, then run the version check separately. Do not put install, update, and verification commands into one copyable block.

macOS / Linux
Windows PowerShell
npm
Homebrew

Install:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Verify:

codex --version

Install:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

If the same PowerShell window still says codex is not recognized, refresh the current PATH first:

$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")

Verify:

codex --version

Install:

npm install -g @openai/codex

Verify:

codex --version

Install:

brew install --cask codex

Verify:

codex --version

Recommended: import configuration from an API key

On the Moxus AI API keys page, each key row has an Import configuration action. Choose Codex to generate a terminal script for the selected key and current site address.

Open the API keys page

Go to the Moxus AI console API keys page and find the key you want Codex to use.

Open Import configuration

Open the actions menu for that key, choose Import configuration, then switch to Codex.

Copy the script for your system

Use “macOS / Linux terminal” for macOS or Linux. Use “Windows PowerShell” for Windows.

Run the script directly in your terminal

Open your terminal, paste the copied script directly into the same terminal window, and press Enter. The script works in both zsh and Bash, and the current terminal can use the new configuration as soon as it finishes.

The generated script does the following:

System	What it writes
macOS / Linux	Writes `${CODEX_HOME:-$HOME/.codex}/config.toml`, creates `${CODEX_HOME:-$HOME/.codex}/moxus-env.sh` for `MOXUS_API_KEY`, then adds an auto-load block to `~/.zshrc` and `~/.bashrc`
Windows PowerShell	Writes `%USERPROFILE%\.codex\config.toml`, writes `%USERPROFILE%\.codex\moxus-api-key.txt`, and uses `auth.command` in `config.toml` to read that file; it also sets `MOXUS_API_KEY` as a current-user environment variable for terminal compatibility

The current Import configuration script overwrites Codex config.toml. If you already have other providers, models, sandbox settings, or project defaults, back up the file before running the script.

Use the “macOS / Linux terminal” script for macOS or Linux, and the PowerShell script for Windows. Both can be pasted and run directly in their respective terminals; no temporary file or extra command is required.

Codex config file location

Codex reads .codex/config.toml from your user directory by default. If you set CODEX_HOME, the file moves to $CODEX_HOME/config.toml.

macOS
Linux
Windows

Default path: /Users/your-name/.codex/config.tomlCreate the directory:

mkdir -p ~/.codex

Open the directory:

open ~/.codex

Default path: /home/your-name/.codex/config.tomlCreate the directory:

mkdir -p ~/.codex

Check the file:

ls ~/.codex/config.toml

Default path: C:\Users\your-name\.codex\config.tomlCreate the directory:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"

Open the directory:

explorer $env:USERPROFILE\.codex

The file name must be config.toml. If you create it with Notepad, make sure it is not saved as config.toml.txt.

Manual config.toml setup

If you do not use Import configuration, create or edit config.toml manually:

model_provider = "custom"
model = "gpt-5.4"

[model_providers.custom]
name = "custom"
base_url = "https://moxus.cloud/v1"
env_key = "MOXUS_API_KEY"
requires_openai_auth = false
wire_api = "responses"

Key fields:

Field	Meaning
`model_provider`	The default provider name. It must match `[model_providers.custom]`
`model`	The default model Codex uses. You can change it to an exact model name from Models and pricing
`base_url`	Moxus AI’s OpenAI-compatible endpoint
`env_key`	Codex reads the key from `MOXUS_API_KEY`, so the secret does not need to be stored in `config.toml`
`requires_openai_auth`	Set to `false` so Codex does not require OpenAI account auth for this provider
`wire_api`	Set to `responses` to use the Responses API request shape

Manually set the API key

Current terminal only

Use this for a temporary test. macOS and Linux replace only the key read during this launch. Windows also overrides the provider for this launch because the Windows config.toml generated by Import configuration uses auth.command to read a key file. The variable disappears when you close the terminal.

macOS / Linux
Windows PowerShell

MOXUS_API_KEY="sk-your-key" codex \
  -c 'model_provider = "custom"' \
  -c 'model = "gpt-5.4"' \
  -c 'model_providers.custom = { name = "custom", base_url = "https://moxus.cloud/v1", env_key = "MOXUS_API_KEY", requires_openai_auth = false, wire_api = "responses" }'

Copy and run the complete block. It applies to this launch only and does not change the existing config.toml or key file:

$env:MOXUS_API_KEY="sk-your-key"
codex `
  -c 'model_provider = "moxus_temp"' `
  -c 'model = "gpt-5.4"' `
  -c 'model_providers.moxus_temp.name = "moxus_temp"' `
  -c 'model_providers.moxus_temp.base_url = "https://moxus.cloud/v1"' `
  -c 'model_providers.moxus_temp.env_key = "MOXUS_API_KEY"' `
  -c 'model_providers.moxus_temp.requires_openai_auth = false' `
  -c 'model_providers.moxus_temp.wire_api = "responses"'

For persistent setup or desktop use, choose Codex from Import configuration on the API keys page. The generated script writes both the provider configuration and key, and configures the launch environment for the current operating system.

Verify

Confirm that Codex can read the config file and environment variable, then run a small task. Check the key variable:

macOS / Linux
Windows PowerShell

echo "$MOXUS_API_KEY"

echo $env:MOXUS_API_KEY

Run a test task:

codex "hello"

Then open Usage and confirm the request appears under the expected API key.

Troubleshooting

Can I put the API key directly in config.toml?

Not recommended. The latest Windows Codex script generated from /keys does not write the plain-text key into config.toml; it stores the key in %USERPROFILE%\.codex\moxus-api-key.txt and reads it through auth.command. macOS and Linux still use environment variables. This keeps the secret out of config.toml and makes key rotation easier.

My previous Codex configuration disappeared after Import configuration

The /keys Codex script overwrites config.toml. If you already have custom settings, back up the file first or manually merge [model_providers.custom] into your existing config.

How do I remove the Moxus AI configuration for Codex?

If config.toml was created only by the Import configuration script, use these commands to remove the Moxus AI configuration, key, and current-session variable. If you merged other providers or personal settings into that file, do not delete the whole config.toml; remove only the custom provider configuration.macOS / Linux:

CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"

rm -f "$CODEX_DIR/config.toml" "$CODEX_DIR/moxus-env.sh"

for profile in "$HOME/.zshrc" "$HOME/.bashrc"; do
  [ -f "$profile" ] || continue
  sed -i.bak '/# Moxus AI Codex start/,/# Moxus AI Codex end/d' "$profile"
done

unset MOXUS_API_KEY
if command -v launchctl >/dev/null 2>&1; then
  launchctl unsetenv MOXUS_API_KEY
fi

Windows PowerShell:

$CodexDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }

Remove-Item (Join-Path $CodexDir "config.toml") -Force -ErrorAction SilentlyContinue
Remove-Item (Join-Path $CodexDir "moxus-api-key.txt") -Force -ErrorAction SilentlyContinue

[Environment]::SetEnvironmentVariable("MOXUS_API_KEY", $null, "User")
Remove-Item Env:MOXUS_API_KEY -ErrorAction SilentlyContinue

Fully quit and reopen Codex afterwards. On macOS, restart the desktop app as well.

Authentication fails

First check which config style you are using. If config.toml uses env_key = "MOXUS_API_KEY", confirm that the terminal or GUI environment launching Codex can read that variable. Reopen the terminal after terminal setup, and GUI-launched Windows clients may still require a system sign-out/sign-in. If you are using the latest Windows script generated from /keys, confirm that %USERPROFILE%\.codex\moxus-api-key.txt exists and that [model_providers.custom.auth] in config.toml has not been overwritten by an older config. Then fully quit and reopen Codex.

After installing on Windows, codex --version says the command cannot be found

This usually means installation completed but the current PowerShell window has not refreshed its PATH yet. Run:

$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")

Then run codex --version again. If it still fails, close PowerShell, open a new window, and try again.

Model not found

Set model to the exact model name from Models and pricing. Do not use a client display name or shorthand.

wire_api or provider fields are unsupported

Your Codex version may use a different custom provider format. Keep the Base URL and API key values, then adjust wire_api or provider fields according to the current Codex error message.

Overview

Platform

Guides

Integrations

Values

Install Codex CLI

Recommended: import configuration from an API key

Codex config file location

Manual config.toml setup

Manually set the API key

Current terminal only

Verify

Troubleshooting

Next steps

​Values

​Install Codex CLI

​Recommended: import configuration from an API key

​Codex config file location

​Manual config.toml setup

​Manually set the API key

​Current terminal only

​Verify

​Troubleshooting

​Next steps

Values

Install Codex CLI

Recommended: import configuration from an API key

Codex config file location

Manual config.toml setup

Manually set the API key

Current terminal only

Verify

Troubleshooting

Next steps