Поверхность подагентов (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. Выбранные значения используются в добавляемом OpenCodex руководстве по делегированию, которое отдельно управляется полем multiAgentGuidanceEnabled. Они не задают маршрутизацию порождений на стороне прокси. Необязательный injectionPrompt полностью заменяет встроенный текст инструкции.

Если явно включить syncCodexSubagentDefaults, следующая синхронизация или перезапуск применит выбранные модель и уровень как нативные значения по умолчанию для подагентов Codex в [agents], когда активной маршрутизацией Codex управляет OpenCodex. Внешняя пользовательская конфигурация провайдера остаётся неизменной. Эти значения действуют только для вновь создаваемых задач Codex и сами по себе не запускают делегирование. Существующие пользовательские значения [agents] не перезаписываются, а сохраняются, поэтому запрошенные и фактические значения Codex по умолчанию могут различаться.

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: выберите предпочтительную модель и, при желании, уровень рассуждений. Включите Использовать как нативные значения по умолчанию для подагентов Codex, чтобы после следующей синхронизации или перезапуска применять тот же выбор к новым задачам Codex, когда активной маршрутизацией управляет OpenCodex. Внешняя пользовательская конфигурация провайдера остаётся неизменной. Этот переключатель не зависит от переключателя руководства по делегированию. На 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"}'

# Синхронизировать выбранные значения с нативными значениями подагентов Codex по умолчанию (нужна модель)
curl -X PUT http://localhost:10100/api/injection-model \
  -H 'Content-Type: application/json' \
  -d '{"model": "anthropic/claude-sonnet-5", "syncCodexSubagentDefaults": true}'

# Задать пользовательский промпт инструкции (плейсхолдеры {{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, multiAgentGuidanceEnabled, syncCodexSubagentDefaults, глобальную шкалу efforts и включённые нативные/маршрутизируемые модели в available. PUT является частичным обновлением: пропуск effort или prompt сохраняет текущее значение, а null очищает его. Для syncCodexSubagentDefaults: true требуется выбранная модель; очистка model всегда очищает уровень и отключает синхронизацию нативных значений по умолчанию. API валидирует уровень по глобальной шкале Codex; Codex дополнительно валидирует уровень порождения по целевой записи каталога.

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

Необязательная настройка уровня рассуждений подагента хранится как injectionEffort и имеет смысл только вместе с моделью внедрения. Она добавляет указание reasoning_effort во внедряемую инструкцию v2 и не меняет уровень рассуждений родительской сессии. При включённом syncCodexSubagentDefaults и маршрутизации под управлением OpenCodex после следующей синхронизации или перезапуска она также становится нативным уровнем подагента по умолчанию для новых задач Codex. При любом форке, допускающем переопределения, 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; лимит также можно переключить рядом с заголовком группы конкретного провайдера.