OpenCodex 多智能体（Multi-Agent）子代理契约详解：spawn_agent 模型选择、V1/V2 界面与目录引脚规则

【免费下载链接】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-rs 上游的研究笔记devlog_fin/260723_codexrs_realtime_subagent_devlog_sweep/系列整理而成聚焦 Codex 多智能体multi-agent/ 子代理subagent契约在 OpenCodex 中的落地spawn_agent可推荐模型的筛选规则、V1/V2 两套工具界面的差异、模型目录中multi_agent_version引脚pin的语义以及并发与生命周期相关的已知风险点。读完后你将能够解释 OpenCodex 为什么最多只向 Codex 推荐 5 个子代理模型、为什么某些模型在 V2 轮次下会被拒绝派生以及如何用ocx v2CLI 与config.toml控制这些行为。一、契约常量与默认配置研究笔记tip4462b9dee对应上游 PR #34887记录了本地 codex-rs 侧的核心常量与默认值OpenCodex 在源码中逐一对应实现。1.1MAX_SPAWN_AGENT_MODEL_OVERRIDES 5上游codex-rs/core/src/tools/handlers/multi_agents_common.rs定义了pub(crate) const MAX_SPAWN_AGENT_MODEL_OVERRIDES: usize 5;OpenCodex 在 subagent-roster.ts 中镜像了同一常量并在构造有效子代理名单时执行.slice(0, MAX_SPAWN_AGENT_MODEL_OVERRIDES)subagent-roster.ts保证与原生 Codex 的最多推荐 5 个模型行为一致。该常量经由 catalog.ts 的再导出进入目录同步链路catalog/sync.ts。1.2MultiAgentV2Config默认值来自上游codex-rs/core/src/config/mod.rs中MultiAgentV2Config的默认值配置项默认值说明hide_spawn_agent_metadatatrue隐藏 spawn 元数据expose_spawn_agent_model_overridestrue向模型暴露可用的模型 override 列表wait_agent_enabledtrue是否提供wait_agent工具max_concurrent_threads_per_session必填且 1每会话最大并发子代理线程数tip commit4462b9dee#34887新增的能力是把wait_agent与 sleep 工具独立地开启/关闭——在此之前二者是绑定的。OpenCodex 对其中max_concurrent_threads_per_session提供了完整的读写支持features.ts 中的readMultiAgentV2MaxThreads约 L353从config.toml解析[features.multi_agent_v2]表或内联表两种写法writeMultiAgentV2MaxThreads约 L411负责持久化并校验必须是 1 的整数。CLI 侧则由ocx v2 threads n驱动见 v2.ts 中pass an integer 1的报错分支。二、spawn 模型推荐Advertisement规则笔记概括的spawn_agent_models_description/find_spawn_agent_model_name三步筛选规则为过滤show_in_picker目录中visibility list的行过滤对当前multi_agent_version界面的后端支持按优先级取前 5 个take(MAX_SPAWN_AGENT_MODEL_OVERRIDES)。OpenCodex 中对应的实现是effectiveSubagentRostersubagent-roster.ts其流程比上游描述更细且对每个被剔除的模型给出可诊断的原因码configured 去重slugsEquivalent → 过滤 visibility list picker_hidden 之外的第一道闸 → surface v2 时过滤 V2 资格 isEligibleV2SubagentEntry → 按 spawn 优先级排序SPAWN_PRIORITY_FIELD 优先回退 priority再回退 index → slice(0, 5) → 输出 { candidates, advertised, excluded }excluded数组携带四种排除原因SubagentRosterExclusionReasonmissing_catalog_entry目录中不存在、picker_hidden存在但不可见、surface_incompatible界面不兼容如 V1 引脚行出现在 V2 轮次、outside_display_limit可见且兼容但排在第 5 名之后。这使得我配置了模型 X为什么没被推荐可以逐一定位而不是得到一个笼统的报错。关于排序优先级源码注释特别说明了 OpenCodex 的一个私有目录字段opencodex_spawn_prioritysubagent-roster.ts它记录未受modelPickerOrder影响时的自然优先级让 OpenCodex 的推荐窗口guidance window与纯展示用途的modelPickerOrder解耦——Codex 忽略未知目录字段因此该字段对原生 picker 完全不可见。2.1 reasoning effort 的严格校验笔记指出spawn 时指定的 reasoning effort 会对照所选模型的支持档位进行校验不支持的 effort 会硬失败hard-fail并返回该模型实际可用的 effort 列表。OpenCodex 的名单投影中同样携带每个候选模型的 effort 集合roster 中通过catalogEntryEfforts(entry)为每个 candidate 附efforts: string[]见 subagent-roster.ts供注入的 usage hint 文本向模型准确描述这个模型支持哪些 effort。2.2 资格的现行语义只有disabled被排除研究笔记基于4462b9dee当时的规则记录V2 下模型必须固定multi_agent_version Some(V2)才能作为后端支持。上游后续commit6d4d9442cSupport leaf models in multi-agent v2放宽了该规则。以当前仓库源码为准subagent-roster.ts 的isEligibleV2SubagentEntry注释给出了现行的三分语义目录值multi_agent_versionV2 资格含义v2合格且子代理可再委派递归协作工具上游对gpt-5.6-sol/gpt-5.6-terra的引脚v1合格的叶子LEAFworker上游对gpt-5.6-luna的引脚缺失 / null合格的叶子 worker路由或无引脚的原生模型由 feature flag 决定disabled唯一基于能力的排除项model_supports_multi_agent_backend只拒绝它注意这里的职责分裂该字段现在回答的是子代理能否拿到协作工具collab_tools_enabled而不是能否被委派。structure/subagents.md 的契约表也印证了这一点被推荐advertised的模型数有min(5, 可见合格行数)的上限而可被委派的目标资格没有数量上限仅 V2 下排除disabled。三、模型引脚upstream-models.json 与目录快照研究笔记在测量时确认了两处快照相等上游models-manager/models.json与 OpenCodex 的 upstream-models.json引脚情况为slugmulti_agent_versiongpt-5.6-solv2gpt-5.6-terrav2gpt-5.6-lunav1其余测得为 null 的模型由 feature flag 决定仓库内的 upstream-models.json 当前确实包含这些引脚值v2出现于 sol/terra 等行v1出现于 luna 行其余行为null。structure/subagents.md 进一步说明normalizeRoutedCatalogEntry会从路由routed条目中删除multi_agent_version——因为路由行克隆自原生模板时若继承 OpenAI 的引脚会给第三方提供商虚假的能力声明。3.1applyMultiAgentMode三种模式如何落章stampingapplyMultiAgentModeparsing.ts实现OcxConfig.multiAgentMode到目录字段的映射模式行为default清除陈旧的强制值对原生行重新套用上游快照引脚有 pin 的保留如 luna 的v1是真实能力声明必须保留无 pin 的原生行在multi_agent_v2feature 开启时落章v2关闭时删除该键v1强制所有行v1覆盖上游引脚v2强制所有行v2覆盖上游引脚luna 也包括在内一个关键的交互细节mode v2且keepNativeChatGptOnV1 true时parsing.tsChatGPT 原生行被单独落章回v1。其动机issue #92是原生父代理派生路由子代理时任务体是后端加密的NEW_TASK形态需要原生行保持 v1 语义才能打通。CLI 会检测keep-native-v1与multiAgentMode: v2的组合并给出冲突提示v2.ts 的 CONFLICT — global multi_agent_v2 overrides the native v1 catalog pin。四、Fork 与 override 规则笔记中记录的 fork 规则来源源码 上游 issue #20077 lead并反映在config/mod.rs默认 usage hint 文本中全历史 forkfull-history fork继承父代理的 model/effort并拒绝 overrideoverride 只允许出现在非全历史 fork即fork_turns: none或部分历史 fork。这条规则的运维含义是想让某个子代理跑在不同模型上不能走继承完整会话历史的 fork 路径必须显式声明fork_turns: none或部分。OpenCodex 注入给模型的 multi-agent guidance 文本中携带了fork_turns none的提示见 013 影响矩阵对 responses.ts multi_agent guidance 的引用并在注入侧保证roster 资格用的是 V2 兼容的前 5 名而不仅仅是目录中存在——这正是第二节筛选链与注入逻辑的衔接点。五、V1 / V2 工具界面与生命周期笔记的 Tool surface notesV1 工具族spawn / wait / send / close / resume在产品界面上使用multi_agent_v1命名V2 协作工具位于 collaboration 命名空间下不能在functions.exec内被调用默认共享 usage hint 中已说明commitb00c9b2e1在 features crate 中将 multi-agent v2 标记为 stable。OpenCodex 侧的运维入口是ocx v2子命令族cli/v2.ts、cli/help.tsocx v2 sub status | on | off | mode | keep-native-v1 | threads | mode-hintocx v2 status报告 feature 开关、multiAgentMode、agents.max_depth等状态ocx v2 on/off切换全局multi_agent_v2feature并触发目录重新落章catalog resyncocx v2 threads n写features.multi_agent_v2.max_concurrent_threads_per_sessionocx v2 keep-native-v1 on/off控制第三节描述的 v1 保留策略。ocx v2 status还会检查一个上游硬约束[agents] max_threads与multi_agent_v2互斥——codex-rs 在resolve_multi_agent_v2_config阶段会因agents.max_threads cannot be set when features.multi_agent_v2 is enabled而拒绝启动上游core/src/config/mod.rs。features.ts 的注释详细记录了该迁移背景并发配置的唯一合法位置是features.multi_agent_v2.max_concurrent_threads_per_sessionCLI 会在检测到[agents] max_threads时打印 WARNING 提示移除。六、已知稳定性与生命周期风险笔记明确标注这些是stability / lifecycle leads非产品保证即来自 issue 报告的线索而非官方承诺但都对应 OpenCodex 影响矩阵中的具体风险项槽位泄漏 / 需要显式 closeissue 报告显示子代理槽位存在泄漏代理需要显式close_agent释放。OpenCodex 侧的对策是把并发上限作为一等配置项管理max_concurrent_threads_per_session 1避免无界派生。加密 spawn 参数的后端不匹配issue #26753 leadNEW_TASK等加密任务体在不同后端间的形态不一致这正是keepNativeChatGptOnV1策略要解决的场景之一。V2 roster 不匹配把 lunav1 引脚放在 V2 轮次的推荐位会招致 spawn 拒绝——即使目录中列出了它。对应 structure/subagents.md 的契约与 upstream-models.json 的引脚同步要求引脚变化时需要重新同步快照。wait_agent可被独立关闭上游 #34887 之后罕见用户配置可能移除 wait 工具OpenCodex 的 guidance 文本若假设 wait 恒存在会有偏差影响矩阵将暴露wait_agent_enabled的读/状态查询列为后续项默认true时不阻塞。guidance 措辞漂移默认expose_spawn_agent_model_overrides true时任何参数总是隐藏的绝对化表述都是过时说法注入文本需要与暴露标志保持同步。七、小结契约的三层结构综合研究笔记与仓库实现OpenCodex 的多智能体契约可以归纳为三层能力层pinupstream-models.json 中每个模型行的multi_agent_versionv2 递归 / v1 叶子 / null 由 flag 决定 / disabled 排除由 applyMultiAgentMode 按default/v1/v2三种multiAgentMode落章且路由行一律剥离该字段推荐层rostereffectiveSubagentRoster 以可见性 → 界面兼容性 → 自然优先级 → 取前 5生成 candidates/advertised/excluded 三视图每个被排除模型带原因码运维层CLI/configocx v2子命令族与[features.multi_agent_v2]TOML 表管理 feature 开关、并发上限与 mode hint同时守卫agents.max_threads互斥、keep-native-v1冲突等上游硬约束。该契约的适用前提是当前仓库快照下的 codex-rs 上游行为若上游引脚或筛选规则再次变化如资格判定从 Some(V2)演进到仅排除 disabled需以 structure/subagents.md 的契约表与 devlog 对应研究单元为准重新核对。赞分享【免费下载链接】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 子代理注入努力值injection-effort选择器从配置契约到多智能体提示注入的完整实现解析opencodex 子代理注入努力值injection effort选择器从配置契约到多智能体提示注入的完整实现解析 opencodexUniversaOpenShell Protobuf API 规范详解实体引用、Workspace 作用域与 gRPC 契约演化规则OpenShell Protobuf API 规范详解实体引用、Workspace 作用域与 gRPC 契约演化规则 本文以仓库根目录 proto/READMApache Pulsar 内置连接器Built-in Connector完全指南Source 与 Sink 一览及实战部署Apache Pulsar 内置连接器Built in Connector完全指南Source 与 Sink 一览及实战部署 Apache Pulsar消息队列后端流处理上一篇10个KeePassXC高级技巧最大化您的密码管理效率 下一篇抖音无水印批量下载完整指南一条链接存下单个视频、整页主页与直播创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考