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.

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:

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.