config-codex-cli

Original：🇺🇸 English

Translated

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.

3installs

Sourcecheaper-inference/omniroute

Added on2026-10-30

NPX Install

npx skill4agent add cheaper-inference/omniroute config-codex-cli

SKILL.md Content

View Translation Comparison →

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.

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:

bash

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

and

STREAM_IDLE_TIMEOUT_MS