---
title: Codex in ChatGPT and Codex CLI
description: Connect the Codex workspace in ChatGPT desktop and Codex CLI to CrossModel with one shared configuration.
---


[Codex](https://learn.chatgpt.com/docs/app) is OpenAI's coding agent. You can use it inside the ChatGPT desktop app or from the terminal with [Codex CLI](https://learn.chatgpt.com/docs/codex/cli). Both local clients use the same user-level `~/.codex/config.toml`, so you only need to configure CrossModel once.

CrossModel supports the Responses API used by Codex directly. You do not need to install or run a separate router or proxy.

<Callout type="info">
  This configuration changes the model provider for local Codex work in the ChatGPT desktop app and Codex CLI. It does not change regular ChatGPT chats, Work, the ChatGPT web app, or Codex cloud.
</Callout>

## Quickstart

### 1. Choose a client

For the desktop experience, [install the ChatGPT desktop app](https://learn.chatgpt.com/docs/app), sign in, and choose **Codex**.

If you also want the terminal client, install Codex CLI.

macOS / Linux:

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

Windows:

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

Or install it with npm:

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

Already using either client? Skip the installation and continue with the same configuration below.

### 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 the shared provider

Edit `~/.codex/config.toml` and add the following configuration. Create the file if it does not exist.

```toml
model_provider = "crossmodel"
model = "deepseek/deepseek-v4-pro"

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

This is a user-level setting shared by the ChatGPT desktop app's Codex workspace and Codex CLI. The provider block follows OpenAI's [custom model provider configuration](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers): `base_url` points Codex at CrossModel, `env_key` names the environment variable that contains your key, and `wire_api` selects the Responses API.

### 4. Set the API key environment variable

On macOS or Linux, add the variable to your shell profile (`~/.zshrc` or `~/.bashrc`):

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

Open a new terminal, or reload the profile you edited:

```bash
source ~/.zshrc
```

On Windows PowerShell, set it for the current session:

```powershell
$env:CROSSMODEL_API_KEY = "cm-YOUR_KEY"
```

To save it as a user environment variable for future PowerShell sessions and the desktop app:

```powershell
[Environment]::SetEnvironmentVariable("CROSSMODEL_API_KEY", "cm-YOUR_KEY", "User")
```

<Callout type="warning">
  The ChatGPT desktop app must be able to read `CROSSMODEL_API_KEY`, not just your terminal. After setting or changing the variable, fully quit ChatGPT and reopen it. If Codex CLI works but the desktop app reports an authentication error, the app process has not inherited the variable; set it in your operating system's user environment, then sign out and back in if needed.
</Callout>

### 5. Start Codex

In the ChatGPT desktop app, choose **Codex**, open your project, and start a new task. After changing `config.toml`, fully quit and reopen ChatGPT before testing.

For Codex CLI, run it from your project directory:

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

## How it works

Codex sends Responses API requests directly to `https://api.crossmodel.ai/v1`. CrossModel authenticates the `cm-` key, routes each request to the selected upstream model, converts protocols when necessary, and bills usage to your CrossModel wallet. There is no local routing service to install or keep running.

## Choosing models

Change the default model by editing the `model` field in `~/.codex/config.toml`. This guide deliberately uses `deepseek/deepseek-v4-pro` to show that Codex can run with a non-OpenAI model through CrossModel. Model IDs use the `vendor/short_name` format; browse the current IDs and capabilities in the [model catalog](/models).

For a one-off CLI session, override the configured model with `-m`:

```bash
codex -m openai/gpt-5.6-terra
```

Choose a model with tool-calling support for the full agent experience. The built-in model picker may not discover every model in the CrossModel catalog automatically; setting `model` explicitly still works.

<Callout type="info">
  You can also point `model` at a [model alias](/docs/model-aliases) defined on your API key. Keep `config.toml` fixed on a stable name such as `cross-model-pro`, then switch the real model from the dashboard without editing either client.
</Callout>

## Troubleshooting

| Symptom | What to check |
|---------|---------------|
| Auth failure in both clients | Confirm `CROSSMODEL_API_KEY` contains an active `cm-` key and is available in the current environment. |
| CLI works but the desktop app fails auth | Fully quit and reopen ChatGPT. If it still fails, expose `CROSSMODEL_API_KEY` to GUI applications through your operating system's user environment. |
| "Model not found" | Verify that `model` exactly matches an ID in the [model catalog](/models) or the `/v1/models` response. |
| Requests bypass CrossModel | Confirm `model_provider = "crossmodel"`, the provider block is named `[model_providers.crossmodel]`, and `base_url` ends with `/v1`. |
| The old model is still active | Start a new task after editing `config.toml`; for the desktop app, fully quit and reopen ChatGPT. |
| The model replies but cannot edit files or run tools | Choose a model whose catalog entry includes tool-calling support. |
| Insufficient balance | Top up in the [Console](/console/billing). |

## Official references

- [ChatGPT desktop app](https://learn.chatgpt.com/docs/app)
- [Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
- [Custom model providers](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers)
- [Codex environment variables](https://learn.chatgpt.com/docs/config-file/environment-variables)