企业官网建设流程全解析

OmX 如何配置 .omx-config.json 的模型路由：agentModels、agentReasoning 与 env 默认模型

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex

在 oh-my-codex（OmX）里，每个 agent 角色（planner、architect、explore 等）走哪条模型通道、用多大推理强度，是由.omx-config.json决定的。如果你希望某个角色固定用指定模型、把部分角色切到低成本模型，或者整体更换 frontier/standard/spark 三条通道的默认模型，就需要编辑这份配置文件中的agentModels、agentReasoning、env（以及配套的models）四组键。本文按“定位文件 → 写配置 → 重新生成 → 验证生效”的路径展开，适用于已安装 OmX、需要调整模型路由的开发者。完整的键形说明见 omx-config-schema-routing.md，模型路由的源码实现在 src/config/models.ts。

.omx-config.json 在哪里被读取

大多数.omx-config.json读取方都通过当前激活的 Codex home 解析文件位置，两种部署形态对应两个位置：

omx setup --scope project会把 project 选择持久化到./.omx/setup-scope.json；omx doctor会打印当前解析出的 setup scope 以及它正在检查的 Codex home 和 config 路径。作用域解析逻辑在 src/cli/codex-home.ts 中。

一个容易踩的边界：wiki 生命周期读取是项目根目录的例外，它先查<root>/.omx-config.json，再查${CODEX_HOME:-~/.codex}/.omx-config.json，两者都没有有效wiki对象时回退到内置默认值。除这个例外外，按上表定位你的文件即可。

配置前必须知道的优先级规则

四组键不是平替关系，而是不同粒度的覆盖层。配置前先确认你要改的是哪一层：

按角色的模型覆盖——agentModels优先于一切内置默认。对某个具名角色，生效模型按以下顺序取：

1. .omx-config.json的agentModels[role]
2. 内置exactModel固定值（planner、architect、researcher 固定为gpt-6-astra）
3. 特殊角色逻辑（如executor走 main/frontier 通道）
4. modelClass路由：fast用 spark/低复杂度通道，frontier用 main/frontier 通道，standard用 standard 通道

按通道的默认模型——env提供回退值，但 shell 环境变量永远胜出。各通道的解析顺序：

• Main/frontier 默认：shellOMX_DEFAULT_FRONTIER_MODEL→ 配置文件env.OMX_DEFAULT_FRONTIER_MODEL→ Codexconfig.toml根model→ 内置gpt-6-astra
• Standard 通道：shellOMX_DEFAULT_STANDARD_MODEL→env.OMX_DEFAULT_STANDARD_MODEL→ main/frontier 默认（即不设 standard 覆盖时，standard 角色直接继承 frontier 模型）
• Spark/快车道：shellOMX_DEFAULT_SPARK_MODEL→ shell 旧键OMX_SPARK_MODEL→env.OMX_DEFAULT_SPARK_MODEL→env旧键 →models.team_low_complexity（含team-low-complexity、teamLowComplexity两个别名）→ 内置gpt-6-astra
• 按 mode 查询（getModelForMode(mode)）：models[mode]→models.default→ main/frontier 默认

env支持的模型相关键为：OMX_DEFAULT_FRONTIER_MODEL、OMX_DEFAULT_STANDARD_MODEL、OMX_DEFAULT_SPARK_MODEL、旧键OMX_SPARK_MODEL（新配置建议用前者）、OMX_TEAM_CHILD_MODEL（部分 team 子模型路径直接读取）。env里其他非空字符串值会原样透传给omx explore、omx sparkshell等启动辅助，属于高级环境覆盖，不是按角色路由的 schema。

不要发明的键：文档明确警告，除非你安装的版本明确支持，不要写models.executor、models.architect、models.roles这类按角色模型映射。当前按角色路由的表面就是agentModels。同理，根级model_reasoning_effort不走.omx-config.json，它由omx reasoning <low|medium|high|xhigh>编辑 Codex 根配置；agentReasoning只管按 agent 覆盖。

写配置：agentModels、agentReasoning 与 env 示例

agentModels是受支持的按 agent 模型覆盖映射。键是规范化后的 OMX agent 名（字母、数字、下划线、连字符，大小写不敏感），值必须是非空字符串；格式错误的键、空值或非字符串值会被忽略而不是报错，同文件中其他有效条目继续生效。

文档给出的示例是把四个角色从 Astra 默认切到 GPT-5.6 系列：

