Субагенты в Codex: настраиваем AI-команду

TL;DR: Субагенты в Codex позволяют разбивать задачи на параллельные потоки — каждый со своей моделью, инструкциями и sandbox-режимом. Настраиваются через TOML-файлы, работают из коробки в CLI и приложении. Разбираю, как это настроить и когда это реально полезно.

Codex умел работать как один агент — ты даёшь задачу, он выполняет. Но когда задача большая (ревью PR из 30 файлов, исследование кодовой базы, миграция), один агент тонет в контексте. Начинает забывать, что было в начале разговора, путает файлы, теряет фокус.

OpenAI выкатили субагенты в GA 16 марта 2026 — после нескольких недель в превью. Идея простая: вместо одного агента, который делает всё, ты запускаешь нескольких специализированных. Каждый работает в своём потоке, со своим контекстом.

Зачем вообще субагенты

Даже с большими контекстными окнами у моделей есть проблема — context pollution. Полезная информация тонет в логах, стектрейсах и промежуточных результатах. Со временем это перерастает в context rot — модель начинает работать хуже, потому что контекст забит мусором.

Субагенты решают это так:

• Основной агент остаётся сфокусированным — требования, решения, финальный результат
• Шумная работа (exploration, тесты, анализ логов) уходит в дочерние потоки
• Обратно приходят только саммари, а не сырой вывод

Плюс, параллельные задачи реально работают параллельно — это экономит время.

Что понадобится

• Codex CLI или Codex App актуальной версии (субагенты доступны по умолчанию)
• Подписка на OpenAI с доступом к Codex
• Текстовый редактор для TOML-файлов
• Проект с кодом, на котором хочешь попробовать

Субагенты пока не отображаются в IDE Extension — только в CLI и App.

Шаг 1. Попробуй встроенных агентов

Codex идёт с тремя встроенными агентами:

Для старта не нужно ничего конфигурировать. Просто попроси Codex запустить субагенты:

Проверь текущий PR (эта ветка vs main). Запусти по одному агенту
на каждый пункт, дождись всех и сведи результаты:
1. Уязвимости безопасности
2. Качество кода
3. Баги
4. Race conditions
5. Нестабильные тесты
6. Поддерживаемость кода

Codex сам разберётся, что каждый пункт — это отдельный субагент. Дождётся всех и вернёт сводку.

Чтобы переключаться между потоками агентов в CLI, используй /agent. Оттуда видно, что каждый делает и в каком состоянии находится.

Шаг 2. Создай кастомного агента

Встроенные агенты — ок для старта, но по-настоящему интересно становится с кастомными. Каждый описывается TOML-файлом.

Где хранить: - ~/.codex/agents/ — личные агенты (работают везде) - .codex/agents/ — проектные агенты (коммитятся в репо, работают для всех в команде)

Минимальный файл агента — три обязательных поля:

# ~/.codex/agents/reviewer.toml

name = "reviewer"
description = "Ревьюер кода — ищет баги, проблемы безопасности и пропущенные тесты."
developer_instructions = """
Ревьюь код как владелец проекта.
Приоритет: корректность, безопасность, регрессии поведения, пропущенные тесты.
Конкретные находки с шагами воспроизведения. Стилистические замечания — только если за ними прячется реальный баг.
"""

Сохрани файл и всё — Codex увидит агента по имени reviewer. Если имя совпадает со встроенным (например, explorer), твой кастомный агент его перекроет.

Шаг 3. Настрой модель и reasoning

Необязательные поля, но без них кастомные агенты не особо отличаются от встроенных. Главное — можно назначить разным агентам разные модели:

name = "explorer"
description = "Быстрый исследователь кодовой базы — ищет файлы и связи."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Режим исследования. Трассируй реальные пути выполнения, указывай файлы и символы.
Не предлагай фиксы, если родительский агент не попросит.
"""

Как выбирать модель:

Reasoning effort:

Чем выше reasoning — тем дольше ответ и больше токенов. Для exploration-агента low или medium хватит за глаза.

Шаг 4. Собери команду агентов

Самое интересное начинается, когда собираешь нескольких агентов в связку. Покажу на примере ревью PR — тут это прям заходит.

Конфиг проекта (.codex/config.toml):

[agents]
max_threads = 6
max_depth = 1

Исследователь (.codex/agents/pr-explorer.toml):

name = "pr_explorer"
description = "Read-only исследователь для сбора контекста перед ревью."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Режим исследования. Трассируй реальные пути выполнения,
указывай файлы и символы. Не предлагай фиксы.
Быстрый поиск и точечное чтение файлов вместо широких сканов.
"""

Ревьюер (.codex/agents/reviewer.toml):

