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

# Codex CLI | AI Gateway

> Route Codex CLI model calls through Orq.ai AI Gateway for unified observability, cost tracking, and model governance.

Route every model call Codex CLI makes through the [**Orq.ai AI Gateway**](/docs/ai-gateway/get-started/quickstart) by editing `~/.codex/config.toml`. Requests appear in [Traces](/docs/ai-gateway/traces) automatically.

## Prerequisites

* [Codex CLI](https://github.com/openai/codex) installed
* Active **Orq.ai** account with **AI Gateway** access
* [Orq.ai API key](/docs/ai-gateway/configuration/api-keys)
* Model enabled in [**AI Gateway** → **Supported Models**](/docs/ai-gateway/supported-models)

## Setup

<Steps>
  <Step title="Export the API key">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export ORQ_API_KEY="<your-orq-api-key>"
    ```

    Replace `<your-orq-api-key>` with an [API key](/docs/ai-gateway/configuration/api-keys). This sets the variable for the current shell session. To persist it across sessions, add the line to `~/.zshrc` or `~/.bashrc`.
  </Step>

  <Step title="Create or edit ~/.codex/config.toml">
    Create `~/.codex/config.toml` if it does not exist. Add or merge the following keys. The top-level `model` and `model_provider` lines set the default; the `[model_providers.orq]` block registers the custom provider:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    model = "openai/gpt-5.4"
    model_provider = "orq"

    [model_providers.orq]
    name = "Orq AI Gateway"
    base_url = "https://api.orq.ai/v3/router"
    env_key = "ORQ_API_KEY"
    wire_api = "responses"
    requires_openai_auth = false
    ```

    Replace `openai/gpt-5.4` with the provider-prefixed model to use by default (e.g. `anthropic/claude-sonnet-4-6`). If a `model` key already exists in the file, replace it.

    <Warning>
      Do not name the provider `openai`. That identifier is reserved and hardcoded to `api.openai.com`. Setting `base_url` has no effect on it.
    </Warning>
  </Step>

  <Step title="Run Codex">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    codex
    ```

    Running `codex` without flags routes all calls through the **AI Gateway** using the model configured in `~/.codex/config.toml`.

    Pass `--model` to override the model for a single invocation:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    codex --model anthropic/claude-sonnet-4-6
    ```
  </Step>
</Steps>

## Configuration Reference

| Field                  | Value                          | Description                                                     |
| ---------------------- | ------------------------------ | --------------------------------------------------------------- |
| `model`                | `provider/model-id`            | Default model. Must use provider-prefixed format.               |
| `model_provider`       | `orq`                          | Selects the custom provider defined below.                      |
| `base_url`             | `https://api.orq.ai/v3/router` | AI Gateway router endpoint.                                     |
| `env_key`              | `ORQ_API_KEY`                  | Environment variable that holds the API key.                    |
| `wire_api`             | `responses`                    | Wire protocol. Codex uses the Responses API.                    |
| `requires_openai_auth` | `false`                        | Disables the OpenAI auth header. Required for Orq-routed calls. |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication error">
    Confirm `ORQ_API_KEY` is exported in the shell running Codex. Run `echo $ORQ_API_KEY` to verify the value is set.
  </Accordion>

  <Accordion title="Model not found">
    The model must be enabled in [**AI Gateway** → **Supported Models**](/docs/ai-gateway/supported-models) before Codex can route to it. Check that the model ID in `config.toml` uses the provider-prefixed format (e.g. `openai/gpt-5.4`, not `gpt-4o`).
  </Accordion>

  <Accordion title="No Traces appearing in Orq.ai">
    Confirm `base_url` is `https://api.orq.ai/v3/router` and `model_provider` is set to the custom provider name (e.g. `orq`), not `openai`.
  </Accordion>
</AccordionGroup>

## Verification

Send a prompt in Codex. The response appears in the terminal and the trace appears in [**Orq.ai** Traces](/docs/ai-gateway/traces) with the model identifier (e.g. `openai/gpt-5.4`).