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

opencodex позволяет выбрать поверхность мультиагентного взаимодействия для каждой модели в каталоге. Переключатель Sub-agent в дашборде и на странице Models управляет этим глобально.

На поверхности v2 (multi_agent_v2) порождённый подагент по умолчанию наследует модель родителя: fork_turns по умолчанию равен all, а форки с полной историей отклоняют переопределения. Начиная с v2.7.2 opencodex внедряет инструкцию, которая учит модель обходить наследование: вызов spawn_agent, устанавливающий fork_turns в "none" (или частичный форк, например "3"), может передать аргументы model / reasoning_effort, которые рантайм Codex разбирает и применяет, хотя опубликованная схема инструмента их скрывает. Известное ограничение транспорта: когда нативный родитель порождает потомка, маршрутизируемого на ненативного провайдера, клиент Codex может отправить полезную нагрузку NEW_TASK только как зашифрованный бэкендом encrypted_content (#92). opencodex не пересылает нечитаемую задачу внешнему провайдеру: прямой маршрут завершается с HTTP 400 и кодом unreadable_encrypted_agent_task, а комбо пропускает цели без возможности дешифрования и при наличии выбирает каноническую нативную цель ChatGPT. Для делегирования между разнородными провайдерами используйте v1, выберите нативного потомка ChatGPT или отправьте задачу повторно как открытый v2 agent_message контент.

Режимы

Режим	Поверхность	Поведение
v1	`multi_agent_v1`	Классические агентные инструменты с пространством имён: `send_input` / `close_agent` / `resume_agent`. Переопределение модели в `spawn_agent` может запустить подагента на другой модели.
base (по умолчанию)	Вышестоящие закрепления	Восстанавливает вышестоящие закрепления моделей: gpt-5.6-sol и gpt-5.6-terra используют v2, gpt-5.6-luna — v1, а незакреплённые модели следуют фиче-флагу Codex `multi_agent_v2`. Поведение порождения следует поверхности, которая определяется для данной модели.
v2	`multi_agent_v2`	Плоские инструменты `spawn_agent` с параллельными сессиями и `send_message` / `followup_task` / `wait_agent` / `interrupt_agent`. Потомки наследуют модель родителя при форках с полной историей; `fork_turns: "none"` (или частичный форк) принимает переопределения `model` / `reasoning_effort`. Если потомок native→routed получает только зашифрованное бэкендом содержимое задачи, внешние маршруты возвращают `unreadable_encrypted_agent_task`, а смешанные комбо предпочитают цель с возможностью дешифрования (#92).

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

Только нативный бэкенд ChatGPT может прочитать свой зашифрованный полезный груз задачи. Для нечитаемого v2 agent_message opencodex применяет следующие правила до диспетчеризации провайдеру:

Прямой ненативный маршрут возвращает HTTP 400 с error.code = "unreadable_encrypted_agent_task". Ответ никогда не отражает зашифрованный груз.
Комбо рассматривает для такой задачи только канонические нативные цели ChatGPT, включая повторные попытки. Если в комбо нет цели с возможностью дешифрования, он возвращает тот же ответ 400 вместо отправки пустой задачи внешнему провайдеру.
Читаемые открытые задачи сохраняют обычный порядок комбо и поведение фейловера.

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

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

Режим задаёт поле multi_agent_version в каждой записи каталога, которую читает Codex:

Режим v1: принудительно устанавливает multi_agent_version = "v1" во всех записях, переопределяя вышестоящие закрепления.
Режим base: восстанавливает вышестоящие значения по умолчанию. Закреплённые модели получают значение из снимка; у незакреплённых поле опускается, и решение принимает фиче-флаг Codex.
Режим v2: принудительно устанавливает multi_agent_version = "v2" во всех записях, переопределяя вышестоящие закрепления.

Это переопределение — финальный проход и в живом ответе каталога /v1/models, и при синхронизации каталога на диске. Поэтому смена режима применяется к новым сессиям единообразно, независимо от того, как была построена запись.

Модель делегирования и уровень рассуждений

Селектор Sub-agent delegation в дашборде сохраняет injectionModel и, при желании, injectionEffort. Это настройки инструкции по делегированию, а не маршрутизатор порождений на стороне прокси. Необязательный injectionPrompt полностью заменяет встроенный текст инструкции.

multiAgentGuidanceText определяет поверхность по инструментам запроса — включая WebSocket-путь Codex Desktop (responses_lite), где инструменты приходят внутри входного элемента additional_tools, а не в массиве tools запроса.

В ходах v2 (Sol/Terra в режиме base, любая модель в режиме v2) прокси внедряет компактный блок инструкции — с бюджетом 700 символов — когда задана допустимая модель внедрения или эффективный список подагентов не пуст. Блок условно описывает переопределения model / reasoning_effort, не утверждая, видны ли они в активной схеме, требует fork_turns: "none" (или частичный форк), называет только допустимую каноническую предпочтительную модель и перечисляет только настроенные модели из первых пяти видимых в селекторе, совместимых с v2 и отсортированных по priority записей Codex с доступными уровнями effort.

В ходах v1 прокси лишь зеркалирует вышестоящий текст Proactive delegation на верхнем уровне рассуждений (max / ultra). Ни назначение модели, ни список, ни пользовательский промпт туда не добавляются — v1 намеренно остаётся минимальным.

Чтобы заменить встроенную инструкцию v2, задайте injectionPrompt (ключ конфигурации или PUT /api/injection-model со значением prompt). Плейсхолдеры {{model}}, {{effort}} и {{roster}} подставляются как настроенная модель внедрения, уровень рассуждений и строка разрешённого списка. Условия срабатывания не меняются: пользовательский промпт никогда не заставит сработать ход, который иначе остался бы без внедрения.

Смена режима

GUI

Dashboard → первая ячейка статистики: нажмите v1, base или v2.
Страница Models → сегментированный переключатель в верхнем ряду.
На обеих страницах есть кнопка ?, открывающая модальное окно справки со ссылкой на эту страницу.
Dashboard → Sub-agent delegation: выберите предпочтительную модель и, при желании, уровень рассуждений. На v2 внедрённая инструкция велит агенту порождать с fork_turns: "none", чтобы переопределение модели сработало, — хотя для потомков native→routed тело задачи сейчас может приходить зашифрованным (#92).

CLI

ocx v2 mode v1       # перевести все модели на v1
ocx v2 mode default  # восстановить вышестоящие закрепления
ocx v2 mode v2       # перевести все модели на v2
ocx v2 status        # показать текущий режим + фиче-флаг Codex

API

# Прочитать режим поверхности, фиче-флаг и лимит потоков
curl http://localhost:10100/api/v2

# Установить режим поверхности
curl -X PUT http://localhost:10100/api/v2 \
  -H 'Content-Type: application/json' \
  -d '{"multiAgentMode": "v2"}'

Эндпоинт PUT /api/v2 также принимает enabled (булево значение, фиче-флаг Codex) и maxConcurrentThreadsPerSession (целое число). Он валидирует запрос, сохраняет режим, пересинхронизирует каталог и сообщает, что смена режима применяется к новым сессиям.

Селектор делегирования использует отдельный эндпоинт:

# Прочитать текущие модель/уровень и доступные значения селектора
curl http://localhost:10100/api/injection-model

# Установить оба значения
curl -X PUT http://localhost:10100/api/injection-model \
  -H 'Content-Type: application/json' \
  -d '{"model": "anthropic/claude-sonnet-5", "effort": "xhigh"}'

# Задать пользовательский промпт инструкции (плейсхолдеры {{model}}/{{effort}}/{{roster}})
curl -X PUT http://localhost:10100/api/injection-model \
  -H 'Content-Type: application/json' \
  -d '{"model": "anthropic/claude-sonnet-5", "prompt": "Delegate to {{model}}.{{roster}}"}'

# Очистить оба значения
curl -X PUT http://localhost:10100/api/injection-model \
  -H 'Content-Type: application/json' \
  -d '{"model": null}'

GET /api/injection-model возвращает model, effort, prompt, глобальную шкалу efforts и включённые нативные/маршрутизируемые модели в available. В PUT пропуск effort или prompt сохраняет текущее значение, null очищает его, а очистка model всегда очищает и уровень. API валидирует уровень по глобальной шкале Codex; Codex дополнительно валидирует уровень порождения по целевой записи каталога.

Уровень рассуждений

Необязательная настройка уровня рассуждений подагента хранится как injectionEffort и имеет смысл только вместе с моделью внедрения. Она добавляет указание reasoning_effort во внедряемую инструкцию v2 и не меняет уровень рассуждений родительской сессии. При любом форке, допускающем переопределения, Codex напрямую применяет reasoning_effort, переданный в spawn_agent.

ultra стоит выше max в каталоге Codex и добавляет семантику автоматического делегирования, но никогда не доходит до провайдера как буквальное значение в запросе. Codex преобразует ultra в max на границе клиента. Затем opencodex сохраняет запрос к провайдеру валидным:

Модель	`max` в запросе	Выбор `ultra` в запросе
gpt-5.5, gpt-5.4, gpt-5.4-mini	xhigh	xhigh (через max, затем `nativeEffortClamp`)
gpt-5.6-sol, gpt-5.6-terra	max	max
gpt-5.6-luna	max	Не объявляется его точной вышестоящей шкалой
Маршрутизируемые модели	Сопоставляется или ограничивается адаптером	Преобразуется в max, затем сопоставляется или ограничивается адаптером

Доступность в каталоге не зависит от режима v1/v2. Сгенерированные записи с поддержкой рассуждений объявляют max, чтобы прямые переопределения уровня подагента проходили валидацию; текущие сгенерированные маршрутизируемые записи объявляют также ultra. Точные вышестоящие шкалы моделей сохраняются — поэтому gpt-5.6-luna останавливается на max.

Лимит контекста

Глобальный лимит контекста по умолчанию равен 350k и ограничивает объявляемое context_window только для маршрутизируемых провайдеров, у которых лимит включён. Нативные модели OpenAI сохраняют свои реальные контекстные окна.

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