# Configure Codex CLI

Configures the Codex CLI to use OmniRoute as its backend on any major OS.

- Repository: https://github.com/cheaper-inference/OmniRoute (83611 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add cheaper-inference/OmniRoute --skill config-codex-cli -g -a claude-code -y`
Codex: `npx skills add cheaper-inference/OmniRoute --skill config-codex-cli -g -a codex -y`
Cursor: `npx skills add cheaper-inference/OmniRoute --skill config-codex-cli -g -a cursor -y`
Gemini CLI: `npx skills add cheaper-inference/OmniRoute --skill config-codex-cli -g -a gemini-cli -y`

## Description

Step-by-step agent workflow to configure the OpenAI Codex CLI on any machine (Linux, macOS, Windows) to use OmniRoute as an OpenAI-compatible backend. Detects OS and shell, writes config.toml and 7 named profiles, sets environment variables, and verifies the setup.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

## Overview

Step-by-step agent workflow to configure the OpenAI Codex CLI on any machine (Linux, macOS, Windows) to use OmniRoute as an OpenAI-compatible backend. Detects OS and shell, writes config.toml and 7 named profiles, sets environment variables, and verifies the setup.

## Quick install

```bash
npm install -g omniroute   # or: npx omniroute
omniroute --version
```

## Subcommands

_No CLI subcommands mapped for this family yet._

<!-- skill:custom-start -->

## Long-running Codex tasks (#7287)

Two OmniRoute defaults silently break multi-hour Codex sessions. Document them whenever configuring Codex for overnight / multi-hour work. Full guide: `docs/guides/CODEX-CLI-CONFIGURATION.md` → **Long-running tasks**.

### Session affinity (default off)

- Setting: `sessionAffinityTtlMs` (ms; UI shows **Affinity TTL (seconds)** under Dashboard → Settings → Routing → Session affinity). Legacy alias: `codexSessionAffinityTtlMs`.
- Default `0` = disabled. Each turn can land on a different account and break prompt-cache / session continuity.
- Codex session keys (`x-codex-session-id`, `x-session-id`, `x-omniroute-session`, body `prompt_cache_key` / `session_id`) are only used for pinning when TTL > 0.
- Max: `86400` seconds / `86400000` ms (24h). Set TTL **above** the expected task length (e.g. `43200` s for ~12h).

### Stream idle timeout (default 10 minutes)

- Env: `STREAM_IDLE_TIMEOUT_MS` (default `600000`). Also consider `FETCH_BODY_TIMEOUT_MS` (same baseline; `0` disables).
- Synthetic SSE heartbeats do **not** reset the idle clock, only real upstream chunks do.
- A quiet reasoning turn past the idle window is force-closed (`stream_idle_timeout` / `StreamIdleTimeoutError`). Grep logs for `Idle timeout: no data from`.

### Recommended multi-hour recipe

The rest: https://github.com/cheaper-inference/OmniRoute/blob/HEAD/skills/config-codex-cli/SKILL.md