Поверхность подагентов (v1 / base / v2)

Что такое подагенты

Подагент — это отдельный воркер Codex, которого основной агент может создать для узкой задачи. У него собственный контекст и собственные инструменты, поэтому несколько независимых задач могут идти параллельно. opencodex управляет тем, какая collaboration surface Codex раскрывает для этих воркеров, какие модели Codex предлагает для них и как выполняется fallback при сбое модели. Когда именно основной агент должен делегировать задачу, opencodex не решает.

Режимы

Режим выбирается для новых сессий. Уже запущенные сессии сохраняют ту поверхность, с которой они стартовали.

Режим	Что получает Codex	Кому подходит
v1	Классические namespaced-инструменты `spawn_agent`, `send_input`, `resume_agent` и `close_agent`. Spawn может сразу выбрать другую модель.	Новички, которым нужно надёжное делегирование между разными провайдерами, особенно для потомков native-to-routed.
base (default)	Upstream pin’ы моделей: GPT-5.6 Sol/Terra используют v2, Luna использует v1, а модели без pin’а следуют feature flag’у Codex `multi_agent_v2`.	Большинство пользователей. Этот режим следует ожидаемой surface для каждой модели и не навязывает одну глобально.
v2	Плоские инструменты `spawn_agent`, `send_message`, `followup_task`, `interrupt_agent` и agent-list, с конкурентными сессиями.	Пользователи, которым нужен новый concurrent-workflow и которые понимают наследование модели и ограничение encrypted task ниже.

Как это работает

Выбранный режим управляет полем multi_agent_version в каждой записи каталога, которую читает Codex:

v1 записывает multi_agent_version = "v1" для каждой модели.
base восстанавливает upstream pin’ы. У записей без pin’а поведение определяется feature flag’ом multi_agent_v2.
v2 записывает multi_agent_version = "v2" для каждой модели, кроме случая, когда включён режим Оставить ChatGPT на v1: собственные строки ChatGPT остаются "v1", а маршрутизируемые и комбо-строки остаются "v2".

opencodex применяет это как финальный проход и к живому каталогу /v1/models, и к каталогу, синхронизированному на диск. Поэтому смена режима одинаково влияет на новые App-, CLI- и TUI-сессии.

Для ростера v2 допустимы три состояния записи: штамп "v2", явное null или отсутствие поля multi_agent_version. Настоящий pin "v1" исключает запись, потому что он прямо указывает, что эта модель относится к другой collaboration surface.

Модель делегирования и effort

Раздел Sub-agent delegation в дашборде управляет тремя связанными настройками:

injectionModel — предпочитаемая модель воркера, которую opencodex упоминает в guidance.
injectionEffort — необязательный reasoning_effort, запрашиваемый для этой модели.
injectionPrompt — замена встроенного текста guidance для v2.

multiAgentGuidanceEnabled по умолчанию включён и служит главным переключателем guidance-сообщений, которые opencodex пишет сам, на обеих поверхностях. Если выключить его, подавляются и блок v2 designation, и proactive text для v1.

Это инструкции для основного агента, а не proxy-side spawn router. На v2 полный форк истории унаследует модель родителя и отвергнет model- или effort-override. Поэтому guidance просит Codex использовать fork_turns: "none" (или положительное частичное число ходов, например "3") при передаче model или reasoning_effort, а сообщение задачи делать самодостаточным.

Пользовательский injectionPrompt может использовать все четыре placeholder’а:

Плейсхолдер	Подставляемое значение
`{{model}}`	Эффективная предпочитаемая модель для текущего запроса. Нативный `injectionModel` без селектора получает квалификатор аккаунта только тогда, когда сам запрос явно указывает селектор аккаунта. Неразрешённое или неоднозначное значение без селектора заменяется пустой строкой; неразрешённый явно квалифицированный по аккаунту или маршрутизируемый ID остаётся без изменений
`{{effort}}`	Настроенный `injectionEffort` либо пустая строка
`{{roster}}`	Разрешённый ростер, видимый в picker и совместимый с поверхностью
`{{fallback}}`	Настроенное глобальное fallback guidance