name = "reviewer"
description = "Ревьюер PR — корректность, безопасность, тестовое покрытие."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Ревьюь код как владелец. Приоритет: корректность, безопасность,
регрессии, пропущенные тесты. Конкретные находки с шагами
воспроизведения. Стилистические замечания — только если за ними
прячется реальный баг.
"""

Исследователь документации (.codex/agents/docs-researcher.toml):

name = "docs_researcher"
description = "Проверяет API и поведение фреймворков через MCP-сервер документации."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Используй MCP-сервер документации для проверки API, опций и
version-specific поведения. Возвращай краткие ответы со ссылками.
Не меняй код.
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Теперь запускай:

Проревьюь эту ветку против main. Пусть pr_explorer найдёт
затронутые пути, reviewer — реальные риски, а docs_researcher
проверит API фреймворков, которые используются в патче.

Codex запустит трёх агентов параллельно, подождёт и соберёт результаты в один ответ. Удобно.

Шаг 5. Настрой никнеймы (опционально)

Когда запущено несколько экземпляров одного агента, в UI они сливаются — непонятно, кто что делает. Никнеймы это решают:

name = "reviewer"
description = "Ревьюер PR."
developer_instructions = "..."
nickname_candidates = ["Atlas", "Delta", "Echo"]

Codex присвоит каждому экземпляру reviewer уникальный никнейм из списка. Это чисто визуальная штука — внутри агент всё равно идентифицируется по name.

Шаг 6. Обработка CSV-батчей (экспериментально)

Отдельная экспериментальная штука — spawn_agents_on_csv. Когда задач много и они однотипные (проревьюить 50 файлов, проверить 100 инцидентов), можно скормить CSV и получить результат в CSV.

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

1. Создаёшь CSV с данными — по строке на задачу
2. Codex запускает по одному субагенту на строку
3. Каждый агент вызывает report_agent_job_result с результатом
4. Результаты собираются в выходной CSV

Пример промпта:

Создай /tmp/components.csv с колонками path,owner — по строке
на каждый фронтенд-компонент.

Затем вызови spawn_agents_on_csv:
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "Проверь {path} (владелец {owner}). Верни JSON
  с ключами path, risk, summary, follow_up через
  report_agent_job_result."
- output_csv_path: /tmp/components-review.csv
- output_schema: объект с обязательными string-полями
  path, risk, summary, follow_up

Если воркер завершится без вызова report_agent_job_result, Codex пометит строку ошибкой в итоговом CSV.

Результат

Если всё сделал правильно, у тебя теперь набор агентов под конкретные задачи. Ревью, exploration и анализ идут одновременно, а основной контекст не забивается промежуточным мусором.

В CLI набери /agent — увидишь все активные потоки. Можно переключаться между ними, останавливать или перенаправлять.

Глобальные настройки

В config.toml есть три параметра, которые стоит знать:

Мне кажется, дефолтный max_depth = 1 — это правильно. Субагенты, которые запускают свои субагенты — это рецепт для неконтролируемых расходов на токены.

Частые ошибки

Субагенты не запускаются. Codex не запускает их сам — нужно явно попросить. Формулировки типа «запусти агентов параллельно», «spawn subagents», «по одному агенту на задачу» работают.

Конфликты при параллельной записи. Если два субагента редактируют один файл, будут проблемы. Для записи оставляй одного агента, остальных сажай в read-only. Вообще параллельные субагенты лучше всего заходят на задачах чтения: exploration, тесты, анализ.

Расход токенов. Каждый субагент — отдельная модельная сессия. Пять параллельных агентов потратят примерно в 5 раз больше токенов, чем один. Для read-only воркеров бери gpt-5.3-codex (~5 кредитов вместо ~7 у gpt-5.4) или gpt-5.1-codex-mini (~1 кредит) для совсем простых задач. gpt-5.3-codex-spark быстрее всех, но доступен только на Pro и тратит отдельный лимит.

FAQ

Субагенты работают в IDE Extension?

Пока нет — только в Codex CLI и Codex App. OpenAI обещают добавить поддержку в IDE Extension, но дат не называют.

Можно ли подключить MCP-серверы к кастомному агенту?

Да. В TOML-файле агента добавь секцию [mcp_servers.имя_сервера] с полем url. Агент получит доступ к инструментам этого сервера.

Чем субагенты в Codex отличаются от Claude Code?

По сути одно и то же: параллельные специализированные агенты. Разница в конфигурации — Codex использует TOML-файлы, Claude Code настраивается через системный промпт. В Codex можно явно задать модель и reasoning effort для каждого агента, что удобнее. Встроенные агенты (explorer, worker) есть у обоих.

Субагенты наследуют права родительского агента?

Да. Sandbox-политика, approval-настройки и runtime-овверайды наследуются от родительской сессии. Но можно переопределить sandbox_mode в TOML-файле конкретного агента — например, поставить read-only для исследователей.

Сколько субагентов можно запустить одновременно?

По умолчанию — 6 (параметр agents.max_threads). Можно увеличить, но учитывай расход токенов и время ожидания.

Что ещё почитать

• 3 паттерна воркфлоу AI-агентов: когда какой использовать — когда нужен single agent, а когда мультиагентная схема
• Codex CLI vs Claude Code: что выбрать для кодинга — детальное сравнение двух CLI-агентов
• AI-агенты в 2026: что реально работает — типы и архитектуры агентов