Codex CLI — Configuration with OmniRoute (中文 (简体))

TOML 是唯一有效的格式。 现代版 Codex 仅会读取 ~/.codex/config.toml （已使用 codex-cli 0.147.0 验证：codex --help 中说明， -c/--config 覆盖项“从 ~/.codex/config.toml 加载”）。旧的 ~/.codex/config.yaml 属于旧版 npm CLI，会被直接忽略且不会给出提示。控制面板生成器（/api/cli-tools/apply，工具 codex）会使用保守合并方式写入 TOML—— 现有键和其他提供者配置块会被保留，API 密钥保存在 OMNIROUTE_API_KEY 中（绝不会写入文件），而遗留的旧版 config.yaml 会作为迁移提示报告，但不会被修改。

可直接粘贴的 config.toml

将 <YOUR_HOST> 和 <YOUR_KEY> 替换为你的值：

model                          = "cx/gpt-5.5"
model_provider                 = "omniroute"
model_reasoning_effort         = "xhigh"
model_context_window           = 400000
model_auto_compact_token_limit = 350000
tool_output_token_limit        = 32768    # 每次工具调用的历史记录存储上限

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://<YOUR_HOST>:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api             = "responses"

# ~/.bashrc 或 ~/.zshrc——实际密钥值，绝不要写入 config.toml
export OMNIROUTE_API_KEY="<YOUR_KEY>"

macOS：捆绑在 ChatGPT 应用中的 Codex

如果你通过 ChatGPT 桌面应用安装了 Codex，codex 二进制文件可能仅存在于应用包内部，尚未加入 shell 的 PATH。请将资源目录添加到 shell 启动文件中：

export PATH="/Applications/ChatGPT.app/Contents/Resources:$PATH"

打开一个新的 shell，然后验证：

command -v codex
codex --version

本地无身份验证的 OmniRoute：占位密钥即可

在第一个请求离开 CLI 之前，Codex 会验证 env_key 指定的环境变量是否存在。如果你的本地 OmniRoute 实例不要求身份验证，则任何非空占位值都可以：

export OMNIROUTE_API_KEY="${OMNIROUTE_API_KEY:-local}"

如果你的 OmniRoute 服务器受保护或位于远程，请改用真实密钥。

常见主机选项

访问方式 URL

本地网络 http://192.168.0.1:20128/v1

Tailscale http://100.x.x.x:20128/v1

环回地址 http://localhost:20128/v1

访问方式	URL
本地网络	`http://192.168.0.1:20128/v1`
Tailscale	`http://100.x.x.x:20128/v1`
环回地址	`http://localhost:20128/v1`

`wire_api = "responses"`——为何它适用于所有模型

Codex CLI 已于 2026 年 2 月弃用 wire_api = "chat"（Chat Completions），现在要求使用 wire_api = "responses"（OpenAI Responses API）。从 v0.138 开始，设置 wire_api = "chat" 会导致启动时立即崩溃。

包括 GLM 和 Kimi 在内的许多提供者仍然只提供 Chat Completions 端点。DeepSeek V4 现在除 Anthropic 兼容端点外，也提供原生 Responses API；OmniRoute 默认使用 Responses，并允许每个 DeepSeek 连接选择 Anthropic 兼容模式。

OmniRoute 会透明地解决这一问题：

Codex CLI
  → wire_api = "responses"
  → POST /v1/responses (OmniRoute)
    → OmniRoute 选择提供者的原生协议，并在需要时进行转换
    → POST /responses (DeepSeek V4) 或 /chat/completions (Mistral / GLM / Kimi / 其他)

使用 OmniRoute 时，你无需单独的转换代理。所有模型都使用 wire_api = "responses"——其余工作由 OmniRoute 处理。

wire_api 是默认设置——该字段默认为 "responses"，可以完全从 config.toml 中省略。只有在需要明确记录配置意图时，才应显式设置它。

上下文窗口与压缩

Token 配置字段

字段	说明
`model_context_window`	当前模型的总 Token 预算。请将其设置为模型公开声明的上限。
`model_auto_compact_token_limit`	触发自动历史记录压缩的阈值。最大值：`model_context_window` 的 90% — 超过 90% 的值会被静默忽略。
`tool_output_token_limit`	历史记录中每次工具调用输出所存储的 Token 上限。防止单个大型工具响应占满窗口。这并非最大输出量 — 它只是历史记录的存储上限。
`compact_prompt`	压缩期间所使用的系统提示词的内联覆盖配置（v0.138+）。

