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

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

​
Resources