Configure Codex CLI

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

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