Skip to main content
To connect Codex with CometAPI, install Codex and get an API key from the CometAPI dashboard.

Quick start: edit two files

Edit config.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 ~/.codex/config.toml, add or update these connection settings:
Replace 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 ~/.codex/auth.json exists, back up the file before replacing its contents:
Replace <COMETAPI_KEY> with your CometAPI API key. Keep the field name OPENAI_API_KEY unchanged.
Save both files, restart Codex, and send a short message to begin.
  • macOS: In Finder, press Command + Shift + G and enter ~/.codex.
  • Linux: Open .codex in your user home directory. The ~ in ~/.codex refers to your home directory.
  • Windows native: In File Explorer, enter %USERPROFILE%\.codex, usually C:\Users\<user>\.codex.
  • WSL: Use ~/.codex inside the Linux distribution where Codex runs.
If you set 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. 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.
Replace <COMETAPI_KEY> with your CometAPI API key and store the API key in a local file:
Add or update this configuration in ~/.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, use env_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:
Remove requires_openai_auth and [model_providers.cometapi.auth] when using env_key.

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:
For non-interactive setup, replace <COMETAPI_KEY> and pass the API key explicitly:
For Windows native PowerShell, run the interactive installer:
For non-interactive Windows setup, replace <COMETAPI_KEY> and pass the API key explicitly:
By default, the script leaves ~/.codex/auth.json unchanged. Use --force-auth-json or -ForceAuthJson to select the quick start’s API-key sign-in method. This option writes auth.json and sets requires_openai_auth = true instead of command authentication.

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, replace <COMETAPI_KEY> and your-model-id when running the setup script:
For Windows native PowerShell, replace <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:
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.
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.
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.
Use the manual Windows native PowerShell steps, then run the verification command.
Pass --key "<COMETAPI_KEY>" with your CometAPI API key, or run the interactive installer from Run the setup script.
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.
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.

Official references

Last modified on October 8, 2026