---
title: Codex
---


[Codex](https://github.com/openai/codex) is OpenAI's command-line coding assistant. It can talk to any custom model provider through its `config.toml`, so pointing that provider at CrossModel gives you access to the whole catalog.

## Quickstart

### 1. Install Codex

macOS / Linux:

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

Windows:

```bash
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

Or install with npm:

```bash
npm install -g @openai/codex
```

### 2. Create an API key

Sign in to the [Console](/console/api-keys) and create a key that starts with `cm-` on the **API Keys** page. The key is shown only once, so copy it somewhere safe.

### 3. Add CrossModel as a provider

Edit `~/.codex/config.toml` and define the CrossModel provider:

```toml
model_provider = "crossmodel"
model = "openai/gpt-5.5"

[model_providers.crossmodel]
name = "CrossModel"
base_url = "https://api.crossmodel.ai/v1"
env_key = "CROSSMODEL_API_KEY"
```

### 4. Set the API key environment variable

`env_key` tells Codex which environment variable holds your key. Add it to your shell profile (`~/.zshrc` or `~/.bashrc`):

```bash
export CROSSMODEL_API_KEY="cm-YOUR_KEY"
```

Reopen the terminal, or run `source ~/.zshrc`, to load it.

### 5. Launch

Run Codex from your project directory:

```bash
cd /path/to/your/project
codex
```

## How it works

`model_provider` selects the default provider, and the `[model_providers.crossmodel]` block describes it: `base_url` points at CrossModel's OpenAI-compatible endpoint (`https://api.crossmodel.ai/v1`), and `env_key` tells Codex where to read the key. Requests go to CrossModel with your `cm-` key sent as a `Bearer` token.

## Choosing models

To switch models, just change the `model` field in `config.toml` — no reinstall needed. Model IDs follow the `vendor/short_name` format, e.g. `openai/gpt-5-mini` or `deepseek/deepseek-v4-pro`. See the full list in the [model catalog](/models).

<Callout type="info">
  You can also point `model` at a [model alias](/docs/model-aliases) you define on your API key — keep `config.toml` fixed on a stable name like `cross-model-pro` and switch the real model from the dashboard.
</Callout>

## Troubleshooting

| Symptom | What to check |
|---------|---------------|
| Auth failure | Confirm `CROSSMODEL_API_KEY` is set, active in the current shell, and holds a valid `cm-` key. |
| "Model not found" | Verify the `model` field matches an ID from the `/v1/models` response. |
| Requests bypass CrossModel | Make sure `model_provider` is set to `crossmodel` and `base_url` ends with `/v1`. |
| Insufficient balance | Top up in the [Console](/console/billing). |