Skill64.3k repo starsupdated yesterday

config-codex-cli

This Claude Code skill automates the setup of OpenAI's Codex CLI to use an OmniRoute instance as its backend service. It collects the OmniRoute host and API key, detects the user's operating system and shell environment, creates necessary configuration directories, generates a config.toml file with seven named model profiles, writes environment variables to the appropriate shell configuration file, and validates the complete setup across Linux, macOS, and Windows platforms.

View source Repository: OmniRoute

Install in Claude Code

Copy

git clone --depth 1 https://github.com/diegosouzapw/OmniRoute /tmp/config-codex-cli && cp -r /tmp/config-codex-cli/skills/config-codex-cli ~/.claude/skills/config-codex-cli

Then start a new Claude Code session; the skill loads automatically.

Definition

SKILL.md

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

```bash
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

1. Dashboard → Settings → Routing → Session affinity → Affinity TTL = `43200` (12h) or `86400` (24h max).
2. OmniRoute environment:

```bash
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.
<!-- skill:custom-end -->