> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://openrouter.ai/docs/llms.txt.
> For full documentation content, see https://openrouter.ai/docs/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://openrouter.ai/docs/_mcp/server.

# Codex CLI

## What is Codex CLI?

[Codex CLI](https://github.com/openai/codex) 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](https://github.com/openai/codex) to install the CLI on your system.

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

Codex uses a `config.toml` file, typically located at `~/.codex/config.toml`. Create or edit this file with the following configuration:

```toml
model_provider = "openrouter"
model_reasoning_effort = "high"
model="~openai/gpt-latest"

[model_providers.openrouter]
name = "openrouter"

base_url="https://openrouter.ai/api/v1"
env_key="OPENROUTER_API_KEY"
```

### Step 4: Set Your API Key

Export your OpenRouter API key in your shell profile:

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

Codex reads the API key from the environment variable specified in `env_key` (default: `OPENROUTER_API_KEY`). Ensure this is set before starting Codex.

### Step 5: Start Codex

Navigate to your project directory and run:

```bash
cd /path/to/your/project
codex
```

Your requests will now be routed through OpenRouter.

## Configuration Reference

### Core Settings

| Setting                    | Description                                   | Example                                  |
| -------------------------- | --------------------------------------------- | ---------------------------------------- |
| `model_provider`           | Provider to use for model requests            | `"openrouter"`                           |
| `model`                    | OpenRouter model ID                           | `"~openai/gpt-latest"`                   |
| `model_reasoning_effort`   | Reasoning effort level for Codex models       | `"low"`, `"medium"`, `"high"`, `"xhigh"` |
| `show_raw_agent_reasoning` | Whether to display reasoning tokens in the UI | `true` or `false`                        |
| `personality`              | Agent personality preset                      | `"pragmatic"`, `"helpful"`, etc.         |

### OpenRouter Provider Block

```toml
[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
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:

```toml
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
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](https://openrouter.ai/activity). 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](https://openrouter.ai/keys).
* **Model Not Found:** Verify the model ID on [openrouter.ai/models](https://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](https://openrouter.ai/privacy) for details.

## Resources

* [Codex CLI on GitHub](https://github.com/openai/codex)
* [OpenRouter Codex Models](https://openrouter.ai/models?q=codex)
* [OpenRouter Activity Dashboard](https://openrouter.ai/activity)
* [OpenRouter API Documentation](https://openrouter.ai/docs/api)