<!-- 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
- Dashboard → Settings → Routing → Session affinity → Affinity TTL =
43200 (12h) or 86400 (24h max).
- OmniRoute environment:
STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0
- 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 -->