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

# Codex Desktop App

> Use the Codex desktop app (ChatGPT for macOS and Windows) with OpenRouter

## What is the Codex Desktop App?

Codex ships inside the [ChatGPT desktop app](https://developers.openai.com/codex/app) for macOS and Windows. The app, the [Codex CLI](/docs/cookbook/coding-agents/codex-cli), and the IDE extension all read the same local configuration in `~/.codex/config.toml`, so pointing the desktop app at OpenRouter is a matter of adding an OpenRouter model provider and making your API key visible to the app.

The one difference from the CLI is how the key reaches the process. A terminal inherits your shell profile, but a desktop app launched from the Dock or Start menu does not, so an `export` in `~/.zshrc` is not enough on its own.

## Quick Start

### Step 1: Install the Desktop App

Download the ChatGPT desktop app for [macOS or Windows](https://chatgpt.com/download/) and sign in.

### Step 2: Get Your OpenRouter API Key

1. Sign up or log in at [OpenRouter](https://openrouter.ai)
2. Navigate to your [API Keys page](https://openrouter.ai/keys)
3. Create a new API key
4. Copy your key (starts with `sk-or-...`)

### Step 3: Configure Codex for OpenRouter

Create or edit `~/.codex/config.toml` (`%USERPROFILE%\.codex\config.toml` on Windows):

```toml lines theme={null}
model_provider = "openrouter"
model_reasoning_effort = "medium"
model = "openai/gpt-6-astra"

[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"
supports_websockets = false
```

`model` accepts any OpenRouter model ID, including tilde aliases such as `~openai/gpt-sol-latest`. Browse the catalog at [openrouter.ai/models](https://openrouter.ai/models).

<Note>
  `model_provider` and `model_providers` are only honored in the user-level `~/.codex/config.toml`. Codex ignores them in a project-scoped `.codex/config.toml`.
</Note>

### Step 4: Make Your API Key Visible to the App

Codex reads the key from the `OPENROUTER_API_KEY` environment variable named by `env_key`. An `export` in `~/.zshrc` or `~/.bashrc` only reaches terminal processes, so set the variable at the session level instead, then fully quit and reopen the app.

<Tabs>
  <Tab title="macOS">
    Set the variable in the user launchd session so GUI apps inherit it:

    ```bash lines theme={null}
    launchctl setenv OPENROUTER_API_KEY "sk-or-..."
    ```

    This does not survive a reboot or logout. To make it permanent, add the same command to a login item or a launchd agent that runs at login.
  </Tab>

  <Tab title="Windows">
    Set a user-level environment variable. Processes started after this inherit it, so restart the app afterwards:

    ```powershell lines theme={null}
    setx OPENROUTER_API_KEY "sk-or-..."
    ```
  </Tab>
</Tabs>

### Step 5: Restart and Start a Task

Quit the app completely (not just the window), reopen it, choose **Codex**, and start a new chat. Requests now go through OpenRouter and appear in your [Activity Dashboard](https://openrouter.ai/activity).

<Warning>
  The ChatGPT and Codex apps can leave background processes running after you quit. These processes keep the old environment, so the app keeps using the previous configuration and API key even after you reopen it. If your changes don't take effect, see [Background processes keep the old configuration](#background-processes-keep-the-old-configuration).
</Warning>

## Configuration Reference

| Setting | Description | Example |
| - | - | - |
| `model_provider` | Provider to use for model requests | `"openrouter"` |
| `model` | OpenRouter model ID | `"openai/gpt-6-astra"` |
| `model_reasoning_effort` | Reasoning effort level | `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
| `model_providers.openrouter.base_url` | OpenRouter API endpoint | `"https://openrouter.ai/api/v1"` |
| `model_providers.openrouter.env_key` | Environment variable holding your API key | `"OPENROUTER_API_KEY"` |
| `model_providers.openrouter.wire_api` | Protocol Codex speaks to the provider. `responses` is the only supported value | `"responses"` |
| `model_providers.openrouter.supports_websockets` | Whether the provider supports the Responses API WebSocket transport. Leave `false` for OpenRouter | `false` |

<Note>
  With `env_key` authentication Codex does not fetch the OpenRouter model catalog, so non-OpenAI models may show an "Unknown model" fallback-metadata warning. The command-based `auth` block on the [Codex CLI page](/docs/cookbook/coding-agents/codex-cli#step-3-configure-codex-for-openrouter) triggers the catalog refresh and works in the desktop app as long as `OPENROUTER_API_KEY` is visible to it as described above.
</Note>

## Why Use OpenRouter with the Codex Desktop App?

* **Provider failover:** If one provider is unavailable or rate-limited, OpenRouter fails over to another, keeping long-running desktop tasks moving.
* **Organizational controls:** Set spending limits and allocate credits across a team of desktop users from one place.
* **Usage visibility:** Track cost, tokens, and request patterns in the [OpenRouter Activity Dashboard](https://openrouter.ai/activity).
* **Model flexibility:** Switch models by editing `model` in `config.toml`, including non-OpenAI models such as `~anthropic/claude-sonnet-latest`.

## Troubleshooting

* **Auth errors or "Missing Authentication header":** The app could not read `OPENROUTER_API_KEY`. Set it with `launchctl setenv` on macOS or `setx` on Windows, then quit and reopen the app. An `export` in your shell profile alone is not visible to the desktop app.
* **Changes to `config.toml` not taking effect:** Make sure you edited the user-level `~/.codex/config.toml`, not a project-scoped `.codex/config.toml`, and restart the app. If the changes still don't apply, see [Background processes keep the old configuration](#background-processes-keep-the-old-configuration).
* **Model not found:** Verify the model ID on [openrouter.ai/models](https://openrouter.ai/models) and use the exact slug.
* **Privacy:** OpenRouter does not log your source code prompts unless you opt in to prompt logging. See our [Privacy Policy](https://openrouter.ai/privacy) for details.

### Background processes keep the old configuration

The ChatGPT and Codex apps can leave background processes running after you quit the app. When you reopen the app, it reuses those processes, which still hold the environment and configuration from before your changes. As a result, a new `OPENROUTER_API_KEY` or `config.toml` edit can appear to be ignored, and you might keep seeing auth errors.

To force the app to read the new configuration and API key:

1. Quit the ChatGPT app.
2. End any leftover processes:

   * **macOS:** Open **Activity Monitor**, search for `gpt` and then `codex`, select each matching process, and click **Stop** (the **X** button), then **Quit**.
   * **Windows:** Open **Task Manager**, go to the **Processes** or **Details** tab, find each process with `gpt` or `codex` in its name, and click **End task**.

   Only end processes that belong to the ChatGPT or Codex app. Other apps and tools can also have `gpt` or `codex` in their process names, so check the process's parent app or publisher (OpenAI) before you end it.
3. Reopen the app.

Alternatively, log out of your computer and log back in, which ends all of these processes. On macOS, a logout also clears the `launchctl setenv` variable, so run `launchctl setenv OPENROUTER_API_KEY "sk-or-..."` again before you open the app. On Windows, the `setx` variable persists across sign-outs, so you don't need to set it again.

## Resources

* [ChatGPT desktop app](https://developers.openai.com/codex/app)
* [Codex configuration reference](https://developers.openai.com/codex/config-reference)
* [Codex custom model providers](https://developers.openai.com/codex/config-advanced#custom-model-providers)
* [Codex CLI with OpenRouter](/docs/cookbook/coding-agents/codex-cli)
* [OpenRouter Activity Dashboard](https://openrouter.ai/activity)