Codex 目录推理等级钳制（Catalog Clamp）调查：max/ultra 被剥离的条件性缺陷与修复路径

【免费下载链接】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 仓库开发日志 002_investigation_297_catalog_clamp.md 展开深入剖析 issue #297 所述的catalog 钳制clamp在所有模型上剥离max/ultra推理等级问题的机制、证据与修复选项。读完本文你将掌握 opencodex 如何探测已安装 Codex 二进制的推理等级词汇表、如何对最终落盘目录执行全局钳制以及为何该机制被证明为真、当前触发器却无法在本地复现并理解条件性修复方案版本门控 Option B的设计约束。问题背景issue #297 的指控2026-07-23 的 issue #297 提出如下指控bug(catalog): clamp in b7ce5aad strips max/ultra from all models regardless of Codex binary version.即引入钳制逻辑的提交b7ce5aad会不论 Codex 二进制版本如何从所有模型目录条目中剥离max与ultra推理等级。这直接威胁到 opencodex 在 GPT-5.6 时代推广的六档推理等级low/medium/high/xhigh/max/ultra——尤其是路由模型如openrouter/...、anthropic/...与 GPT-5.6 原生模型的顶级档位。调查结论在codex/issue-triage-260723分支54e0bbf88cebe6a77e0a8584af193cf689680ad6上完成与当时的origin/dev一致分为两半机制Mechanism被证实目录级全局钳制会从一个全局集合出发过滤所有已发射模型含路由模型因此确实可以撤销此前 ensure 函数追加的max/ultra当前触发器Trigger未被证实在本地安装的codex-cli 0.144.5上捆绑目录自带全部六个档位钳制不会剥离任何东西问题无法复现。一、机制确认探测函数如何推导支持的档位集合1.1 扫描范围所有无/的裸 slugcodexSupportedReasoningEfforts是整条钳制链的源头。它加载已安装二进制的捆绑目录遍历所有slug为不含/的字符串的模型行即原生/裸 slug把每个模型supported_reasoning_levels[].effort与default_reasoning_level的字符串值全部并入一个Set仅当并集为空时返回null。该探测中不存在硬编码的原生 slug 白名单。// src/codex/catalog/effort.ts:349-368当前源码 export function supportedCodexReasoningEffortsFromObservedCatalog( catalog: ReadonlyRawCatalog | null, ): ReadonlySetstring | null { if (!catalog) return null; const efforts new Setstring(); for (const model of catalog.models ?? []) { if (typeof model.slug ! string || model.slug.includes(/)) continue; const levels Array.isArray(model.supported_reasoning_levels) ? model.supported_reasoning_levels : []; for (const level of levels) { const effort (level as { effort?: unknown })?.effort; if (typeof effort string) efforts.add(effort); } if (typeof model.default_reasoning_level string) efforts.add(model.default_reasoning_level); } return efforts.size 0 ? efforts : null; } export function codexSupportedReasoningEfforts(deps: BundledCatalogDeps {}): ReadonlySetstring | null { return supportedCodexReasoningEffortsFromObservedCatalog(loadBundledCodexCatalog(deps)); }关键语义如果某个 Codex 版本的捆绑目录中裸 slug 行恰好没有声明max/ultra那么这个全局集合就只到xhigh后续一切包含max/ultra的条目都会被判定为该二进制无法反序列化而剥离。1.2 生产环境如何拿到捆绑目录生产探测通过调用codex debug models --bundled获取目录 JSON要求解析成功**且包含原生模板native template**才算数多个命令候选依次尝试首次成功即返回// src/codex/catalog/bundled.ts:220-237 export function runCodexDebugModels( command: string, execFile: ExecFile, deps: PickBundledCatalogDeps, env | platform | existsSync {}, ): string { const args [debug, models, --bundled]; const invocation codexExecInvocation(command, args, deps.platform ?? process.platform, { env: deps.env, exists: deps.existsSync, }); return execFile(invocation.file, invocation.args, { encoding: utf8 as const, stdio: [ignore, pipe, ignore] as [ignore, pipe, ignore], timeout: 10_000, windowsHide: true, ...invocation.options, }); }候选命令的来源codexCommandCandidatesbundled.ts依次包括环境变量CODEX_CLI_PATH指定的路径若设置、codex-shim.json记录的包装器/原路径/备份路径codexShimCommandCandidates、Windows 下 PATH 中的codex.exe/codex.cmd最后兜底codex。loadBundledCodexCatalogbundled.ts在无注入依赖时优先使用单一已解析运行时resolveAndPersistCodexRuntime的 command 作为唯一候选保证钳制探测与 OpenCodex 实际启动的二进制是同一个结果按BUNDLED_CATALOG_CACHE_MS 60_0001 分钟进程内缓存。1.3 本地只读运行证据0.144.5调查机器上该命令路径解析为/Users/jun/.nvm/versions/node/v24.17.0/bin/codex无CODEX_CLI_PATH覆盖、无 shim 状态候选。实测输出$ codex --version codex-cli 0.144.5 $ codex debug models --bundled | jq bare-slug projection and effort union gpt-5.6-sol low medium high xhigh max ultra gpt-5.6-terra low medium high xhigh max ultra gpt-5.6-luna low medium high xhigh max gpt-5.5 low medium high xhigh gpt-5.4 low medium high xhigh gpt-5.4-mini low medium high xhigh gpt-5.2 low medium high xhigh codex-auto-review low medium high xhigh union low medium high xhigh max ultra即当前被扫描的裸 slug 恰好是上面 8 行推导出的集合是{low, medium, high, xhigh, max, ultra}。报告者提出的当前二进制上集合只到xhigh的触发器对本地 0.144.5 为假但单次观测并不能证明所有已发布版本或 Desktop 内置版本的捆绑目录都如此。二、机制确认条目级钳制如何剥离档位2.1 保留/兜底/默认修复三规则给定非空 supported 集合clampEntryToCodexSupportedEfforts对单条目执行三件事保留过滤仅保留effort字符串在 supported 集合中的档位兜底若一个都不剩替换为通用low/medium/high三档而非保留无法解析的阶梯默认修复若默认档不受支持则取存活档位中不高于原始档位排名的最高者空存活列表回退medium。// src/codex/catalog/effort.ts:384-434当前源码节选 export function clampEntryToCodexSupportedEfforts( entry: RawEntry, supported: ReadonlySetstring | null, ): void { if (!supported) return; const levels Array.isArray(entry.supported_reasoning_levels) ? entry.supported_reasoning_levels as Array{ effort?: string } : null; if (levels levels.length 0) { const kept levels.filter(level typeof level?.effort string (supported.has(level.effort) || UNCLAMPABLE_REASONING_EFFORTS.has(level.effort))); ... entry.supported_reasoning_levels kept.length 0 ? kept : CODEX_REASONING_LEVELS .filter(level level.effort low || level.effort medium || level.effort high) .map(level ({ ...level })); } ... }需要指出的是当前仓库源码与调查时的实现已有演进现版在保留过滤时加入了UNCLAMPABLE_REASONING_EFFORTSmax/ultra白名单豁免见 effort.ts 注释per the unconditional-emission ruling并对保留条目reserve行做了requiresExactReserveEfforts分支。这体现了后续版本对本文调查结论的落地——但机制本身用全局集合过滤每条目与调查时一致。2.2 目录级钳制对所有条目无差别套用clampCatalogModelsToCodexSupport把同一个全局集合应用到每一个模型而不检查该 slug 是原生还是路由。因此若 supported 集合止于xhighopenrouter/example、anthropic/...、GPT-5.6 等一切带推理能力的条目都会被剥掉max/ultra。这也正是 issue #297 指控的核心路由模型本应由其适配器自行映射档位却被目录钳制越俎代庖。// src/codex/catalog/effort.ts:541-600当前源码节选 export function clampCatalogModelsToCodexSupport(models: RawEntry[], deps: BundledCatalogDeps {}): RawEntry[] { const supported codexSupportedReasoningEfforts(deps); if (!supported) { if (!deps.commandCandidates) persistEffortClamp(null, { configDir: deps.configDir }); return models; } const clamp clampCatalogModelsToObservedCodexSupport(models, supported); ... }现版还会在发生剥离时输出运行日志行formatClampLogLines并持久化EffortClampDiagnosticruntimePath、runtimeVersion、removedEfforts、affectedModels这是调查后新增的可观测性设施见 runtime 相关代码。2.3 在 sync 路径中的最后一棒位置syncCatalogModels在mergeCatalogEntriesForSync完成之后才调用目录级钳制随后立即atomicWriteFile写入。也就是说钳制是同步路径上对最终落盘目录的最后一次模型变更完全可以删除前面构建器刚追加的档位// src/codex/catalog.ts:2200-2208调查时行号逻辑沿用至 catalog/sync.ts const wsEnabled websocketsEnabled(config); catalog.models mergeCatalogEntriesForSync(catalog.models ?? [], goEntries, baseline, featured, wsEnabled, goIds, template, disabledNativeSlugs(config), gatheredProviderNames, multiAgentMode, exactComboSlugs, hasPhysicalComboProvider); clampCatalogModelsToCodexSupport(catalog.models); atomicWriteFile(catalogPath, JSON.stringify(catalog, null, 2) \n); return { added: goEntries.length, path: catalogPath };三、机制冲突ensure 函数先追加、钳制后剥离3.1 两个 ensure 函数显式追加顶级档位GPT-5.6 兜底函数ensureGpt56ReasoningLevels明确追加max真实原生档位与ultra始终广告旧原生辅助函数ensureUltraReasoningLevel在存在阶梯时同样追加两者// src/codex/catalog/effort.ts:314-346当前源码 export function ensureGpt56ReasoningLevels(entry: RawEntry): void { const levels ...; const out [...levels]; // max is a real native rung on the 5.6 family — always restored. ultra is advertised unless // the slugs pinned ladder (or its sources) stops short of it, as gpt-6-lunas does. const wanted typeof entry.slug string !nativeLadderIncludesUltra(entry.slug) ? [max] : [max, ultra]; for (const effort of wanted) { if (out.some(level level.effort effort)) continue; out.push(CODEX_REASONING_LEVELS.find(level level.effort effort) ?? { effort, description: ${effort} reasoning }); } entry.supported_reasoning_levels out; } export function ensureUltraReasoningLevel(entry: RawEntry): void { const levels ...; if (levels.length 0) return; const wanted [max, ultra]; ... }这些辅助函数在目录构建/合并路径中运行——原生条目推导返回前、或保留的旧原生条目在合并数组返回前都会先调用它们。于是同一条目的max/ultra可能被先加后删。3.2 路由条目的档位由谁负责路由命名空间条目走的是另一条路applyReasoningLevelseffort.ts为推理能力路由模型广告max/ultra除非该模型 opt-out 合成顶级档这是用户决策 260709mock top tiers的延续。因此路由条目的max/ultra是合成广告其真值映射发生在请求期见下文nativeEffortClamp与mapReasoningEffort而目录钳制并不区分广告与真值一律过滤。四、测试证据证明机制而非证明今日触发器仓库中钳制测试位于 tests/codex-integration/codex-catalog.test.ts调查记录写的是tests/codex-catalog.test.ts现已随测试布局迁移。其捆绑目录是依赖注入的 JSON 固定数据只含一个裸gpt-5.5并非从已安装二进制捕获的真实输出// tests/codex-integration/codex-catalog.test.ts:7110-7125当前源码 function bundledCatalogDeps(efforts: string[]) { return { commandCandidates: () [codex], execFileSync: () JSON.stringify({ models: [{ slug: gpt-5.5, base_instructions: test, supported_reasoning_levels: efforts.map(effort ({ effort, description: effort })), default_reasoning_level: medium, }], }), }; }两个分支测试分别证明剥离分支注入的探测集合止于xhigh时路由条目openrouter/example六档 默认max被裁剪为四档保留分支注入六档集合时六档被完整保留。// tests/codex-integration/codex-catalog.test.ts:7160-7195当前源码 test(strips max and ultra when the installed Codex ladder stops at xhigh, () { const models [routedEntry()]; clampCatalogModelsToCodexSupport(models, bundledCatalogDeps([low, medium, high, xhigh])); expect(models[0]!.supported_reasoning_levels.map(level level.effort)) .toEqual([low, medium, high, xhigh]); }); test(preserves max and ultra when the installed Codex ladder includes them, () { const models [routedEntry()]; clampCatalogModelsToCodexSupport(models, bundledCatalogDeps([low, medium, high, xhigh, max, ultra])); expect(models[0]!.supported_reasoning_levels.map(level level.effort)) .toEqual([low, medium, high, xhigh, max, ultra]); });结论测试无条件支持机制声明 (a)而对特定二进制触发声明 (b)测试并不覆盖仍需直接拿到二进制输出才能验证。五、回归提交的意图保护严格枚举解析器git show b7ce5aad --stat显示该提交改动 1 个运行时文件与 2 个测试文件src/codex/catalog.ts63 行、tests/codex-catalog.test.ts74 行、tests/google-models-listing.test.ts2 行136 插入、3 删除。提交信息原文fix(codex): clamp catalog reasoning efforts to installed binarys ladder Adopts the approach from PR #223 by Bricol1982 with safe-fallback improvements: when ALL efforts are unsupported, fall back to universal [low,medium,high] instead of preserving the unsupported ladder. Prevents Codex 0.133.0 catalog parse failure.背景事实链Codex 0.133.0 的目录解析器对未知枚举值max/ultra会直接解析失败且失败发生在任何请求到达 OpenCodex 原生/路由 wire 钳制逻辑之前。因此该钳制的存在是为了兼容性安全——但兼容性边界必须精确只该对真正无法反序列化这些档位的二进制生效。六、三个修复选项的评估Option A从CODEX_REASONING_LEVELS常量播种 supported 集合六档常量定义于 src/reasoning-effort.ts描述与上游捆绑models.json官方措辞一致对应 openai/codex PR #31684export const CODEX_REASONING_LEVELS: { effort: string; description: string }[] [ { effort: low, description: Fast responses with lighter reasoning }, { effort: medium, description: Balances speed and reasoning depth for everyday tasks }, { effort: high, description: Greater reasoning depth for complex problems }, { effort: xhigh, description: Extra high reasoning depth for complex problems }, { effort: max, description: Maximum reasoning depth for the hardest problems }, { effort: ultra, description: Maximum reasoning with automatic task delegation }, ];判定拒绝。播种全部已知标签会把兼容性钳制变成对正是导致 0.133.0 崩溃的那两个标签的 no-op。请求期nativeEffortClamp无法弥补因为它在请求到达后才触发且明确区分原生 wire 行为与路由适配器映射——目录解析失败发生在请求之前wire 钳制鞭长莫及。Option B对目录钳制做版本门控conditional 推荐门控可对已知严格枚举的二进制保留xhigh上限同时允许已被证明能反序列化这些档位、但捆绑原生行恰好未声明它们的版本保留标签。这是唯一既能保住原兼容性边界、又能处理真实解析器/目录错配的选项。约束要点调查原文强调解析器接受阈值必须由真实二进制矩阵确立0.133.0已知严格本地0.144.5声明全六档但首个接受版本尚未确定实现必须探测与捆绑目录同源的同一个命令候选的版本。当前loadBundledCodexCatalog内部循环候选并只返回解析后的目录若独立探测codex --version可能门控到另一套安装多安装候选错配。// src/codex/catalog/bundled.ts:239-303当前源码候选循环主体 for (const command of unique(candidates)) { try { const catalog parseCatalogJson(runCodexDebugModels(command, execFile, deps)); if (catalog findNativeTemplate(catalog)) { if (useCache cacheKey) { publishBundledCatalogCache(cacheKey, Date.now() BUNDLED_CATALOG_CACHE_MS, catalog); return cloneAndDeepFreeze(bundledCatalogCache!.value!); } return cloneAndDeepFreeze(catalog); } } catch { /* try next candidate */ } }与nativeEffortClamp的交互是干净的版本门控只控制目录反序列化兼容性客户端能接受max/ultra之后旧阶梯原生请求仍被裁剪到快照中的最高真实档位路由请求仍归各 provider 的映射表/适配器管。// src/codex/catalog/effort.ts:52-75当前源码节选 export function nativeEffortClamp(slug: string, effort: string | undefined): string | null { if (!effort || (effort ! max effort ! ultra)) return null; if (slug.includes(/)) return null; // routed models map efforts in their adapters const entry UPSTREAM_NATIVE_ENTRIES.get(slug); ... return highest ?? null; }路由侧由 src/reasoning-effort.ts 的mapReasoningEffort独立负责先执行ultra - max边界转换与上游 codex-rs 的reasoning_effort_for_request一致再应用 provider 别名映射最后按配置的支持档位钳制得到 wire 值。Option C把 ensure 函数移到钳制之后运行判定拒绝。ensure 函数是原生条目辅助函数不是通用的路由模型恢复通道。路由条目由applyReasoningLevels负责见 effort.tsensure 函数只出现在原生分支因此简单移动/重跑它们并不能为报告中所有路由 provider 恢复max/ultra。且回归风险高在兼容性边界之后重新加标签等于把未知枚举变体重新送给旧的严格客户端——wire 钳制无法阻止发生在请求之前的目录解析失败。若把 Option C 扩展成钳制后全量恢复本质上就是在更晚的代码行重演 Option A并保留同样的安全性缺陷。七、任何代码变更前的强制验证清单获取报告者的精确codex --version、可执行文件路径与codex debug models --bundled裸 slug 档位并集演示错配条件客户端能成功解析含max/ultra的最小目录而自身捆绑裸条目并集缺其一或全部若走 Option B用二进制矩阵确定首个解析器兼容版本矩阵至少覆盖已知严格的0.133.0、阈值的前一版本、阈值本身以及当前 CLI/Desktop 候选新增把版本与目录探测结果绑定到同一命令候选的测试并保留现有 synthetic strip / preserve / no-probe / fallback / default-repair 用例运行bun run typecheck、聚焦的 catalog/reasoning 测试以及完整bun run test最终发射边界全局影响原生与路由模型。八、结论与建议方向判定opencodex-bug —— 条件性成立今日所检二进制上未确认。全局剥离机制从源码与测试均可证明针对报告者的当前触发在本地codex-cli 0.144.5上被证伪且因报告未附精确版本与捆绑目录输出而无法进一步支撑。该行为对0.133.0这类解析器拒绝未知档位的二进制是正确且必要的。桶分类建议将 #297 从 Bucket 2立即调查降级为 Bucket 1答复 关闭 / 等待精确版本复现。回复应展示 0.144.5 的全六档并集并索取上述三个运行时工件仅当他们演示出解析器可解析 / 捆绑阶梯缺失的错配时才重新打开或恢复 Bucket 2。推荐方向条件性 Option B在缺少触发器证据前不做任何立即源码修改。若错配二进制被演示则用经验证的解析器接受阈值对钳制做版本门控并把版本/目录探测绑定到同一候选。不要使用 Option A 或 C两者都绕过了目录反序列化保护且 C 对路由条目还不完整。工作量评估在拿到可复现二进制/版本后约需0.51 个工程师日——代码改动应很小但确立阈值、防止多安装候选错配、添加二进制版本固定数据矩阵、跑通全横切面测试才是大头。若无错配证据剩余工作仅为一份有证据支撑的 issue 答复/关闭约 30 分钟零代码改动。延伸阅读完整调查记录002_investigation_297_catalog_clamp.md钳制与 ensure 实现src/codex/catalog/effort.ts捆绑目录探测与缓存src/codex/catalog/bundled.ts六档常量与路由映射src/reasoning-effort.ts钳制合成测试tests/codex-integration/codex-catalog.test.ts赞分享【免费下载链接】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 Reasoning Clamp 深度解析用观测到的 Codex 运行时推理等级校准模型目录修复 0.133.0 严格枚举破坏OpenCodex Reasoning Clamp 深度解析用观测到的 Codex 运行时推理等级校准模型目录修复 0.133.0 严格枚举破坏 本篇文章围drizzle-seed 0.1.2 缺陷修复解析reset() 运行时依赖剥离与 schema 类型兼容性drizzle seed 0.1.2 缺陷修复解析reset 运行时依赖剥离与 schema 类型兼容性 本文基于 drizzle seed 0.1.2 版本后端数据库ORMRabbitMQ 3.13.5 维护版本发布详解关键缺陷修复、对等发现改进与升级路径RabbitMQ 3.13.5 维护版本发布详解关键缺陷修复、对等发现改进与升级路径 导读 本文基于当前仓库中 RabbitMQ 3.13.5 的官方发布说明后端消息队列消息路由创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考