> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Codex with CometAPI

> Use this guide to configure Codex with CometAPI by editing the user-level config.toml provider settings.

Use this guide to run [Codex](https://developers.openai.com/codex/quickstart) with CometAPI as a model provider.

Official references:

* [Codex quickstart](https://developers.openai.com/codex/quickstart)
* [Codex config basics](https://developers.openai.com/codex/config-basic)
* [Codex custom model providers](https://developers.openai.com/codex/config-advanced#custom-model-providers)
* [Codex Authentication](https://developers.openai.com/codex/auth)
* [Codex on Windows](https://developers.openai.com/codex/windows)

## 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](https://developers.openai.com/codex/quickstart) |
| CometAPI API key | Get one from the [CometAPI dashboard](https://www.cometapi.com/console/token)                                  |
| Model ID         | Use a model ID from the [Models page](/overview/models)                                                        |

## Choose a setup path

We provide two options to help you configure Codex quickly.

<CardGroup cols={2}>
  <Card title="Option 1: Configure Codex manually (recommended)" icon="bolt" href="#configure-codex-manually">
    Edit the user-level `~/.codex/config.toml` file directly. This is the most reliable path, especially for Windows and WSL users.
  </Card>

  <Card title="Option 2: Configure via script" icon="puzzle-piece" href="#run-the-setup-script">
    Run the setup script as a shortcut. It writes the same provider configuration and stores the CometAPI API key for Codex.
  </Card>
</CardGroup>

## 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`.

<Tabs>
  <Tab title="macOS / Linux / WSL">
    Store your CometAPI API key in a local key file:

    ```bash theme={null}
    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`:

    ```toml theme={null}
    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\""]
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    Store your CometAPI API key in the Windows Codex home directory:

    ```powershell theme={null}
    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`:

    ```toml theme={null}
    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()",
    ]
    ```
  </Tab>
</Tabs>

<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.
</Note>

## 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:

```toml theme={null}
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.
</Warning>

## 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:

```bash theme={null}
sh -c "$(curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh)"
```

For non-interactive setup, pass the API key explicitly:

```bash theme={null}
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 theme={null}
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 theme={null}
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`.
</Warning>

## Choose or change a model ID

Use a model ID from the [Models page](/overview/models). In manual configuration, change the `model` value in `~/.codex/config.toml`.

For macOS, Linux, or WSL, pass `--model` when you run the setup script:

```bash theme={null}
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 theme={null}
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`.
</Note>

## Verify the setup

To verify the setup with the Codex CLI, run this read-only command from any local project:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Codex still uses the default OpenAI provider">
    Confirm that `model_provider = "cometapi"` is in the user-level `~/.codex/config.toml` file.
  </Accordion>

  <Accordion title="The API key changed">
    Update `~/.codex/cometapi_key`, or rerun the setup script with the updated `$COMETAPI_KEY` value.
  </Accordion>

  <Accordion title="The PowerShell script fails during pre-flight checks">
    Use the manual Windows native PowerShell steps, then run the verification command.
  </Accordion>

  <Accordion title="The piped shell setup asks for no API key">
    Use `--key "$COMETAPI_KEY"`, set `COMETAPI_KEY`, or run the interactive `sh -c "$(curl ...)"` command.
  </Accordion>

  <Accordion title="The connection times out or uses the wrong base URL">
    Confirm that `base_url` is `https://api.cometapi.com/v1` in `~/.codex/config.toml`.
  </Accordion>

  <Accordion title="The model is not found">
    Check the [Models page](/overview/models) for available model IDs.
  </Accordion>

  <Accordion title="Windows setup affects the wrong environment">
    Edit `$HOME\.codex` for Windows native mode, or edit `~/.codex` inside WSL for WSL agent mode.
  </Accordion>

  <Accordion title="The ChatGPT login changed">
    Do not use `--force-auth-json` or `-ForceAuthJson` unless you want API-key login mode.
  </Accordion>
</AccordionGroup>