关于 model_max_output_tokens 的说明：此字段不属于 Codex CLI 配置模式（Codex Rust 代码库中不存在该字段）。即使设置，也会被静默忽略。请勿依赖此字段 — 请使用 tool_output_token_limit 控制历史记录中存储的工具输出量。

各模型的上下文窗口

模型	OmniRoute ID	上下文窗口	`auto_compact`	`tool_output_limit`
GPT-5.5	`cx/gpt-5.5`	400k 可靠（最大 1M）	350,000	32,768
Kimi K2.7（思考型）	`kmc/kimi-k2.7`	131,072	112,000	32,768
Kimi K2.6	`kmc/kimi-k2.6`	131,072	112,000	32,768
GLM-5.2 / 5.2-max（思考型）	`glm/glm-5.2`	131,072	112,000	32,768
MiMo V2.5 Pro（思考型）	`opencode-go/mimo-v2.5-pro`	131,072	112,000	32,768
Qwen 3.7 Plus（思考型）	`opencode-go/qwen3.7-plus`	32,768	28,000	16,384
DeepSeek V4 Pro（OllamaCloud）	`ollamacloud/deepseek-v4-pro`	131,072	112,000	32,768
DeepSeek V4 Pro	`ds/deepseek-v4-pro`	1,000,000	900,000	65,536
MiMo V2.5	`opencode-go/mimo-v2.5`	131,072	112,000	32,768
Gemma 4 31B（OllamaCloud）	`ollamacloud/gemma4:31b`	32,768	28,000	16,384
Nemotron 3 Super（OllamaCloud）	`ollamacloud/nemotron-3-super`	32,768	28,000	16,384
GPT-OSS 20B（OllamaCloud）	`ollamacloud/gpt-oss:20b`	32,768	28,000	16,384
DeepSeek V4 Flash（OllamaCloud）	`ollamacloud/deepseek-v4-flash`	65,536	56,000	16,384
Gemini 3 Flash Preview（OllamaCloud）	`ollamacloud/gemini-3-flash-preview`	1,000,000	850,000	32,768
GLM-5 Turbo	`glm/glm-5-turbo`	131,072	112,000	16,384
GLM-4.7 Flash	`glm/glm-4.7-flash`	131,072	112,000	16,384
Mistral Large Latest	`mistral/mistral-large-latest`	262,144	220,000	16,384

压缩公式： effective_window = model_context_window - min(tool_output_token_limit, 20000)。超过 20k 的值不会改变压缩触发点。

经验法则： 将 model_auto_compact_token_limit 设置为 model_context_window 的 85–88%。切勿超过 90% — 超过该值会被静默忽略。

模型前缀：`cx/`

OmniRoute 中的所有 Codex 模型都使用 cx/ 前缀：

Codex CLI 名称	OmniRoute 模型
`cx/gpt-5.5`	GPT-5.5 标准版
`cx/gpt-5.4`	GPT-5.4 标准版
`cx/gpt-5.4-mini`	GPT-5.4 mini
`cx/gpt-5.1-codex-mini`	GPT-5.1 Codex mini

其他提供者使用各自的前缀（kmc/、glm/、ds/、ollamacloud/、opencode-go/、mistral/）——该前缀与 OmniRoute 提供者别名一致。

推理强度

控制模型在响应前进行多少“思考”。

值	适用场景
`none`	不进行推理——直接响应
`low`	简单任务（重命名、格式化）
`medium`	未指定时的服务器默认值
`high`	中等难度任务（重构、调试）
`xhigh`	架构设计、深度分析、复杂问题

# 针对单次调用覆盖设置
codex -c model_reasoning_effort=low "rename variable x to count"
codex -c model_reasoning_effort=xhigh "design the auth module"

还需设置推理摘要，以便 Desktop 能够渲染思考文本（而不仅是加密的数据块）：

model_reasoning_effort = "xhigh"   # 支持时也可使用 ultra
model_reasoning_summary = "detailed"  # auto | concise | detailed | none

OmniRoute 思考预算（服务器设置）

在 OmniRoute 主机上，必须将 Settings → AI → Thinking Budget 设置为 passthrough，Codex 的推理强度/摘要才能传递到上游。auto 模式会移除所有客户端的 reasoning / reasoning_effort 字段，即使 Codex 配置正确，也会导致思考面板为空。

