---
name: config-codex-cli
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.
---
<!-- 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

1. Dashboard → Settings → Routing → Session affinity → Affinity TTL = `43200` (12h) or `86400` (24h max).
2. OmniRoute environment:

```bash
STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0
```

3. Restart OmniRoute. Leave Codex `config.toml` as usual (`wire_api = "responses"`, correct `base_url`).

### Defaults decision

Do **not** flip ship defaults in code for this skill: `sessionAffinityTtlMs` stays `0` and `STREAM_IDLE_TIMEOUT_MS` stays `600000`. Long-running operators must opt in. See Discussion #5718 and issue #7287.
<!-- skill:custom-end -->