{ "agentModels": { "architect": "gpt-5.6-sol", "planner": "gpt-5.6-sol", "researcher": "gpt-5.6-terra", "explore": "gpt-5.6-luna" } }

这些覆盖不会改动源码内置默认，只在 OMX 解析生成式 native agent TOML、AGENTS.md 模型能力表、以及 role-based team/Ralph 回退模型选择时生效。这些值属于用户/项目配置，不是对内置行为的修改。

agentReasoning是按 agent 的推理强度覆盖映射，值会被规范化为low、medium、high、xhigh、max五个之一：

{ "agentReasoning": { "architect": "MAX", "critic": "xhigh" } }

关于max有两点限制必须知道：它会被原样写入生成的 native agent TOML 和 Team 角色默认值，但能否实际生效取决于已安装 Codex 版本、所选模型和 provider 的能力；OmX 不会探测能力、不会自动降级为xhigh、也不会隐藏下游错误。ultra在 OmX 自有的agentReasoning表面不受支持，也不是max的别名；非法值会被忽略，该角色保持内置回退不变。

如果想整体调通道默认模型而不是按角色点名，用env加models。文档提供的“省钱起步配置”示例（编排走 Sol、standard worker 走 Terra、探索/低复杂度走 Luna）：

{ "env": { "OMX_DEFAULT_FRONTIER_MODEL": "gpt-5.6-sol", "OMX_DEFAULT_STANDARD_MODEL": "gpt-5.6-terra", "OMX_DEFAULT_SPARK_MODEL": "gpt-5.6-luna" }, "models": { "default": "gpt-5.6-terra", "team": "gpt-5.6-sol", "team_low_complexity": "gpt-5.6-luna" } }

注意models各值同样必须是非空字符串；内置 frontier/standard/spark 默认（含快 agent 和低复杂度 worker）当前都是gpt-6-astra，已知别名列表包含gpt-6-astra和可配置的 GPT-5.6 系列gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna；gpt-5.5等旧代名称只是透传的不透明字符串，没有特殊路由含义。

重新生成并验证生效

改完.omx-config.json后，agentModels和agentReasoning的覆盖要重新生成 setup 管理的 native agent TOML 才会落到文件里。在与实际启动 OmX 相同的 shell 和项目形态下执行：

omx setup --force omx doctor

omx setup --force会重新生成 setup 管理的 native agent TOML 和 AGENTS.md 管理段（文档要求在这两个映射变更后重跑）。omx doctor报告解析出的 setup scope、Codex home、config 路径、hook 覆盖、prompt/skill/agent 可用性，以及选定的 prompt 路由状态——它验证的是安装接线和“OmX 正在检查哪棵配置树”。

绿色omx doctor不等于当前 Codex profile 能认证并运行所选模型。要验证这一点，用同一个 shell/profile/project 执行：

codex login status omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

omx exec那条会实际发起一次模型调用，输出恰好为OMX-EXEC-OK（文档给出的示例指令）说明链路可用。

行为不符合预期时的检查边界

文档列出的排查起点只有一个：先确认你处于 user scope 还是 project scope，以及CODEX_HOME是否覆盖了预期 Codex home。这是“行为与配置不符”时的第一检查项，而不是自行添加的通用排错流程。

另外有两个文档明确指出的优先级陷阱：

1. config.toml根model会压过env的 frontier 覆盖。生成 frontier 角色（以及executor特例）的 native agent TOML 时，先读激活 Codexconfig.toml的根model，再回退到getMainDefaultModel()。因此env.OMX_DEFAULT_FRONTIER_MODEL不能覆盖显式写在config.toml根部的model。如果你要把已有配置整体迁到某个模型，需要把那个根model也一并改掉。
2. Team worker 启动还有一层。OMX_TEAM_WORKER_LAUNCH_ARGS内显式--model ...胜出；其次可继承 leader 的启动模型参数；都没有时按角色 modelClass 选回退模型，explore等快角色及以-low结尾的角色名走低复杂度/spark 回退。

运行中的团队需要查看模型检查提示时，用omx team status <team-name> --model-inspect；普通 status 路径不会为摘要消耗模型配额。

想继续了解各角色的完整键形（notifications、wiki、promptRouting 等与模型路由无关的顶层键），回到 omx-config-schema-routing.md 的“Supported top-level keys”一节即可。

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex