Skip to main content

​
What is Codex CLI?

Codex CLI is OpenAI’s open-source local coding agent that runs in your terminal. It supports multiple model providers, including OpenRouter, so you can use OpenRouter’s unified API, provider failover, and organizational controls with Codex’s agentic coding workflows.

​
Quick Start

​
Step 1: Install Codex CLI

Follow the Codex CLI installation instructions to install the CLI on your system.

​
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

Codex uses a config.toml file, typically located at ~/.codex/config.toml. Create or edit this file with the following configuration:
On Windows, use PowerShell instead:
A plain env_key = "OPENROUTER_API_KEY" also works for authentication, but Codex won’t fetch the OpenRouter model catalog in that mode — non-OpenAI models will show the “Unknown model” fallback-metadata warning. Prefer the command-based auth block above.

​
Step 4: Set Your API Key

Export your OpenRouter API key in your shell profile:
On Windows, set it as a user-level environment variable and restart Codex (including the desktop app, which won’t see variables set only in a terminal session):
The auth command above reads your key from $OPENROUTER_API_KEY, so ensure this environment variable is set before starting Codex.

​
Step 5: Start Codex

Navigate to your project directory and run:
Your requests will now be routed through OpenRouter.

​
Configuration Reference

​
Core Settings

​
OpenRouter Provider Block

  • base_url: OpenRouter API endpoint. Use https://openrouter.ai/api/v1 for production.
  • auth.command / auth.args: Command Codex runs to obtain your API key — here it echoes $OPENROUTER_API_KEY. Command-based auth is what triggers Codex’s model-catalog refresh, so non-OpenAI models get correct metadata instead of the fallback-metadata warning. On Windows use command = "powershell" with args = ["-NoProfile", "-Command", "Write-Output $env:OPENROUTER_API_KEY"], since sh does not exist there.
A plain env_key = "OPENROUTER_API_KEY" also works for authentication, but Codex won’t fetch the OpenRouter model catalog in that mode — non-OpenAI models will show the “Unknown model” fallback-metadata warning. Prefer the command-based auth block above.

​
Project Trust Levels

Codex supports per-project trust levels. Add project paths to control what the agent can access:
  • trusted: Agent has full access (e.g., run commands, edit files).
  • untrusted: Agent has restricted access for safety.

​
Why Use OpenRouter with Codex CLI?

​
Provider Failover

OpenRouter routes requests across multiple providers. If one provider is unavailable or rate-limited, OpenRouter can fail over to another, keeping your coding sessions uninterrupted.

​
Organizational Controls

For teams, OpenRouter provides centralized budget management. Set spending limits, allocate credits, and prevent unexpected cost overruns across developers using Codex.

​
Usage Visibility

Track Codex usage in real-time via the OpenRouter Activity Dashboard. Monitor costs, token usage, and request patterns.

​
Model Flexibility

Point model at any OpenRouter slug (e.g. ~openai/gpt-latest, ~anthropic/claude-sonnet-latest) or a pinned version to switch models without changing your Codex installation—just update config.toml.

​
Troubleshooting

  • Auth Errors: Ensure OPENROUTER_API_KEY is set and valid. Check at openrouter.ai/keys. A 401 with “Missing Authentication header” usually means the auth command failed to run — on Windows, make sure you use the PowerShell variant above and that the environment variable is set user-wide (setx), then fully restart Codex.
  • Model Not Found: Verify the model ID on openrouter.ai/models. Use the exact format (e.g., ~openai/gpt-latest).
  • Privacy: OpenRouter does not log your source code prompts unless you opt-in to prompt logging. See our Privacy Policy for details.

​
Resources