完整指南：THINKING_BUDGET.md。

压缩和提示词缓存相互独立，并且在 passthrough 模式下仍可正常工作。

配置文件——按模型/工作流命名的配置

配置文件允许你通过一个标志切换模型和上下文窗口。每个配置文件都是一个扁平的 ~/.codex/<name>.config.toml 文件，它会覆盖基础 config.toml 中的设置。

**命名规则（Codex CLI v0.137+）：**文件必须命名为 ~/.codex/<name>.config.toml——不要使用 profile- 前缀。 CLI 会将 -p kimi-k27 解析为 ~/.codex/kimi-k27.config.toml。如果找不到该文件，则会静默应用默认配置。

codex --profile kimi-k27 "analyze 10k lines of this codebase"
codex -p glm52 "architecture review"
codex --profile deepseek-flash "rename variable"   # 快速、低成本

推理强度配置文件（相同模型，不同强度）

codex -p low      # cx/gpt-5.5，effort=low
codex -p medium   # cx/gpt-5.5，effort=medium
codex -p high     # cx/gpt-5.5，effort=high
codex -p xhigh    # cx/gpt-5.5，effort=xhigh（默认）
codex -p chat     # cx/gpt-5.5，未设置 effort（服务器默认值）

思考模型（深度思考）——xhigh + 详细摘要

配置文件	模型	上下文	适用场景
`kimi-k27`	`kmc/kimi-k2.7`	128k	最佳思考质量（Kimi）
`glm52`	`glm/glm-5.2`	128k	GLM 思考
`glm52max`	`glm/glm-5.2-max`	128k	GLM 最大思考能力
`mimo-pro`	`opencode-go/mimo-v2.5-pro`	128k	MiMo 思考
`qwen37plus`	`opencode-go/qwen3.7-plus`	32k	Qwen 思考

优质模型——高推理强度

配置文件	模型	上下文	适用场景
`kimi-k26`	`kmc/kimi-k2.6`	128k	通用用途（Kimi）
`deepseek-pro`	`ollamacloud/deepseek-v4-pro`	128k	通过 OllamaCloud 使用 DeepSeek Pro
`deepseek`	`ds/deepseek-v4-pro`	1M	直连 DeepSeek Pro，超大上下文
`mimo`	`opencode-go/mimo-v2.5`	128k	MiMo 通用模型

简单模型——不设置推理强度

配置文件	模型	上下文	适用场景
`gemma4`	`ollamacloud/gemma4:31b`	32k	高性价比且能力出色
`nemotron`	`ollamacloud/nemotron-3-super`	32k	NVIDIA Nemotron
`gptoss`	`ollamacloud/gpt-oss:20b`	32k	开源 GPT

快速模型——低推理强度

配置文件	模型	上下文	适用场景
`deepseek-flash`	`ollamacloud/deepseek-v4-flash`	64k	快速任务
`gemini-flash`	`ollamacloud/gemini-3-flash-preview`	1M	速度极快、超大上下文
`glm5turbo`	`glm/glm-5-turbo`	128k	GLM Turbo
`glm47flash`	`glm/glm-4.7-flash`	128k	GLM Flash
`mistral`	`mistral/mistral-large-latest`	256k	Mistral Large

快速决策表

任务	推荐配置文件
重命名、格式化、样板代码	`--profile deepseek-flash` 或 `-p low`
解释、轻量审查	`-p chat` 或 `-p gemini-flash`
调试、中等规模重构	`-p medium` 或 `-p kimi-k26`
新功能、复杂测试	`-p high` 或 `-p mimo`
架构、深度分析	`-p kimi-k27` 或 `-p glm52` 或 `-p xhigh`
代码库分析（需要 1M 上下文）	`--profile deepseek` 或 `--profile gemini-flash`
最高思考质量	`-p glm52max` 或 `-p mimo-pro`
注重成本	`-p gemma4` 或 `-p gptoss`

使用 `omniroute setup-codex` 自动生成配置文件

如果你在 VPS 上运行 OmniRoute，可以根据实时模型目录自动生成配置文件：

# 从 VPS 运行（使用端口 20128 上的本地 OmniRoute）
omniroute setup-codex

# 从任意计算机运行——指向你的 VPS
omniroute setup-codex --remote http://100.x.x.x:20128 --api-key sk-xxx

# 预览但不写入文件
omniroute setup-codex --remote http://100.x.x.x:20128 --dry-run

