Skip to content

codex.md

Latest commit

 

History

History
199 lines (139 loc) · 7.67 KB

codex.md

File metadata and controls

199 lines (139 loc) · 7.67 KB
Raw

Use Codex with CometAPI

Canonical docs: https://apidoc.cometapi.com/integrations/codex

Use this guide to configure Codex with CometAPI by editing the user-level config.toml provider settings. Use this guide to run Codex with CometAPI as a model provider.

Official references:

Prerequisites

Requirement Details
OS macOS, Linux, Windows native PowerShell, or Windows with WSL
Git 2.23+ recommended
Codex Install the Codex app or Codex CLI from the Codex quickstart
CometAPI API key Get one from the CometAPI dashboard
Model ID Use 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.

macOS / Linux / WSL

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 PowerShell

Store your CometAPI API key in the Windows Codex home directory:

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
Set-Content -NoNewline -Path "$HOME\.codex\cometapi_key" -Value $env:COMETAPI_KEY

Add this configuration to $HOME\.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 = "powershell.exe"
args = [
  "-NoProfile",
  "-Command",
  "$p=Join-Path $HOME '.codex/cometapi_key'; (Get-Content -Raw $p).Trim()",
]

Note 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"

Warning 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"

Warning 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'"

Note 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

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

Update ~/.codex/cometapi_key, or rerun the setup script with the updated $COMETAPI_KEY value.

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

Use --key "$COMETAPI_KEY", set COMETAPI_KEY, or run the interactive sh -c "$(curl ...)" command.

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

Check the Models page for available model IDs.

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

Do not use --force-auth-json or -ForceAuthJson unless you want API-key login mode.