Встроенное guidance для v2 ограничено 700 символами. Если оно не укладывается, opencodex сначала убирает ростер, а не обрезает ядро инструкций для spawn. Встроенное guidance включается только тогда, когда разрешается предпочитаемая модель, допустимый ростер или fallback chain. Настроенного injectionModel достаточно, чтобы отобразить пользовательский prompt; если значение без селектора нельзя разрешить однозначно, {{model}} заменяется пустой строкой.

На v1 opencodex внедряет только upstream-style proactive guidance о делегировании на уровнях effort max или ultra. Предпочитаемую модель, ростер, fallback list и custom prompt на v1 он не добавляет.

Опция syncCodexSubagentDefaults, выключенная по умолчанию, отделена от guidance. Когда opencodex владеет активной маршрутизацией Codex, sync или restart могут записать выбранные значения как marker-owned поля [agents] default_subagent_model и default_subagent_reasoning_effort в TOML Codex. opencodex обновляет или удаляет только те поля, которые помечены его marker’ами. Если любое из целевых полей принадлежит пользователю, пара остаётся без изменений вместо частичной записи; неоднозначный TOML отклоняется без записи. Внешние provider manager’ы и user-owned root routing тоже сохраняют приоритет.

Fallback chains

Для порождённого воркера opencodex строит такой порядок приоритета:

Запрошенная основная модель.
Модельная цепочка из subagentModelFallbackByModel в конфигурации opencodex, ключ — запрошенная основная модель.
Глобальный список subagentModelFallback в конфигурации opencodex.