# 仅生成 GLM 和 Kimi 配置文件
omniroute setup-codex --only glm,kimi

# 写入自定义目录
omniroute setup-codex --codex-home /path/to/.codex

该命令会获取 /v1/models，对已知模型使用经过调优的配置，对其他兼容的文本模型则回退使用目录元数据，并为每个模型写入 ~/.codex/<name>.config.toml。该操作具有幂等性，可安全地重复运行。

当成功发现/导入提供者模型并导致实时目录发生变化后，OmniRoute 还可以自动同步这些配置文件。此功能需要主动启用，默认关闭：可在 CLI Code 仪表板中切换（“CLI 配置文件自动同步”→ Codex），或设置 OMNIROUTE_AUTO_SYNC_CODEX_PROFILES=true（它也会遵循 CLI_ALLOW_CONFIG_WRITES，该选项默认启用）。启用后，它只会写入独立的 ~/.codex/*.config.toml 配置文件；绝不会更改当前/默认的 ~/.codex/config.toml、Codex-lb 设置、身份验证或提供者选择。

使用 `omniroute launch-codex` 启动 Codex

在启动 Codex 之前检查 OmniRoute 实例的运行状况：

# 使用本地 OmniRoute 启动（默认端口 20128）
omniroute launch-codex

# 使用指定配置文件启动
omniroute launch-codex --profile kimi-k27

# 使用远程 VPS 启动
omniroute launch-codex --remote http://100.x.x.x:20128/v1 --api-key sk-xxx

# 向 codex 传递额外参数
omniroute launch-codex --profile glm52 -- --yolo "fix this bug"

Codex 也是以下两个由清单驱动的通用入口点的目标（bin/cli/cli-manifest.mjs）：

# 交互式模型选择器 → 写入 ~/.codex/&lt;name&gt;.config.toml（TOML、env_key）
omniroute configure codex

# 通过 -c 标志注入 omniroute 提供者并启动 codex（不写入配置）
omniroute run codex

Codex CLI 新功能（v0.138–v0.141）

版本	功能
v0.138	桌面应用移交（`/app`）、v2 个人访问令牌、将 `--profile` 作为唯一的配置文件选择器（旧版文件内 `[profiles]` 表会导致启动时崩溃）
v0.139	`web_search = "live"`——在代码模式下使用原生网页搜索；MCP 工具架构中的 `oneOf`/`allOf`；`codex doctor` 环境诊断
v0.140	会话内 `/usage` 令牌视图；从 Claude Code 会话执行 `/import`；`codex delete <SESSION_ID>` 子命令；通过提供者配置中的 `aws` 对象进行 Amazon Bedrock 身份验证
v0.141	用于远程执行器的端到端加密 Noise 中继；SQLite WAL 修复；P-521 TLS 支持

新增 `config.toml` 字段（v0.137 之后）

# 原生网页搜索（v0.139）
web_search = "live"   # "disabled" | "cached" | "live"

# 独立的开发者系统提示词（v0.138）
developer_instructions = "Always prefer functional style."

# 自定义压缩提示词
compact_prompt = "Summarise the above as bullet points."

# 将 /review 路由到成本更低的模型
review_model = "glm/glm-5-turbo"

# OpenAI 服务层级
service_tier = "fast"   # "fast" | "flex"

新增 `[model_providers.<id>]` 字段

[model_providers.omniroute]
base_url             = "http://100.x.x.x:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false

# 每个请求附带的静态额外请求头
[model_providers.omniroute.http_headers]
"X-Custom-Header" = "value"

# 从环境变量读取的请求头
[model_providers.omniroute.env_http_headers]
"X-Trace-Id" = "TRACE_ID"

# 额外的 URL 查询参数（适用于 Azure api-version）
[model_providers.omniroute.query_params]
"api-version" = "2024-12-01-preview"

Amazon Bedrock 身份验证（v0.140）

[model_providers.bedrock]
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"

[model_providers.bedrock.aws]
profile = "default"   # ~/.aws/credentials 配置文件
region  = "us-east-1"

多台服务器

[model_providers.omniroute-main]
base_url = "http://192.168.0.1:20128/v1"
env_key  = "OMNIROUTE_API_KEY"

[model_providers.omniroute-tailscale]
base_url = "http://100.x.x.x:20128/v1"
env_key  = "OMNIROUTE_API_KEY"

Claude Code — 等效配置

Codex CLI (`config.toml`)	Claude Code（环境变量）	效果
`tool_output_token_limit = 32768`	（未直接公开）	单个工具的历史记录上限
`model_context_window = 400000`	（由模型决定）	上下文窗口
—	`CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536`	每次响应的最大 token 数

# ~/.bashrc — Claude Code token 上限
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536

快速参考 — CLI 标志

标志	简写	效果
`--model <id>`	`-m`	覆盖本次调用的 `model`
`--profile <name>`	`-p`	加载 `~/.codex/<name>.config.toml`
`--config key=value`	`-c`	覆盖任意 config.toml 字段（可重复使用）
`--enable <feature>`	—	强制启用某个功能标志
`--disable <feature>`	—	强制禁用某个功能标志
`--search`	—	为本次调用启用实时网页搜索

v0.140 中的新增功能：

codex delete <SESSION_ID>          # 删除会话
codex delete <SESSION_ID> --force  # 跳过确认
codex debug models --bundled       # 以 JSON 格式列出内置模型目录

在交互式会话中：

命令	效果
`/model`	打开模型选择器
`/usage`	显示本次会话的 token 使用情况（v0.140）
`/app`	移交给桌面应用（v0.138）
`/import`	导入 Claude Code 会话（v0.140）
`/help`	列出所有斜杠命令

长时间运行的任务

OmniRoute 的两个默认设置可能会悄无声息地破坏持续数小时的 Codex CLI 会话。它们都不是 Codex CLI 设置，而是位于 OmniRoute 端。用户从会固定账户并禁用空闲截止限制的上游代理迁移配置时，往往会同时遇到这两个问题，并得出 OmniRoute“无法维持长时间会话”的结论。

症状	可能的原因	配置项
会话不断切换账户／各轮之间的提示缓存连续性丢失	会话亲和性 TTL 为 `0`（已禁用）	`sessionAffinityTtlMs`
推理过程中连接中断，且客户端未收到任何提示	连续 10 分钟未收到上游数据块，触发了流空闲监视器	`STREAM_IDLE_TIMEOUT_MS`

相关讨论：#7126（长任务中断）、#5718（为何默认关闭亲和性）。跟踪问题：#7287。

1. 会话亲和性 — 将一个对话固定到一个账户

默认值： sessionAffinityTtlMs = 0（已禁用）。

设置位置

控制面板 → 设置 → 路由 → 会话亲和性 → 亲和性 TTL（秒）（ComboDefaultsTab）
或者通过 PATCH 设置 sessionAffinityTtlMs，单位为毫秒（Zod 范围为 0–86_400_000，即最长 24 小时）

在 #7274 中由仅适用于 Codex 的 codexSessionAffinityTtlMs 重命名而来。旧键仍作为只读别名被接受；新配置应使用 sessionAffinityTtlMs。现在，只要 TTL 大于 0，亲和性就会应用于任何提供者，而不仅仅是 Codex — 请参阅 docs/architecture/RESILIENCE_GUIDE.md → 会话亲和性。

保持为 0 时会出现什么问题

多轮 Codex 对话中的每一轮都会由当前启用的组合策略独立路由，因此每一轮都可能落到不同的账户上。这会破坏上游会话／提示缓存的连续性。只有当 TTL 大于 0 时，OmniRoute 才会读取 Codex 会话标头（x-codex-session-id / x-session-id / x-omniroute-session）以及 prompt_cache_key / session_id 等请求体字段（src/sse/services/auth.ts 中的 extractSessionAffinityKey）。

针对持续数小时的单个任务的建议

将 TTL 设置为高于任务预期的实际运行时长（UI 最大值为 86400 秒，即 24 小时）：

预期任务时长	亲和性 TTL（UI，秒）	`sessionAffinityTtlMs`
数小时	`14400`（4 小时）	`14400000`
过夜／约 12 小时	`43200`（12 小时）	`43200000`
一整天	`86400`（24 小时，最大值）	`86400000`

选择性启用是有意为之：禁用亲和性有利于在多个账户间进行负载均衡；启用亲和性则有利于保持单个长时间代理会话的连续性。本指南不会更改默认值 — 运行长时间 Codex 任务的运维人员必须自行启用。

2. 流空闲超时 — 不要终止安静的推理轮次

默认值： STREAM_IDLE_TIMEOUT_MS = 600000（10 分钟）。如果未设置，它会继承 REQUEST_TIMEOUT_MS；共享基准值同样为 600000。请参阅 docs/guides/SETUP_GUIDE.md → 超时设置。

使用默认值时会出现什么问题

Codex 推理/工具调用轮次如果超过 10 分钟保持静默，且没有真正的上游数据块，就会被 SSE 空闲看门狗（open-sse/utils/stream.ts）强制关闭。客户端通常只会看到连接直接断开——这与“在没有任何通知的情况下自动停止”一致。

关键细节：OmniRoute 生成的 SSE 心跳不会重置空闲计时器。只有真正的上游响应体数据块才会更新 lastChunkTime。从看门狗的角度来看，仍在“思考”的静默模型与停滞的上游没有区别。

相关的 Undici 响应体非活动超时：FETCH_BODY_TIMEOUT_MS（默认值也采用相同的 10 分钟基准；设置为 0 可将其禁用）。对于流式传输，FETCH_TIMEOUT_MS 仅涵盖连接建立/首个响应头阶段——流一旦激活，停滞就由 STREAM_IDLE_TIMEOUT_MS 和 FETCH_BODY_TIMEOUT_MS 控制。

针对耗时数小时的单个任务的建议

在 OmniRoute 进程环境中（.env / compose / systemd）：

# 对长时间推理轮次禁用流空闲和响应体非活动超时限制
STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0

或者将它们提高到超过预期最长静默间隔的值（单位为毫秒）：

# 示例：允许上游数据块之间最多静默 2 小时
STREAM_IDLE_TIMEOUT_MS=7200000
FETCH_BODY_TIMEOUT_MS=7200000

更改这些环境变量后重启 OmniRoute。

具体操作步骤——耗时数小时的 Codex 任务

固定账户： Dashboard → Settings → Routing → Session affinity → Affinity TTL = 43200（12 小时）或 86400（最长 24 小时）。
提高/禁用空闲超时限制，在 OmniRoute 的环境中设置：

STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0

保持常规的 Codex config.toml 配置（wire_api = "responses"、正确的 base_url、OMNIROUTE_API_KEY）——对于这两种行为，Codex 端不存在会话亲和性/空闲超时配置项。
重启 OmniRoute，然后启动长时间运行的 Codex 任务。

默认值决定（#7287）

配置项	发布默认值	本指南中是否更改？
`sessionAffinityTtlMs`	`0`（关闭）	否——仍为可选配置（负载均衡与连续性之间的权衡；参见 Discussion #5718）
`STREAM_IDLE_TIMEOUT_MS`	`600000`（10 分钟）	否——常规流量仍保持 10 分钟；运行长时间 Codex 任务的运维人员可提高或禁用该限制

全局更改任一默认值都会改变实例中所有客户端的行为，而不仅仅是 Codex。应记录这些配置项；在运维人员作出明确决定之前，保持默认值不变。

诊断空闲超时中断

当空闲看门狗触发时，OmniRoute 会记录一条类似如下的日志：

[STREAM] Idle timeout: no data from codex for 600000ms (model: cx/gpt-5.5)

搜索 Idle timeout: no data from（或代码 stream_idle_timeout / 错误名称 StreamIdleTimeoutError）。提供者部分取决于 OmniRoute 为该请求实际使用的值（codex、其他提供者 ID，或者在未知时为 provider）——它并不总是字面字符串 codex。

故障排除

Error: wire_api = "chat" is no longer supported 从配置中移除 wire_api = "chat"。设置 wire_api = "responses"，或省略该字段（自 v0.138 起默认为 "responses"）。

Error: model not found 确认 OmniRoute 中存在该模型，并且使用了正确的前缀。使用 omniroute models list，或打开 /dashboard/providers/<provider>。

Authentication error 确认已导出 OMNIROUTE_API_KEY：echo $OMNIROUTE_API_KEY。

ERROR: Missing environment variable: OMNIROUTE_API_KEY Codex 会在发出第一个请求之前验证该环境变量是否存在。对于受保护的服务器，请导出真实密钥；如果你的本地 OmniRoute 实例不需要身份验证，则可使用非空占位值，例如 OMNIROUTE_API_KEY=local。如果你将其添加到了 ~/.bashrc 或 ~/.zshrc，请重启 shell。

Connection refused 确认 OmniRoute 正在运行，并且 base_url 的主机/端口对于你的网络环境（本地、Tailscale 或 VPS）是正确的。

会话在接近上下文限制时崩溃 显式设置 model_context_window 和 model_auto_compact_token_limit。请参阅上方的上下文窗口表。

压缩触发得太晚 将 model_auto_compact_token_limit 降至上下文窗口的 80–85%。切勿设置为高于 90%。

配置文件未加载（-p <name> 被静默忽略） 确认文件存在于 ~/.codex/<name>.config.toml（没有 profile- 前缀）。运行 ls ~/.codex/*.config.toml。

长时间运行的 Codex 任务在执行中途断开/在不同轮次之间切换账户 请参阅长时间运行的任务。启用会话亲和性（TTL 应长于任务时长），并提高或禁用 STREAM_IDLE_TIMEOUT_MS / FETCH_BODY_TIMEOUT_MS。在 OmniRoute 日志中使用 grep 搜索 Idle timeout: no data from。

OmniRoute 源码 (a58000c7685f)

HagiCode

HagiCode 是一套智能体编码工作台：结构化工作流、多 Agent 并行执行与 Hero Dungeon 视图，把想法变成真正交付的软件。

让想法更快变成好用的软件，让智能编码更聪明、更高效，也更有趣。

Smart结构化工作流将意图转化为从想法到交付的可执行路径。
Efficient多 Agent 工作流让调研、实现与审阅并行推进。
FunHero Dungeon 让长时间编码协作更直观、更有参与感。

访问 HagiCode

选择语言

选择语言

Codex CLI — Configuration with OmniRoute (中文 (简体))

可直接粘贴的 config.toml

macOS：捆绑在 ChatGPT 应用中的 Codex

本地无身份验证的 OmniRoute：占位密钥即可

`wire_api = "responses"`——为何它适用于所有模型

上下文窗口与压缩

Token 配置字段

各模型的上下文窗口

模型前缀：`cx/`

推理强度

OmniRoute 思考预算（服务器设置）

配置文件——按模型/工作流命名的配置

推理强度配置文件（相同模型，不同强度）

思考模型（深度思考）——xhigh + 详细摘要

优质模型——高推理强度

简单模型——不设置推理强度

快速模型——低推理强度

快速决策表

使用 `omniroute setup-codex` 自动生成配置文件

使用 `omniroute launch-codex` 启动 Codex

Codex CLI 新功能（v0.138–v0.141）

新增 `config.toml` 字段（v0.137 之后）

新增 `[model_providers.<id>]` 字段

Amazon Bedrock 身份验证（v0.140）

多台服务器

Claude Code — 等效配置

快速参考 — CLI 标志

长时间运行的任务

1. 会话亲和性 — 将一个对话固定到一个账户

2. 流空闲超时 — 不要终止安静的推理轮次

具体操作步骤——耗时数小时的 Codex 任务

默认值决定（#7287）

诊断空闲超时中断

故障排除

HagiCode

Codex CLI — Configuration with OmniRoute (中文 (简体))

可直接粘贴的 config.toml

macOS：捆绑在 ChatGPT 应用中的 Codex

本地无身份验证的 OmniRoute：占位密钥即可

wire_api = "responses"——为何它适用于所有模型

上下文窗口与压缩

Token 配置字段

各模型的上下文窗口

模型前缀：cx/

推理强度

OmniRoute 思考预算（服务器设置）

配置文件——按模型/工作流命名的配置

推理强度配置文件（相同模型，不同强度）

思考模型（深度思考）——xhigh + 详细摘要

优质模型——高推理强度

简单模型——不设置推理强度

快速模型——低推理强度

快速决策表

使用 omniroute setup-codex 自动生成配置文件

使用 omniroute launch-codex 启动 Codex

Codex CLI 新功能（v0.138–v0.141）

新增 config.toml 字段（v0.137 之后）

新增 [model_providers.&lt;id&gt;] 字段

Amazon Bedrock 身份验证（v0.140）

多台服务器

Claude Code — 等效配置

快速参考 — CLI 标志

长时间运行的任务

1. 会话亲和性 — 将一个对话固定到一个账户

2. 流空闲超时 — 不要终止安静的推理轮次

具体操作步骤——耗时数小时的 Codex 任务

默认值决定（#7287）

诊断空闲超时中断

故障排除

HagiCode

`wire_api = "responses"`——为何它适用于所有模型

模型前缀：`cx/`

使用 `omniroute setup-codex` 自动生成配置文件

使用 `omniroute launch-codex` 启动 Codex

新增 `config.toml` 字段（v0.137 之后）

新增 `[model_providers.<id>]` 字段