---
title: "Codex integration"
description: "Settings for using Codex with MiniRouter."
canonical_url: "https://minirouter.sh/docs/integrations/codex"
markdown_url: "https://minirouter.sh/docs/integrations/codex.md"
last_updated: "2026-09-26"
---

# Codex

Run OpenAI's coding agent on any model in the MiniRouter catalog.

[Get a key](https://minirouter.sh/key)

[Codex](https://developers.openai.com/codex) is OpenAI's coding agent for the terminal and IDE. Point it at MiniRouter's [Responses endpoint](https://minirouter.sh/docs/parameters) to run it on any tool-capable model in the [catalog](https://minirouter.sh/models), with one balance and per-key [spend limits](https://minirouter.sh/docs/rate-limits).

> **Note:** Codex talks to MiniRouter through `wire_api = "responses"`. Hosted web search stays off; local shell and file tools work as usual.

## Quick start

### 1. Install Codex

**npm**

```sh
npm install -g @openai/codex
```

**Homebrew**

```sh
brew install --cask codex
```

### 2. Export your key

[Create a key](https://minirouter.sh/key), then export it in the shell that launches Codex.

**macOS / Linux**

```sh
export MINIROUTER_KEY=mr-live-YOUR-KEY-HERE
```

**Windows**

```powershell
setx MINIROUTER_KEY mr-live-YOUR-KEY-HERE
```

> **Tip:** Give Codex its own key, so its spend shows separately in [Usage](https://minirouter.sh/dashboard/usage) and a limit stops only Codex.

### 3. Add the provider

Add MiniRouter to your user-level config.

```toml
model = "zai/glm-5.3-flash"
model_provider = "minirouter"
web_search = "disabled"

[model_providers.minirouter]
name = "MiniRouter"
base_url = "https://api.minirouter.sh/v1"
wire_api = "responses"
auth = { command = "sh", args = ["-c", "echo $MINIROUTER_KEY"] }
```

> **Warning:** Keep this block in `~/.codex/config.toml`. Codex ignores `model_provider` and `model_providers` in a project's `.codex/config.toml`.

### 4. Start a session

```sh
codex
```

Send one prompt, then open [Activity](https://minirouter.sh/dashboard/activity). The request lists its model, tokens and exact cost.

## Switch models

`/model` lists MiniRouter's options in this order:

1. Routers: [`minirouter/fusion`](https://minirouter.sh/docs/fusion), then [`minirouter/auto`](https://minirouter.sh/docs/auto-router) and its `:smart`, `:cheap` and `:code` intents.
2. Your [presets](https://minirouter.sh/docs/presets), as `@preset/your-slug`.
3. Every tool-capable model, frontier models first.

| Where | Scope |
| --- | --- |
| `/model` | Inside a session. |
| `codex -m minirouter/auto:code` | One run. |
| `model = "zai/glm-5.3-flash"` | The default, in `~/.codex/config.toml`. |

> **Note:** Routers carry no reasoning levels, so Codex sends no effort with them. Fusion is listed while its classifier is available.

## Pin a model per project

A trusted project can choose its own model. The provider stays in your user config.

```toml
model = "@preset/your-slug"
```

A [preset](https://minirouter.sh/docs/presets) lets you change the model from the dashboard without touching the repository.

## Run headless

`codex exec` runs one task without the TUI. Use it in scripts and CI, or see [Automatic code review](https://minirouter.sh/docs/guides/code-review) for a pull request workflow.

```sh
codex exec -m zai/glm-5.3-flash \
  --sandbox workspace-write \
  --json "Run the tests and fix failures"
```

| Flag | Does |
| --- | --- |
| `--sandbox workspace-write` | Allows edits. The default is read-only. |
| `--json` | Prints events as JSON Lines. |
| `--ephemeral` | Keeps no session files. |

> **Warning:** Codex reads the key through the auth command, so the job must export `MINIROUTER_KEY`.

## Keep spend in check

- [Own key](https://minirouter.sh/dashboard/keys): One key for Codex.
- [Spend cap](https://minirouter.sh/docs/rate-limits): Daily or monthly limit on that key.
- [Activity](https://minirouter.sh/dashboard/activity): Every request and its cost.

Restrict models or filter content with [Guardrails](https://minirouter.sh/docs/guardrails).

## Recommended models

| Model | Why |
| --- | --- |
| [`zai/glm-5.3-flash`](https://minirouter.sh/models/zai/glm-5.3-flash) | Best current balance of coding ability, agentic performance, context and cost. |
| [`openai/gpt-5.6-sol`](https://minirouter.sh/models/openai/gpt-5.6-sol) | Higher-intelligence option when task quality matters more than spend. |
| [`spacexai/grok-4.6`](https://minirouter.sh/models/spacexai/grok-4.6) | Strong agentic alternative with a 500K-token window. |
| [`google/gemini-3.8-flash`](https://minirouter.sh/models/google/gemini-3.8-flash) | Multimodal coding alternative with a 1M-token window. |

Browse every model in the [catalog](https://minirouter.sh/models).

## Troubleshooting

### Codex ignores the MiniRouter provider block

Project .codex/config.toml ignores model_provider, model_providers and profiles, and loads only in trusted projects. Put the provider block in ~/.codex/config.toml.

### Codex calls Chat Completions or reports an unsupported wire API

Set wire_api to responses. MiniRouter exposes the Responses route at /v1/responses; Codex appends /responses to the configured base URL.

Error: [400 `invalid_request`](https://minirouter.sh/docs/errors#invalid_request).

### Codex prints "provider auth command `sh` produced an empty token"

MINIROUTER_KEY is not exported in the shell that launched Codex. Run export MINIROUTER_KEY=… in that shell, or add the export to your shell profile, then start Codex again. Without the token Codex also skips the MiniRouter model list, so the fallback-metadata notice follows.

### Codex prints "Model metadata … not found. Defaulting to fallback metadata"

Codex 0.153 and later load a third-party model list only through a command-backed auth entry. Replace env_key with the auth line above; with env_key the notice is expected and harmless.

### 401 on every request

Wrong or rotated key. Keys start with mr-live-; after a rotation the old key keeps working for 24 hours, then dies.

Error: [401 `invalid_api_key`](https://minirouter.sh/docs/errors#invalid_api_key).

### 402 before any tokens arrive

Balance below the estimated cost of the request. Top up (from $0.50 with direct Solana payments) — and watch the x-minirouter-balance-usd header, the low-balance signal every response carries.

Error: [402 `insufficient_credits`](https://minirouter.sh/docs/errors#insufficient_credits).

Every error code, with its fix: [Errors](https://minirouter.sh/docs/errors).

## Next steps

- [Presets](https://minirouter.sh/docs/presets): Save a model and its settings under one name.
- [Guardrails](https://minirouter.sh/docs/guardrails): Budgets and model lists per key.
- [Auto router](https://minirouter.sh/docs/auto-router): Let MiniRouter pick the model.