OmniRoute/skills/config-codex-cli/SKILL.md at aa7b3913862cf2f32a5cd7f09c8ffb9be87c19d0

mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-07 15:52:52 +03:00

Files

AmirHossein Rezaei 85128984f9 docs(codex): document session affinity and stream idle for long tasks (#8709 )

* docs(codex): document session affinity and stream idle for long tasks

Operators running multi-hour Codex sessions need both knobs spelled out:
sessionAffinityTtlMs (default off) and STREAM_IDLE_TIMEOUT_MS (10 min),
with a concrete recipe and an explicit keep-defaults decision (#7287).

* fix(ci): keep #7287 docs-only so base-red gates stay skipped

Drop the unit content-guard that classified the PR as code (triggering
i18n/unit/eslint/dast on a red release tip). Sync agent-skills so
check:agent-skills-sync passes (config-codex-cli blank line + stale
cli-backup-sync catalog drift).

2026-07-27 17:24:48 -03:00

2.7 KiB

Raw Blame History

name, description

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

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

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.

2.7 KiB Raw Blame History