# Codex CLI

<Callout type="info" title="Note">
  AI Gateway is part of [AI Governance](/beta-docs/ai-coder/ai-governance/), which is
  included with a Premium license.
</Callout>

Codex CLI can be configured to use AI Gateway by setting up a custom model provider.

## Centralized API Key [#centralized-api-key]

To configure Codex CLI to use AI Gateway, set the following configuration options in your Codex configuration file (e.g., `~/.codex/config.toml`):

```toml
model_provider = "ai_gateway"

[model_providers.ai_gateway]
name = "AI Gateway"
base_url = "<your-deployment-url>/api/v2/ai-gateway/openai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

To authenticate with AI Gateway, get your &#x2A;*[Coder API token](/beta-docs/admin/users/sessions-tokens/#generate-a-long-lived-api-token-on-behalf-of-yourself)** and set it in your environment:

```sh
export OPENAI_API_KEY="<your-coder-api-token>"
```

Run Codex as usual. It will automatically use the `ai_gateway` model provider from your configuration.

## BYOK (Personal API Key) [#byok-personal-api-key]

Add the following to your Codex configuration file (e.g., `~/.codex/config.toml`):

```toml
model_provider = "ai_gateway"

[model_providers.ai_gateway]
name = "AI Gateway"
base_url = "<your-deployment-url>/api/v2/ai-gateway/openai/v1"
wire_api = "responses"
requires_openai_auth = true
env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_API_TOKEN" }
```

Set both environment variables:

```sh
# Your personal OpenAI API key, forwarded to OpenAI.
export OPENAI_API_KEY="<your-openai-api-key>"

# Your Coder API token, used for authentication with AI Gateway.
export CODER_API_TOKEN="<your-coder-api-token>"
```

## BYOK (ChatGPT Subscription) [#byok-chatgpt-subscription]

<Callout type="idea" title="Important">
  This flow requires a [ChatGPT provider](/beta-docs/ai-coder/ai-gateway/providers/#chatgpt) on
  the deployment. Without it, Codex requests fail with
  `404 route not supported: POST /chatgpt/v1/responses`.
</Callout>

Add the following to your Codex configuration file (e.g., `~/.codex/config.toml`):

```toml
model_provider = "ai_gateway"

[model_providers.ai_gateway]
name = "AI Gateway"
base_url = "<your-deployment-url>/api/v2/ai-gateway/chatgpt/v1"
wire_api = "responses"
requires_openai_auth = true
env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_API_TOKEN" }
```

<Callout type="info" title="Note">
  The `base_url` uses `/ai-gateway/chatgpt/v1` instead of `/ai-gateway/openai/v1` to route requests through the ChatGPT provider.
</Callout>

Set your Coder API token and ensure `OPENAI_API_KEY` is not set:

```sh
# Your Coder API token, used for authentication with AI Gateway.
export CODER_API_TOKEN="<your-coder-api-token>"

# Ensure no OpenAI API key is set so Codex uses ChatGPT login instead.
unset OPENAI_API_KEY
```

When you run Codex, it will prompt you to log in with your ChatGPT account.

## Pre-configuring in Templates [#pre-configuring-in-templates]

If configuring within a Coder workspace, you can use the
[Codex CLI](https://registry.coder.com/modules/coder-labs/codex) module.

For the centralized API key flow, set `enable_ai_gateway`:

```tf
module "codex" {
  source            = "registry.coder.com/coder-labs/codex/coder"
  version           = "~> 5.3"
  agent_id          = coder_agent.main.id
  workdir           = "/path/to/project" # Set to your project directory
  enable_ai_gateway = true
}
```

For the ChatGPT subscription flow, pass the provider configuration
through `base_config_toml` and inject the Coder API token with a
`coder_env` resource. Users authenticate by running `codex login` with
their ChatGPT account:

```tf
resource "coder_env" "coder_api_token" {
  agent_id = coder_agent.main.id
  name     = "CODER_API_TOKEN"
  value    = data.coder_workspace_owner.me.session_token
}

module "codex" {
  source   = "registry.coder.com/coder-labs/codex/coder"
  version  = "~> 5.3"
  agent_id = coder_agent.main.id
  workdir  = "/path/to/project" # Set to your project directory

  base_config_toml = <<-TOML
    model_provider = "ai_gateway"

    [model_providers.ai_gateway]
    name = "AI Gateway"
    base_url = "${data.coder_workspace.me.access_url}/api/v2/ai-gateway/chatgpt/v1"
    wire_api = "responses"
    requires_openai_auth = true
    env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_API_TOKEN" }
  TOML
}
```

Do not set `OPENAI_API_KEY` in the workspace when using the ChatGPT
subscription flow, or Codex authenticates with the API key instead of
the ChatGPT login.

## Troubleshooting [#troubleshooting]

### Codex falls back from WebSockets to HTTPS transport [#codex-falls-back-from-websockets-to-https-transport]

Recent Codex CLI versions default to the WebSocket runtime for the
Responses API. AI Gateway does not support WebSocket transport, so each
request attempts a WebSocket connection and retries up to 5 times before
falling back to HTTPS. When this happens you will see:

```txt
Falling back from WebSockets to HTTPS transport.
```

The requests still succeed over HTTPS, but every turn waits through the
five failed WebSocket attempts first.

To stop Codex from attempting WebSockets, set `supports_websockets = false`
in your AI Gateway provider block in `~/.codex/config.toml`:

```toml
model_provider = "ai_gateway"

[model_providers.ai_gateway]
name = "AI Gateway"
base_url = "<your-deployment-url>/api/v2/ai-gateway/openai/v1"
wire_api = "responses"
supports_websockets = false
```

This forces the HTTPS transport directly and removes the fallback delay.

**References:** [Codex CLI Configuration](https://developers.openai.com/codex/config-reference)