Skip to main content

​
What is the Codex Desktop App?

Codex ships inside the ChatGPT desktop app for macOS and Windows. The app, the 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 and sign in.

​
Step 2: Get Your OpenRouter API Key

  1. Sign up or log in at OpenRouter
  2. Navigate to your API Keys page
  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):
model accepts any OpenRouter model ID, including tilde aliases such as ~openai/gpt-sol-latest. Browse the catalog at openrouter.ai/models.
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.

​
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.
Set the variable in the user launchd session so GUI apps inherit it:
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.

​
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.
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.

​
Configuration Reference

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 triggers the catalog refresh and works in the desktop app as long as OPENROUTER_API_KEY is visible to it as described above.

​
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.
  • 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.
  • Model not found: Verify the model ID on 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 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