opencodex 模型排序机制全解：Codex 模型选择器的优先级排序原理、配置与源码级验证

【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载opencodex 作为 OpenAI Codex 与 Claude Code 的通用 provider 代理其核心体验之一就是 Codex 模型选择器model picker中模型的排列顺序。本文基于devlog/_fin/260711_model_ordering_docs/文档单元计划文档、交付报告及其产出官方指南完整讲解 opencodex 如何决定选择器顺序Codex 按priority升序排序、数组顺序无效、同优先级平局如何打破、subagentModels的 5 槽位上限与spawn_agent的联动、可见性过滤与排序的分离以及modelPickerOrder与仪表盘排序预设的用法。读完本文你将能精确解释为什么我的模型以这种顺序出现在选择器中并能通过配置完全掌控它。一、为什么需要单独解释排序被遗漏的三个用户面260711文档单元的背景是Codex 模型选择器的排序逻辑基于优先级的目录排序早已完整实现但没有任何面向用户的文档。当时有三个表面缺少说明docs-site 文档站没有任何文章解释为什么选择器按这个顺序展示模型GUI Subagents子代理页用户选择的顺序静默决定了选择器顶部 1~5 位优先级 0..4但页面从未说明这一点GUI Models模型标签页展示了模型列表却没有说明实际的排序规则子代理选中的排最前然后是 provider/模型 id 字母序最后是原生模型。该单元为这三个表面补充了说明并在 交付报告 中记录了验证结果docs-site 构建通过52 页en/ko/zh-cn 三个 locale 均渲染出页面GUI 构建通过英文文案与 目录源码 及 服务端源码 逐条核对一致。二、Codex 的排序铁律priority 升序数组顺序一律丢弃理解 opencodex 排序逻辑的第一原则是Codex 的 models-manager 按目录条目的priority字段升序排序并丢弃目录数组本身的顺序。也就是说在生成的 JSON 数组中把一个条目往前移动并不会让它在选择器里靠前。这条约束被直接记录在 build-entries.ts 的实现注释中// Codexs models-manager sorts by priority ASC and advertises the first 5 picker-visible // models to spawn_agent (sort_by_key(priority) MAX_MODEL_OVERRIDES_IN_SPAWN_AGENT5). Catalog // ARRAY order is discarded — so featuring a model giving it the LOWEST priority (0..N-1) so // it sorts to the front. This works for native gpt slugs AND routed slugs alike.因此 opencodex通过赋予更低的 priority 来控制置顶featured位置而不是依赖数组位置。priority数值越小在升序排序中越靠前。注意000_plan.md中引用的src/codex/catalog.ts行号如 881、885、887、892、1227、1269、1313、1348对应的是目录模块拆分前的代码当前仓库中src/codex/catalog.ts已重构为自动拆分门面catalog.ts真实实现位于 src/codex/catalog/ 子模块中下文均引用当前实际路径。三、核心优先级表四个槽位决定选择器骨架在没有符合条件的 Codex 账户选择器account selectors时opencodex 产生的有效优先级如下这是 000_plan.md 中Verified facts表格的完整继承并对应到当前源码目录条目优先级源码位置subagentModels[i]最多 5 个i0到4featured 排序表build-entries.ts其他路由模型routed5路由条目创建build-entries.ts原生 GPT slug默认9原生条目创建build-entries.ts存在 featured 列表时未被选中的原生模型至少featured.length 100原生目录合并build-entries.ts账户选择器存在时优先级步长stride机制上面的表格默认没有符合条件的账户选择器。当存在N个符合条件的 selector 时featured 优先级使用N作为步长stride见 build-entries.ts 的priorityStride Math.max(accountSelectors.length, 1)裸原生选择如gpt-5.5在配置的排名i处会展开为 selector 行优先级为i * N jj为 selector 的零基位置路由选择如opencode-go/glm-5.2使用i * N精确 selector 限定选择如selector/native-openai-model对其 selector 使用i * N j。未选中的路由行会被移出这些 selector 分组之外1_000 自然优先级见 build-entries.ts。Codex 依然只向前五个可见行做spawn_agent广告。四、同优先级平局provider/id 字母序 稳定排序大多数普通路由模型优先级都是5因此需要确定性平局规则。在目录条目构建之前gatherRoutedModels()会对路由模型列表按provider 名、再按模型 id做字母序排序两者均为字典序见 routed-gather.tsall.sort((a, b) (a.provider b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));这意味着以下两种配置写法都不会改变最终顺序providers对象中键的声明顺序某个 provider 的models数组中 id 的顺序。随后orderForSubagents()build-entries.ts使用稳定排序将配置的 featured 选择按subagentModels中的顺序移到最前export function orderForSubagents(goModels: CatalogModel[], featured?: string[]): CatalogModel[] { if (!featured || featured.length 0) return goModels; const rank new Map(featured.map((id, i) [id, i])); // Featured picks may be stored raw (legacy) or encoded — match both forms. const rankOf (m: CatalogModel) (m.alias ? rank.get(m.alias) : undefined) ?? rank.get(${m.provider}/${m.id}) ?? rank.get(routedSlug(m.provider, m.id)) ?? Number.MAX_SAFE_INTEGER; return [...goModels].sort((a, b) rankOf(a) - rankOf(b)); }未选中的模型保持此前建立好的 provider/id 字母相对顺序。featured 排名在条目构建时转换为0..4的优先级使 Codex 的 priority 排序保留这段前置序列。五、5 槽位上限subagentModels 与 spawn_agent 的联动subagentModels最多容纳 5 个 id。管理 API 用slice(0, 5)强制这一上限见 agent-settings-routes.tschosen body.models.slice(0, 5);这与 Codex 的spawn_agent表面一致——它只广告前 5 个模型覆盖。上限常量定义在 subagent-roster.tsexport const MAX_SPAWN_AGENT_MODEL_OVERRIDES 5;这 5 个之外的模型仍可在主选择器中可见、并可通过精确 id 调用——它们只是不在spawn_agent的默认候选列表里。六、可见性 ≠ 排序selectedModels / disabledModels 只是过滤器selectedModels与disabledModels决定哪些路由模型被暴露它们不是排序控制项。filterCatalogVisibleModels()model-visibility.ts把两者都转换为Set进行查询const disabled new Set(config.disabledModels ?? []); // ... if (Array.isArray(sel) sel.length 0) { allowByProvider.set(name, new Set(sel.map(model slugEquivalenceKey(routedSlug(name, model))))); }随后直接对模型列表做过滤models.filter(...)完全不把数组当作排名使用。因此重新排列selectedModels或disabledModels中的顺序不会改变选择器位置——它们只能决定一个模型是否被包含。另外值得注意可见性过滤用的是 Set 语义而非数组索引且通过slugEquivalenceKey做带损失性的键合并p/a/b与p/a-b折叠为同一项这是 model-visibility.ts 中注释明确记录的已知限制并被测试固定。七、有效选择器顺序模式Net Picker Order综合以上规则在无账户选择器 featured 列表非空时选择器的最终顺序为精确按配置的subagentModels顺序排列的模型优先级0..4其余所有路由模型按 provider 再按模型 id 字母序优先级5未选中的原生模型在目录合并时被压到 featured 块之后。没有subagentModels时路由模型保持优先级5provider/id 字母序原生 GPT 条目使用正常优先级opencodex 构建的条目通常为9路由组仍保持 provider/id 字母序。八、完整示例一张表看懂选择器假设subagentModels按以下精确顺序包含 5 个 idsubagentModels [ gpt-5.5, opencode-go/glm-5.2, anthropic/claude-opus-4-6, gpt-5.6-sol, gpt-5.6-terra, ]选择器开头将呈现为位置模型优先级出现在此的原因1gpt-5.50第一个subagentModels选择2opencode-go/glm-5.21第二个选择尽管其 provider 字母序排在anthropic之后3anthropic/claude-opus-4-62第三个选择4gpt-5.6-sol3第四个选择5gpt-5.6-terra4第五个选择6anthropic/claude-fable-55provider/id 字母序中剩余的第一个路由 id7 起其余路由模型5先 provider 字母序再模型 id 字母序路由之后其余原生模型featured.length 100或更高未选中的原生模型被移到 featured 块之后前 5 个条目正是向spawn_agent广告的覆盖其余继续按正常选择器顺序。有账户选择器时5 条限制适用于裸原生选择展开为 selector 限定组之后。九、modelPickerOrder仅显示层排序与迁移注意subagentModels同时决定 featured 排序与spawn_agent候选而modelPickerOrder是仅显示层display-only的排序它只重写被列出路由行的 Codex 可见priority不影响 OpenCodex 自身的自然优先级指导候选。路由-only 列表{ modelPickerOrder: [ tyler/deepseek-v4-flash, jd-chat/kimi-k3, jd-chat/glm-5.2 ] }被列出的路由行按配置顺序出现位于PICKER_ORDER_PRIORITY_BASE1_000定义于 subagent-roster.ts之上的高优先级显示带未列出的路由行保留自然优先级5所以仍排在modelPickerOrder显示带之前——想控制相对位置就必须把每个相关路由行都列出。同时出现在subagentModels中的行保持 featured 优先级纯路由列表下原生行保持正常位置。完整排序加入裸原生 id{ modelPickerOrder: [gpt-5.6-sol, opencode-go/glm-5.3] }列出的行按数组顺序最先出现未列出的行按自然优先级跟随。匹配使用精确目录 idgpt-5.6-sol与openai/gpt-5.6-sol是不同行同一路由 id 的 raw 与编码拼写都接受精确匹配优先空条目被忽略账户限定行需要在列表中写 selector 限定 id。迁移注意现有排序中的原生 id此前modelPickerOrder中的原生 id 会被忽略。现在只要列表中出现裸原生 id 就激活完整选择器排序包括 featured 行。要保留旧的纯路由行为请移除裸原生 id。未设置、空列表、纯路由列表都保持原有行为OpenCodex 的自然优先级指导候选计算不变。modelPickerOrder通过SPAWN_PRIORITY_FIELDsubagent-roster.ts 中定义的 OpenCodex 私有目录字段单独保留每个移动行的自然优先级仅改显示顺序不会改变 OpenCodex 对最多 5 个首选候选的计算。它也不限制精确名称模型覆盖的资格——原生广告列表不是允许名单既有的认证、模型/effort 与后端约束仍然适用。原生 Codex 在 V1 以及 V2 暴露模型覆盖时会使用原生priority选择前 5 个可被spawn_agent广告的模型因此广告的 5 个可能随显示顺序变化V1 不接收 OpenCodex 首选名册注入。十、Dashboard 排序预设Models 页的排序控制在 GUI 的Models页可选用Default默认、A–Z by model按模型 A–Z、Group by provider按 provider 分组、Most used snapshot常用快照之一并点击Apply order应用排序。这会保存当前可见的路由 id 与modelPickerOrderModealphabetical、provider或most-used。Most used在应用时读取一次全部留存用量重载恢复快照而不再重新拉取新增或移除的模型不会自动重算。Default 会清空两个 picker 字段即使没有可用路由模型。这些控件通过GET/PUT /api/subagent-models工作chosen与available保留已保存的名册选择包括禁用或缺失的模型pickerAvailable只含符合条件的路由目录 id。Models 页只发送pickerOrder与pickerOrderMode从不发送models纯名册保存会保留 picker 设置。路由-only 预设保持现有 featured/原生优先级带保存不重启客户端目录刷新可能仍待处理持有旧目录的客户端可能需要重新打开。Custom order自定义排序会加载一份新的路由快照拖拽或使用 Up/Down 按钮调整可移动行后Save draft。featured 路由行保持在其配置排名的最前且不可移动原生行不显示这不是完整原生选择器的预览。包含裸原生 id 的排序在显式应用路由预设或 Default 之前受保护编辑前检查新快照未知 featured 状态会阻止编辑请求失败保留草稿保存前必须确保每个路由候选有明确的模型身份目录不完整时先刷新 Models 页。十一、GUI 页面的顺序提示Subagents / Models为了兑现在每个用户面解释排序的目标GUI 增加了两处提示Subagents 页SubagentsWorkspace.tsx 在 Featured 列表上方加入sub.orderHint提示行IconInfo 行说明这里选择并显示的顺序决定 Codex 模型选择器顶部 1~5 位以及spawn_agent的默认模型候选Models 页模型列表上方加入models.orderHint说明文字解释默认顺序遵循 featured 选择与目录优先级、同优先级路由模型按 provider/模型排序、已保存的 picker 顺序可覆盖显示顺序、可见性开关只过滤行。两个文案均通过 i18n 键提供多语言版本例如 en.ts 的models.orderHint与 en.ts 的sub.orderHint/sub.orderHintAria并扩展至 ko/zh/de当前仓库已进一步覆盖 fr/ja/ru。十二、诚实的边界目前没有 modelOrder / providerOrder 配置000_plan.md 明确将新增配置字段排除在范围之外当前不存在modelOrder、providerOrder或优先级映射priority-map配置。文档描述的是今天的行为及其限制——排序完全由subagentModelsfeatured、modelPickerOrder显示层与内置优先级规则驱动。报告 010_report.md 也将通用modelOrder配置列为可能的未来单元候选触点记录在计划与文档中。十三、源码速查表结论证据文件Codex 按 priority 升序、丢弃数组顺序build-entries.tsfeatured 排名表与 stridebuild-entries.ts原生条目默认 priority 9build-entries.ts路由条目默认 priority 5build-entries.ts未选中原生行压到featured.length 100build-entries.ts平局provider/id 字母序routed-gather.tsfeatured 稳定排序到最前build-entries.ts5 槽位上限subagent-roster.ts、agent-settings-routes.ts可见性过滤Set 语义model-visibility.ts显示层排序基准 1000subagent-roster.ts多语言官方指南guides/model-ordering.md 及 ko、zh-cnGUI 顺序提示文案en.ts、SubagentsWorkspace.tsx简言之想让某个模型置顶就把它放进subagentModels的前 5 位想微调 featured 块之后的路由行显示顺序用modelPickerOrder想改变可见性用selectedModels/disabledModels——但永远记住Codex 只认priority数组顺序只是幻觉。赞分享【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载相关推荐opencodex 模型排序完全指南Codex Picker 顺序规则、优先级表与实战配置opencodex 模型排序完全指南Codex Picker 顺序规则、优先级表与实战配置 本文深入讲解 opencodexUniversal providReact调度器终极指南揭秘Lane模型与优先级排序的核心原理React调度器终极指南揭秘Lane模型与优先级排序的核心原理 React调度器是React运行时的核心组件它负责管理任务的执行顺序和优先级确保应用在处理教程前端AutoRAG 中 ColBERT 重排序模块colbert_reranker的配置与源码级原理详解AutoRAG 中 ColBERT 重排序模块colbert_reranker的配置与源码级原理详解 AutoRAG 的 colbert_reranker人工智能AI AgentRAG本地部署CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考