Quick start: edit two files
Editconfig.toml for the connection and auth.json for the API key. Use the .codex folder in your user home directory; create the folder or files if missing.
1
Configure config.toml
In Replace
~/.codex/config.toml, add or update these connection settings:your-model-id with a model ID from the Models page. Keep model_provider and model above all [section] headers.Preserve other settings, and update matching entries instead of adding duplicates. Keep requires_openai_auth = true for this method. If switching methods, remove env_key and [model_providers.cometapi.auth].2
Configure auth.json
This method switches Codex to API-key sign-in. If Replace
~/.codex/auth.json exists, back up the file before replacing its contents:<COMETAPI_KEY> with your CometAPI API key. Keep the field name OPENAI_API_KEY unchanged.Find your Codex configuration directory
Find your Codex configuration directory
- macOS: In Finder, press Command + Shift + G and enter
~/.codex. - Linux: Open
.codexin your user home directory. The~in~/.codexrefers to your home directory. - Windows native: In File Explorer, enter
%USERPROFILE%\.codex, usuallyC:\Users\<user>\.codex. - WSL: Use
~/.codexinside the Linux distribution where Codex runs.
CODEX_HOME, use that directory for both files. Configure the user-level files rather than a project’s .codex/config.toml.Compare configuration methods
To keep your ChatGPT sign-in, use the recommended configuration below.
Recommended configuration
This is the recommended configuration. It stores your CometAPI API key in a separate file and reads the API key with a command. It leaves~/.codex/auth.json unchanged.
For this method, remove
requires_openai_auth and env_key from [model_providers.cometapi]. Do not combine these fields with [model_providers.cometapi.auth].If you previously used the quick start and want to restore ChatGPT sign-in, restore your auth.json backup or sign in with ChatGPT again.- macOS / Linux / WSL
- Windows PowerShell
Replace Add or update this configuration in
<COMETAPI_KEY> with your CometAPI API key and store the API key in a local file:~/.codex/config.toml. Replace your-model-id with the model ID:Use environment variable authentication
If you prefer to keep the CometAPI API key in an environment variable, useenv_key instead of the [model_providers.cometapi.auth] block.
Set COMETAPI_KEY to your CometAPI API key in the environment that launches Codex. Use this configuration and replace your-model-id with the model ID:
Run the setup script
The optional setup script applies the recommended command authentication. It updates~/.codex/config.toml, stores your CometAPI API key in ~/.codex/cometapi_key, and creates backups before file changes. It also verifies the configuration with codex exec when the Codex CLI is available.
For macOS, Linux, or WSL, run the interactive installer:
<COMETAPI_KEY> and pass the API key explicitly:
<COMETAPI_KEY> and pass the API key explicitly:
Choose or change a model ID
Use a model ID from the Models page. In manual configuration, change themodel value in ~/.codex/config.toml.
For macOS, Linux, or WSL, replace <COMETAPI_KEY> and your-model-id when running the setup script:
<COMETAPI_KEY> and your-model-id when running the setup script:
The script uses
CODEX_HOME when it is set. Otherwise it writes to the current environment’s ~/.codex.Verify the setup
Save your configuration and restart Codex before checking the connection. To verify the setup with the Codex CLI, run this read-only command from any local project:PATH, open the Codex app and send a short prompt from a local project.
Troubleshooting
Codex still uses the default OpenAI provider
Codex still uses the default OpenAI provider
Confirm that
model_provider = "cometapi" is in the user-level ~/.codex/config.toml file.The API key changed
The API key changed
For the quick start, update
OPENAI_API_KEY in ~/.codex/auth.json. For the recommended configuration, update ~/.codex/cometapi_key. For environment authentication, update COMETAPI_KEY in the environment that launches Codex. Restart Codex after changing the API key.Authentication settings conflict
Authentication settings conflict
Choose one authentication method. The quick start uses
requires_openai_auth = true and auth.json. Command authentication uses [model_providers.cometapi.auth] without requires_openai_auth or env_key. Environment authentication uses env_key without the other two settings.The PowerShell script fails during pre-flight checks
The PowerShell script fails during pre-flight checks
Use the manual Windows native PowerShell steps, then run the verification command.
The piped shell setup asks for no API key
The piped shell setup asks for no API key
Pass
--key "<COMETAPI_KEY>" with your CometAPI API key, or run the interactive installer from Run the setup script.The connection times out or uses the wrong base URL
The connection times out or uses the wrong base URL
Confirm that
base_url is https://api.cometapi.com/v1 in ~/.codex/config.toml.The model is not found
The model is not found
Check the Models page for available model IDs.
Windows setup affects the wrong environment
Windows setup affects the wrong environment
Edit
$HOME\.codex for Windows native mode, or edit ~/.codex inside WSL for WSL agent mode.The ChatGPT login changed
The ChatGPT login changed
The quick start and the script’s
--force-auth-json or -ForceAuthJson option select API-key sign-in. To use ChatGPT sign-in again, restore your auth.json backup or sign in with ChatGPT, then use the recommended configuration.