config-codex-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

用于在任何机器（Linux、macOS、Windows）上配置 OpenAI Codex CLI，使其使用 OmniRoute 作为兼容 OpenAI 的后端的分步 Agent 工作流。可检测操作系统和 shell，编写 config.toml 与 7 个命名 profile，设置环境变量并验证配置。

Quick install

快速安装

bash

npm install -g omniroute   # or: npx omniroute
omniroute --version

bash

npm install -g omniroute   # or: npx omniroute
omniroute --version

Subcommands

子命令

No CLI subcommands mapped for this family yet.

此系列尚未映射任何 CLI 子命令。

Long-running Codex tasks (#7287)

长时间运行的 Codex 任务（#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.

OmniRoute 的两个默认设置会悄然中断持续数小时的 Codex 会话。为 Codex 配置通宵或数小时的工作时，请务必记录这些设置。完整指南：

docs/guides/CODEX-CLI-CONFIGURATION.md

→ 长时间运行的任务。

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).

设置项：
```
sessionAffinityTtlMs
```
（毫秒；UI 中位于 Dashboard → Settings → Routing → Session affinity 下，显示为 Affinity TTL (seconds)）。旧版别名：
```
codexSessionAffinityTtlMs
```
。
默认值为
```
0
```
，即禁用。每个轮次都可能落到不同账户上，从而破坏 prompt-cache / session continuity（提示词缓存与会话连续性）。
仅当 TTL 大于 0 时，Codex 会话键（
```
x-codex-session-id
```
、
```
x-session-id
```
、
```
x-omniroute-session
```
、请求体中的
```
prompt_cache_key
```
/
```
session_id
```
）才会用于固定会话。
最大值为
```
86400
```
秒 /
```
86400000
```
毫秒（24 小时）。应将 TTL 设置为高于预期任务时长，例如约 12 小时的任务设置为
```
43200
```
秒。

Stream idle timeout (default 10 minutes)

流式空闲超时（默认 10 分钟）

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

环境变量：
```
STREAM_IDLE_TIMEOUT_MS
```
（默认值为
```
600000
```
）。同时考虑
```
FETCH_BODY_TIMEOUT_MS
```
（采用相同基线；设置为
```
0
```
可禁用）。
合成的 SSE 心跳不会重置空闲计时器，只有真实的上游数据块才会重置。
如果推理轮次在空闲窗口内始终没有数据，将被强制关闭（
```
stream_idle_timeout
```
/
```
StreamIdleTimeoutError
```
）。可在日志中搜索
```
Idle timeout: no data from
```
。

Recommended multi-hour recipe

Defaults decision

默认值决策

Do not flip ship defaults in code for this skill:

sessionAffinityTtlMs

stays

and

STREAM_IDLE_TIMEOUT_MS