让任意模型出现在Codex子代理选择器中：OpenCodex Sub-agent Surface深度使用教程-平芜编程栈

让任意模型出现在Codex子代理选择器中：OpenCodex Sub-agent Surface深度使用教程

【免费下载链接】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 通用提供方代理）的Sub-agent Surface（子代理界面）功能，可以把你配置好的任意第三方模型——Claude、Gemini、Grok、DeepSeek 等——直接放进 Codex 的子代理选择器，让主代理随时把任务并行委派给你自选的模型。本教程带你从模式选择、模型名册到委派指引，完整配置 OpenCodex 的子代理 Surface，让任意模型出现在 Codex 子代理选择器中。

什么是子代理？先认识这个"并行工人"

子代理（sub-agent）是主代理创建的独立 Codex 工作器：它拥有独立的上下文和工具集，因此多个独立任务可以并行推进。OpenCodex 负责管理三件事，但不决定主代理何时委派：

Codex 使用哪种协作界面暴露子代理（v1 / base / v2）；
子代理选择器中展示哪些模型（roster，最多 5 个）；
首选模型失败或配额耗尽时自动回退到哪条链路。

打开ocx gui进入仪表盘，左侧导航的Subagents页面就是管理子代理选择器的入口。

一键切换三种子代理界面模式：v1 / base / v2

子代理 Surface 有三种模式，它决定每个模型在目录中的multi_agent_version字段，从而决定 Codex 向子代理提供哪一套工具集：

模式	Codex 获得什么	适合谁
v1	经典`spawn_agent`、`send_input`、`resume_agent`工具，spawn 时可直接指定另一个模型	需要在不同 provider 之间可靠委派的初学者
base（默认）	尊重每个模型的上游固定值，未固定的跟随 Codex 功能开关	大多数用户，推荐从它开始
v2	扁平化`spawn_agent`、`send_message`、`interrupt_agent`等工具，支持并发会话	想要最新并发工作流、理解模型继承规则的用户

三种方式随时切换（任选其一）：

GUI：Dashboard 顶部 "Sub-agent" 卡片，或 Models 页顶部分段控件，点选 v1 / base / v2
CLI：ocx v2 mode v1、ocx v2 mode default、ocx v2 mode v2
API：PUT /api/v2，请求体{"multiAgentMode":"v2"}

💡注意：模式更改只影响新建会话，已有会话保留其开始时的界面。若长时间运行的 App 仍显示旧目录，请运行ocx sync并重启该 Codex 界面。

三步让任意模型出现在子代理选择器

这是本教程的核心。原理很简单：Codex 会把选择器可见的目录条目按priority升序排序，取前 5 个作为spawn_agent的模型 override 列表。OpenCodex 会把你挑选的模型按顺序写入subagentModels并调整目录优先级——被选中的模型由此稳定占据选择器前排。

第 1 步：在 Subagents 页面挑选并排序最多 5 个模型

支持三种形式的模型 id：裸原生 id（如gpt-5.6-sol）、路由 id（如anthropic/claude-sonnet-5、xai/grok-4.5）、账户限定的<selector>/<native-model>id（精确 id 需通过 CLI 设置）。

第 2 步：设置委派指引模型与推理强度（可选）

在 Dashboard 的Sub-agent delegation卡片里选择一个首选工作器模型和可选的 reasoning effort，OpenCodex 会在提示词中注入委派指引，告诉主代理"优先使用该模型、roster 里还有哪些可用"。

第 3 步：同步目录，新建会话生效

ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5 # 命令行一键设置名册 ocx sync # 刷新 Codex 模型目录

完成以上步骤后，你的路由模型就会像上图这样出现在 Codex 的子代理选择器里。✨

配置子代理委派模型与推理强度

Sub-agent delegation管理三个相关设置：injectionModel（首选工作器模型）、injectionEffort（可选的 reasoning effort）、injectionPrompt（自定义指引文本，支持{{model}}、{{effort}}、{{roster}}、{{fallback}}四个占位符）。

两点常见疑问：

指引 ≠ 强制：这些是发给主代理的"建议"，不是代理侧的 spawn 路由器，是否委派仍由主代理判断；
effort 上限：injectionEffort只影响子代理委派指引，不会改变父会话的 effort；ultra是面向客户端的顶级档位，Codex 会将其转换为max。

回退链：子代理配额耗尽时自动换模型

首选模型配额用尽时，任务不会卡住。OpenCodex 按以下优先级构建回退顺序：

请求的主模型；
按模型配置的 per-model 回退链（subagentModelFallbackByModel）；
全局回退列表（subagentModelFallback）。

ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000

选择过程中会自动跳过已禁用、冷却中、标记不健康或超出配额阈值的候选，可用性探测默认缓存 60 秒，避免频繁探测。

子代理选择器常见问题：4 个高频坑

问题	解答
配置的模型没出现在选择器？	可能被隐藏、超出 5 个的显示上限、未同步进目录，或被固定在 v1。运行`ocx sync`后新建会话再检查
v2 子级为什么用了父模型？	全历史 v2 fork 会继承父模型；传递 model/effort 覆盖时需把`fork_turns`设为`"none"`或部分 turn 数
出现`unreadable_encrypted_agent_task`？	v2 原生 ChatGPT 子任务是密文，外部 provider 读不了；可改用 v1 做跨 provider 委派，或在 combo 中加入原生 ChatGPT 目标
选了委派模型就会强制 spawn 吗？	不会。指引只是"推荐"，最终由主代理决定