Codex CLI

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:

1
model_provider = "openrouter"
2
model_reasoning_effort = "high"
3
model="~openai/gpt-latest"
4
5
[model_providers.openrouter]
6
name = "openrouter"
7
8
base_url="https://openrouter.ai/api/v1"
9
env_key="OPENROUTER_API_KEY"

Step 4: Set Your API Key

Export your OpenRouter API key in your shell profile:

$
# Add to ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
$
export OPENROUTER_API_KEY="sk-or-..."

Step 5: Start Codex

Navigate to your project directory and run:

$
cd /path/to/your/project
$
codex

Your requests will now be routed through OpenRouter.

Configuration Reference

Core Settings

OpenRouter Provider Block

1
[model_providers.openrouter]
2
name = "openrouter"
3
base_url = "https://openrouter.ai/api/v1"
4
env_key = "OPENROUTER_API_KEY"

• base_url: OpenRouter API endpoint. Use https://openrouter.ai/api/v1 for production.
• env_key: Environment variable name for your API key.

Project Trust Levels

Codex supports per-project trust levels. Add project paths to control what the agent can access:

1
[projects."/path/to/trusted/project"]
2
trust_level = "trusted"
3
4
[projects."/path/to/untrusted/project"]
5
trust_level = "untrusted"

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

• Codex CLI on GitHub
• OpenRouter Codex Models
• OpenRouter Activity Dashboard
• OpenRouter API Documentation