Субагенты в Codex полезны не потому, что «несколько AI лучше одного». Они полезны, когда часть работы можно отделить от главного треда, выполнить независимо и вернуть в виде короткого проверяемого результата. Такой подход уменьшает шум от поиска по репозиторию, тестовых логов и промежуточных гипотез. Но при неудачном разбиении он лишь размножает неопределённость и конфликтующие правки.
В актуальных локальных версиях Codex этот workflow включён по умолчанию в приложении, CLI и IDE extension. Достаточно прямо попросить о делегировании; его также могут требовать применимые инструкции AGENTS.md или skill. При этом каждый субагент отдельно использует модель и инструменты, поэтому токенов уходит больше, чем на сопоставимую работу одного агента. Текущий контракт описан в официальной документации OpenAI о Subagents.
Быстрый тест на пригодность задачи
Перед запуском представьте не список ролей, а граф зависимостей. Если агент B не может закончить без решения агента A, эти ветви не являются параллельными. Если два агента должны менять один интерфейс, у них общий write surface. Если главный тред не знает, как сравнить два ответа, делегирование не имеет критерия завершения.
Хорошо отделяются задачи, где:
- область чтения или проверки заранее ограничена;
- результат можно выразить как факты, ссылки на файлы, команды и неизвестные;
- ошибка одной ветви не заставляет остальные переписывать свою работу;
- финальное решение остаётся у главного треда.
Плохо отделяются архитектурные решения с постоянным согласованием, последовательные изменения одной схемы и правки одних и тех же файлов. Иногда достаточно делегировать разведку, а реализацию оставить одному агенту.
Формулируйте контракт возврата
Запрос «используй субагентов» не определяет ни границы, ни качество результата. Практичный запрос может выглядеть так:
textРазбери падение интеграционных тестов с помощью трёх субагентов. - explorer: только чтение, проследи путь от теста до сетевого клиента; - test_triage: запусти относящиеся к ошибке тесты и классифицируй падения; - docs_reader: проверь только API, на которые опирается код, по прямым источникам. Не изменяйте файлы. Дождись всех трёх результатов. Верни одну сводку: подтверждённые факты, гипотезы, ссылки на файлы и команды, непроверенные области и следующее решение для главного треда.
Здесь заданы область, режим работы, условие ожидания и язык доказательств. Если после диагностики нужна правка, стоит создать отдельный этап: один worker получает конкретные файлы, минимальную цель и команду проверки. Это безопаснее, чем разрешить каждому исследователю исправлять всё, что он заметит.
Права наследуются, а ответственность — нет
Локальные субагенты наследуют текущий sandbox или permission mode родительского workflow. В App и IDE режим выбирают до просьбы о делегировании. В интерактивном CLI approval может прийти от фонового agent thread: оверлей показывает источник, а клавиша o открывает этот тред перед решением. Если неинтерактивный запуск не умеет показать новое подтверждение, защищённое действие завершается ошибкой, которая возвращается родителю.
Также при spawn применяются живые override родительского треда. Поэтому файл custom agent с sandbox_mode = "read-only" не следует считать магическим барьером, если сам запуск уже получил более широкие разрешения. Проверяйте фактический режим до старта.
| Ответственность | Разумная исходная граница | Причина |
|---|---|---|
| Исследование репозитория | read-only | Нужны ссылки и карта, а не изменения |
| Проверка документации | read-only и только нужные источники | Меньше дрейфа и случайных действий |
| Реализация исправления | Узкая область записи | Проще увидеть diff и откатить ошибку |
| Внешняя публикация или удаление | Отдельное явное подтверждение | Это уже не внутренняя работа с кодом |
Наблюдайте за отдельными тредами
Интерфейс управления зависит от клиента:
- в Codex App можно открыть субагента из активности главного чата и попросить Codex перенаправить, остановить или закрыть тред;
- в Codex CLI команда
/agentпереключает между активными agent threads; - в IDE extension доступная background-agent panel показывает состояние и позволяет открыть или остановить агента.
Вмешиваться нужно не только при ошибке. Если агент начал читать лишний сервис, возвращает сырые логи вместо вывода или обнаружил зависимость, которая ломает исходное разбиение, его следует перенаправить сразу. Продолжение работы по неверной карте делает ошибку дороже.
Custom agent нужен для повторяемой обязанности
В Codex есть встроенные default, worker и explorer. Собственный агент оправдан, когда одна и та же обязанность повторяется и ей действительно нужен фиксированный набор инструкций, модель, reasoning effort, sandbox или MCP. Личные файлы хранятся в ~/.codex/agents/, проектные — в .codex/agents/. В каждом отдельном TOML обязательны name, description и developer_instructions.
tomlname = "release_reader" description = "Read-only анализ влияния изменений перед выпуском." model = "gpt-5.6-terra" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ Проследи затронутые пути выполнения и конфигурацию. Верни доказательства с файлами, рисками и неизвестными. Не меняй код и не расширяй область задачи. """
Согласно текущей официальной рекомендации, gpt-5.6 подходит для трудных неоднозначных задач, gpt-5.6-terra — для более быстрых read-heavy ветвей, а gpt-5.6-luna — для узкой повторяемой работы. Доступ зависит от аккаунта, способа авторизации и клиента, поэтому такие значения нужно считать актуальной конфигурацией, а не вечным стандартом.
Глобальные параметры находятся в [agents]: там можно управлять включением tools, лимитом одновременно открытых тредов, моделью и reasoning effort по умолчанию. Если проблема на самом деле связана с приоритетом пользовательского и проектного TOML, используйте отдельное руководство по config.toml, а не расширяйте конфигурацию методом проб и ошибок.
Итоговая сводка должна выдержать проверку
После возврата результатов главный тред обязан устранить дубли, разделить наблюдения, гипотезы и рекомендации, а затем открыть ключевые доказательства. «Тесты прошли» без списка запущенных targets недостаточно. «Уязвимость найдена» без достижимого пути выполнения недостаточно. «Ссылок нет» без понятной области поиска тоже недостаточно.
Хорошая оркестрация сохраняет в главном треде требования, решения и ответственность, а шумную промежуточную работу переносит в ограниченные ветви. Она может сократить прошедшее время, если ветви независимы, но никогда не отменяет проверку объединённого результата.
Если вы ещё выбираете между разными coding-agent продуктами, а не настраиваете делегирование внутри Codex, сначала сравните Claude Code и Codex.
