Skip to main content
Use this guide to run Codex with CometAPI as a model provider. Official references:

​
Prerequisites

RequirementDetails
OSmacOS, Linux, Windows native PowerShell, or Windows with WSL
Git2.23+ recommended
CodexInstall the Codex app or Codex CLI from the Codex quickstart
CometAPI API keyGet one from the CometAPI dashboard
Model IDUse a model ID from the Models page

​
Choose a setup path

We provide two options to help you configure Codex quickly.

Option 1: Configure Codex manually (recommended)

Edit the user-level ~/.codex/config.toml file directly. This is the most reliable path, especially for Windows and WSL users.

Option 2: Configure via script

Run the setup script as a shortcut. It writes the same provider configuration and stores the CometAPI API key for Codex.

​
Configure Codex manually

Codex reads personal provider defaults from the user-level ~/.codex/config.toml file. Configure the CometAPI provider there, not in a project .codex/config.toml file. Codex ignores provider and provider-auth settings in project config files. The recommended setup uses a named cometapi provider and command-backed authentication. This keeps CometAPI separate from the built-in OpenAI provider, does not require shell environment inheritance, and does not replace ~/.codex/auth.json.
Store your CometAPI API key in a local key file:
mkdir -p "$HOME/.codex"
printf "%s\n" "$COMETAPI_KEY" > "$HOME/.codex/cometapi_key"
chmod 600 "$HOME/.codex/cometapi_key"
Add this configuration to ~/.codex/config.toml:
model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"

[model_providers.cometapi.auth]
command = "sh"
args = ["-c", "cat \"$HOME/.codex/cometapi_key\""]
Windows native Codex uses $HOME\.codex, usually C:\Users\<user>\.codex. WSL uses the Linux distribution’s ~/.codex. Edit the directory that matches the environment where the Codex agent runs.

​
Use environment variable authentication

If you prefer to keep the CometAPI API key in an environment variable, use env_key instead of the [model_providers.cometapi.auth] block. Use this provider configuration only when COMETAPI_KEY is available in the environment that launches Codex: 
model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"
env_key = "COMETAPI_KEY"
Do not combine env_key with [model_providers.cometapi.auth]. Codex supports one authentication method per custom provider.

​
Run the setup script

The setup script is optional. It writes the same cometapi provider configuration to ~/.codex/config.toml, stores your CometAPI API key in ~/.codex/cometapi_key, creates backups before file changes, and verifies the configuration with codex exec when the Codex CLI is available. For macOS, Linux, or WSL, run the interactive installer: 
sh -c "$(curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh)"
For non-interactive setup, pass the API key explicitly: 
curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh | sh -s -- --key "$COMETAPI_KEY"
For Windows native PowerShell, run the interactive installer: 
powershell -c "irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1' | iex"
For non-interactive Windows setup, pass the API key explicitly: 
powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1'))) -Key $env:COMETAPI_KEY"
By default, the script does not replace ~/.codex/auth.json and does not remove a ChatGPT login. Use --force-auth-json or -ForceAuthJson only if you want the script to manage Codex API-key login through auth.json.

​
Choose or change a model ID

Use a model ID from the Models page. In manual configuration, change the model value in ~/.codex/config.toml. For macOS, Linux, or WSL, pass --model when you run the setup script: 
curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh | sh -s -- --key "$COMETAPI_KEY" --model your-model-id
For Windows native PowerShell, pass -Model when you run the setup script: 
powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1'))) -Key $env:COMETAPI_KEY -Model 'your-model-id'"
The script uses CODEX_HOME when it is set. Otherwise it writes to the current environment’s ~/.codex.

​
Verify the setup

To verify the setup with the Codex CLI, run this read-only command from any local project: 
codex exec --ephemeral --skip-git-repo-check --sandbox read-only --color never "Reply exactly with: COMETAPI_CODEX_OK"
If the Codex CLI is not available in PATH, open the Codex app and send a short prompt from a local project.

​
Troubleshooting

Confirm that model_provider = "cometapi" is in the user-level ~/.codex/config.toml file.
Update ~/.codex/cometapi_key, or rerun the setup script with the updated $COMETAPI_KEY value.
Use the manual Windows native PowerShell steps, then run the verification command.
Use --key "$COMETAPI_KEY", set COMETAPI_KEY, or run the interactive sh -c "$(curl ...)" command.
Confirm that base_url is https://api.cometapi.com/v1 in ~/.codex/config.toml.
Check the Models page for available model IDs.
Edit $HOME\.codex for Windows native mode, or edit ~/.codex inside WSL for WSL agent mode.
Do not use --force-auth-json or -ForceAuthJson unless you want API-key login mode.