Модельные цепочки fallback для ролей должны храниться в конфигурации opencodex, а не в $CODEX_HOME/agents/*.toml. Codex 0.146+ строго десериализует файлы ролей агента и отвергает model_fallback как неизвестное поле, из-за чего пропускается всё определение роли (#1190). opencodex по-прежнему читает устаревшую строку model_fallback из TOML для обратной совместимости, но ocx doctor предупреждает о ней, а сам Codex игнорирует затронутую роль.

Дубликаты id моделей удаляются с сохранением первого вхождения. При выборе opencodex пропускает кандидатов, которые отключены, немаршрутизируемы, опираются на отключённого провайдера, помечены как unhealthy, находятся в cooldown, не имеют доступного pooled-аккаунта Codex или вышли за настроенный порог квоты. Результаты availability probe кэшируются на subagentModelFallbackPollMs (по умолчанию 60 секунд).

Fallback не делает несовместимые encrypted task читаемыми. Когда задача потомка зашифрована для ChatGPT, выбор ограничивается каноническими нативными целями ChatGPT и прямыми key-auth Responses-маршрутами, явно доверенными через allowEncryptedV2AgentTasks: true, даже если другая внешняя модель появляется раньше в цепочке. Combo по-прежнему использует только нативные цели.

Доставка шифрованных задач v2

Codex может отправить задачу child v2 из native-to-routed пути только как backend-encrypted encrypted_content. Эту нагрузку может прочитать нативный backend ChatGPT, но не внешний провайдер. Это известное ограничение #92.

opencodex завершаетcя безопасно и не пересылает пустую или нечитаемую задачу:

Прямой не-нативный маршрут возвращает HTTP 400 с error.code = "unreadable_encrypted_agent_task" и не отражает ciphertext назад, если его key-auth Responses-провайдер явно не включил allowEncryptedV2AgentTasks: true.
Combo для такой задачи рассматривает только канонические нативные цели ChatGPT, включая retry. Если ни одной подходящей цели нет, возвращается тот же HTTP 400.
Читаемая plaintext-задача сохраняет обычное поведение маршрутизации и fallback.

Варианты восстановления: выбрать нативного потомка ChatGPT, добавить нативную цель ChatGPT в combo, использовать v1 для делегирования между разнородными провайдерами либо повторно отправить задачу как plaintext в содержимом v2 agent_message, если вы управляете вызывающей стороной.

Экспериментальная опция agentTaskRecovery по умолчанию выключена. После явного включения она может восстановить этот формат дополнительным аутентифицированным запросом к фиксированному endpoint ChatGPT, но расходует квоту, добавляет задержку и зависит от закрытого поведения backend. При любом сбое сохраняется прежняя ошибка unreadable_encrypted_agent_task. Подробности приведены в английском справочнике конфигурации.

Как сменить режим

GUI

Dashboard → первая ячейка со статистикой: выберите v1, base или v2.
Models → сегментированный переключатель в верхнем ряду: выберите тот же глобальный режим.
Dashboard → Sub-agent delegation: задайте модель/effort для guidance и opt-in для native-default.
Subagents: выберите и упорядочьте ростер, а также настройте глобальную fallback chain.

CLI

Для collaboration surface и native feature settings используйте ocx v2:

ocx v2 status
ocx v2 mode v1
ocx v2 mode default
ocx v2 mode v2
ocx v2 threads 8

Для делегирования, ростера, effort cap и fallback settings используйте ocx agent:

ocx agent status
ocx agent injection set --model anthropic/claude-sonnet-5 --effort xhigh
ocx agent subagents set gpt-5.6-sol,anthropic/claude-sonnet-5
ocx agent fallback set gpt-5.4-mini,xai/grok-4.5 --poll-ms 60000
ocx agent effort set --subagent max

Чтобы очистить nullable-значение у ocx agent injection, передайте -, либо используйте соответствующее действие clear для ростера или fallback list. Полный состав семейств команд см. в справочнике CLI.

API

Management API предоставляет соответствующие GET и PUT endpoint’ы:

Эндпоинт	Чем управляет
`/api/v2`	Surface mode, native feature flag и thread settings
`/api/injection-model`	Предпочитаемую модель, effort, custom prompt, guidance и native-default sync
`/api/effort-caps`	Потолки effort для main-agent и sub-agent
`/api/subagent-models`	Упорядоченный ростер до пяти моделей
`/api/subagent-model-fallback`	Глобальный fallback order и poll interval

Например:

curl -X PUT http://localhost:10100/api/v2 \
  -H 'Content-Type: application/json' \
  -d '{"multiAgentMode":"v2"}'

curl -X PUT http://localhost:10100/api/injection-model \
  -H 'Content-Type: application/json' \
  -d '{"model":"anthropic/claude-sonnet-5","effort":"xhigh"}'

FAQ

Выбор модели делегирования заставляет Codex её порождать?

Нет. Guidance может рекомендовать модель, а native-default sync может задать значение по умолчанию для Codex, но решение о том, делегировать ли задачу, всё равно принимает основной агент.

Почему мой child v2 использовал модель родителя?

Полный форк истории на v2 наследует модель родителя. Используйте spawn, который задаёт fork_turns как "none" или положительное частичное число ходов, прежде чем передавать model- или effort-override.

Почему настроенная модель не попала в ростер v2?

Она может быть скрыта в picker, выходить за лимит пяти моделей, отсутствовать в каталоге или иметь pin на v1. Значения "v2", null или отсутствие surface-поля допускаются; настоящий "v1" pin — нет.

Смена режима влияет на уже запущенные сессии?

Нет. После смены режима начните новую сессию Codex. Если долго живущий App host всё ещё показывает устаревшее состояние каталога, выполните ocx sync и перезапустите нужную поверхность Codex.

Reasoning effort

injectionEffort влияет только на guidance для делегированных воркеров и, если это явно включено, на нативные default’ы подагентов в Codex. На effort родительской сессии он не влияет. ultra — это верхний client-facing tier, который Codex переводит в max; затем opencodex сопоставляет или ограничивает это значение под выбранного провайдера.

Context cap

Ограничение контекста модели не зависит от режима подагентов. Настраивайте его на странице Models; нативные модели OpenAI сохраняют свои реальные окна контекста.