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

# Codex

> Add the ngrok AI Gateway as a custom model provider in the OpenAI Codex CLI to track usage and route requests with one access key.

[Codex](https://github.com/openai/codex) is OpenAI's coding agent for the terminal.
It reaches the AI Gateway as a custom model provider over the OpenAI Responses API, so its requests show up in [observability](/docs/ai-gateway/observability) and follow your [access key configuration](/docs/ai-gateway/guides/access-key-configurations).

## What you'll need

* The [Codex CLI](https://github.com/openai/codex#quickstart) installed.
* An [access key](/docs/ai-gateway/concepts/access-keys) from [app.ngrok.ai](https://app.ngrok.ai).

## Add the gateway as a model provider

Export your access key in your shell profile, such as `~/.zshrc` or `~/.bashrc`, so Codex can read it:

```bash theme={null}
export NGROK_AI_GATEWAY_KEY="ng-xxxxx-g1-xxxxx"
```

Save Codex's built-in model catalog to a file:

```bash theme={null}
codex debug models > ~/.codex/ngrok-models.json
```

Codex looks up each model's context window, reasoning levels, and tools in a catalog.
The gateway's model list doesn't include those details, so without the file Codex warns that model metadata isn't found and falls back to generic defaults.
Run the command again after you update Codex to pick up new models.

Add the gateway as a provider in `~/.codex/config.toml`:

```toml theme={null}
model = "gpt-5.5"
model_provider = "ngrok"
model_catalog_json = "~/.codex/ngrok-models.json"

[model_providers.ngrok]
name = "ngrok AI Gateway"
base_url = "https://gateway.ngrok.ai/v1"
env_key = "NGROK_AI_GATEWAY_KEY"
wire_api = "responses"
```

This configuration:

* Defines a provider named `ngrok` that points at the gateway
* Reads your access key from `NGROK_AI_GATEWAY_KEY` and sends it as an `Authorization: Bearer` header
* Uses the Responses API, the only wire protocol current Codex versions support
* Makes `ngrok` the default provider, with `gpt-5.5` as the default model
* Loads model details from the catalog you saved

Keep the provider in your user-level `~/.codex/config.toml`.
Codex ignores `model_provider` and `model_providers` in a project's `.codex/config.toml`.
The provider ID can't be `openai`, `ollama`, or `lmstudio`, which Codex reserves for its built-in providers.

## Test the connection

Send a single prompt from the command line:

```bash theme={null}
codex exec "Explain what a hash map is in two sentences."
```

The header Codex prints before the response should list `provider: ngrok` and your model.
Confirm the request in AI Gateway [observability](/docs/ai-gateway/observability) in [app.ngrok.ai](https://app.ngrok.ai).

## Choose a model

<Warning>
  Codex only supports the `/v1/responses` API.
  Check the [model catalog](/docs/ai-gateway/reference/model-catalog) before you point Codex at a non-OpenAI model.
</Warning>

Pass `--model` (or `-m`) to start a session on a different model:

```bash theme={null}
codex --model gpt-5.4
```

Pick a model that's in both your saved catalog and the [ngrok.ai model catalog](/docs/ai-gateway/reference/model-catalog), and use its plain ID.
A `provider:model` name such as `openai:gpt-5.5` reaches the gateway, but Codex doesn't find it in the catalog and falls back to generic defaults.

## Keep OpenAI as your default

To keep Codex on your OpenAI login by default and use the gateway only when you ask for it, put the gateway settings in a profile instead of `config.toml`.
Create `~/.codex/ngrok.config.toml`:

```toml theme={null}
model_provider = "ngrok"
model = "gpt-5.5"
model_catalog_json = "~/.codex/ngrok-models.json"

[model_providers.ngrok]
name = "ngrok AI Gateway"
base_url = "https://gateway.ngrok.ai/v1"
env_key = "NGROK_AI_GATEWAY_KEY"
wire_api = "responses"
```

Start a gateway session with the profile:

```bash theme={null}
codex --profile ngrok
```

Codex loads `config.toml` first, then layers the profile on top, so sessions without `--profile ngrok` stay on OpenAI.

## Troubleshooting

| Symptom | Fix |
| - | - |
| `Reconnecting...` messages, then `401 Unauthorized` | Check that `NGROK_AI_GATEWAY_KEY` is exported in the shell that starts Codex, and that it holds a current access key |
| Requests still go to OpenAI | Move `model_provider` and `[model_providers.ngrok]` to `~/.codex/config.toml` or a profile, since a project config can't set them |
| `Model metadata for <model> not found` at startup | Save the model catalog and set `model_catalog_json`, then use a plain model ID that's in it |
| Long responses stop partway through | Set `totalTimeout` to `15m` in [account settings](/docs/ai-gateway/guides/account-settings#streaming-responses). A saved total timeout caps the whole stream, and saving any account setting stores the `2m` default |

For gateway-side errors, see [Debug failed requests](/docs/ai-gateway/guides/debugging).

## Next steps

* [Restrict providers and models](/docs/ai-gateway/guides/restrict-providers-and-models): Scope what an access key can call
* [Configure fallback models](/docs/ai-gateway/guides/configure-fallback-models): Try another model when the first one fails
* [Observability](/docs/ai-gateway/observability): See which model served each request


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.