> ## Content Index > Fetch the complete content index at: https://matveev.tech/llms.txt > Use this file to discover other available public pages before exploring further. # Субагенты в Codex: настраиваем AI-команду - URL: https://matveev.tech/codex-subagents-tutorial/ - Published: 2026-03-17T18:51:55.000Z - Updated: 2026-03-17T18:51:55.000Z - Description: Разбираю фичу субагентов в Codex — как создать кастомных агентов через TOML, запускать параллельно и не утонуть в токенах. - Author: Pavel Matveev - Tags: OpenAI, Dev Tools, Гайд, Агенты, CLI > TL;DR: Субагенты в Codex позволяют разбивать задачи на параллельные потоки — каждый со своей моделью, инструкциями и sandbox-режимом. Настраиваются через TOML-файлы, работают из коробки в CLI и приложении. Разбираю, как это настроить и когда это реально полезно. Codex умел работать как один агент — ты даёшь задачу, он выполняет. Но когда задача большая (ревью PR из 30 файлов, исследование кодовой базы, миграция), один агент тонет в контексте. Начинает забывать, что было в начале разговора, путает файлы, теряет фокус. OpenAI [выкатили субагенты в GA 16 марта 2026](https://developers.openai.com/codex/subagents?ref=matveev.tech) — после нескольких недель в превью. Идея простая: вместо одного агента, который делает всё, ты запускаешь нескольких специализированных. Каждый работает в своём потоке, со своим контекстом. ## Зачем вообще субагенты Даже с большими контекстными окнами у моделей есть проблема — **context pollution**. Полезная информация тонет в логах, стектрейсах и промежуточных результатах. Со временем это перерастает в **context rot** — модель начинает работать хуже, потому что контекст забит мусором. Субагенты решают это так: - Основной агент остаётся сфокусированным — требования, решения, финальный результат - Шумная работа (exploration, тесты, анализ логов) уходит в дочерние потоки - Обратно приходят только саммари, а не сырой вывод Плюс, параллельные задачи реально работают параллельно — это экономит время. ## Что понадобится - **Codex CLI** или **Codex App** актуальной версии (субагенты доступны по умолчанию) - Подписка на OpenAI с доступом к Codex - Текстовый редактор для TOML-файлов - Проект с кодом, на котором хочешь попробовать Субагенты пока не отображаются в IDE Extension — только в CLI и App. ## Шаг 1\. Попробуй встроенных агентов Codex идёт с тремя встроенными агентами: | Агент | Что делает | | -------- | ------------------------------------------------ | | default | Основной агент общего назначения | | worker | Заточен под выполнение задач — реализация, фиксы | | explorer | Только чтение — исследование кодовой базы | Для старта не нужно ничего конфигурировать. Просто попроси Codex запустить субагенты: ``` Проверь текущий PR (эта ветка vs main). Запусти по одному агенту на каждый пункт, дождись всех и сведи результаты: 1. Уязвимости безопасности 2. Качество кода 3. Баги 4. Race conditions 5. Нестабильные тесты 6. Поддерживаемость кода ``` Codex сам разберётся, что каждый пункт — это отдельный субагент. Дождётся всех и вернёт сводку. Чтобы переключаться между потоками агентов в CLI, используй `/agent`. Оттуда видно, что каждый делает и в каком состоянии находится. ## Шаг 2\. Создай кастомного агента Встроенные агенты — ок для старта, но по-настоящему интересно становится с кастомными. Каждый описывается TOML-файлом. Где хранить: - `~/.codex/agents/` — личные агенты (работают везде) - `.codex/agents/` — проектные агенты (коммитятся в репо, работают для всех в команде) Минимальный файл агента — три обязательных поля: ```toml # ~/.codex/agents/reviewer.toml name = "reviewer" description = "Ревьюер кода — ищет баги, проблемы безопасности и пропущенные тесты." developer_instructions = """ Ревьюь код как владелец проекта. Приоритет: корректность, безопасность, регрессии поведения, пропущенные тесты. Конкретные находки с шагами воспроизведения. Стилистические замечания — только если за ними прячется реальный баг. """ ``` Сохрани файл и всё — Codex увидит агента по имени `reviewer`. Если имя совпадает со встроенным (например, `explorer`), твой кастомный агент его перекроет. ## Шаг 3\. Настрой модель и reasoning Необязательные поля, но без них кастомные агенты не особо отличаются от встроенных. Главное — можно назначить разным агентам разные модели: ```toml name = "explorer" description = "Быстрый исследователь кодовой базы — ищет файлы и связи." model = "gpt-5.3-codex-spark" model_reasoning_effort = "medium" sandbox_mode = "read-only" developer_instructions = """ Режим исследования. Трассируй реальные пути выполнения, указывай файлы и символы. Не предлагай фиксы, если родительский агент не попросит. """ ``` Как выбирать модель: | Модель | Когда использовать | Нюанс | | ------------------- | -------------------------------------------- | -------------------------------------- | | gpt-5.4 | Основной агент, сложные задачи, координация | \~7 кредитов/сообщение | | gpt-5.3-codex | Субагенты-воркеры, exploration, суммаризация | \~5 кредитов/сообщение | | gpt-5.3-codex-spark | Максимальная скорость для лёгких задач | Только Pro ($200/мес), отдельный лимит | | gpt-5.1-codex-mini | Простые рутинные задачи | \~1 кредит/сообщение, самый экономный | Reasoning effort: | Уровень | Когда | | ------- | ---------------------------------------- | | high | Сложная логика, edge cases, безопасность | | medium | Большинство задач (дефолт) | | low | Простые задачи, где важна скорость | Чем выше reasoning — тем дольше ответ и больше токенов. Для exploration-агента `low` или `medium` хватит за глаза. ## Шаг 4\. Собери команду агентов Самое интересное начинается, когда собираешь нескольких агентов в связку. Покажу на примере ревью PR — тут это прям заходит. Конфиг проекта (`.codex/config.toml`): ```toml [agents] max_threads = 6 max_depth = 1 ``` Исследователь (`.codex/agents/pr-explorer.toml`): ```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`): ```toml name = "reviewer" description = "Ревьюер PR — корректность, безопасность, тестовое покрытие." model = "gpt-5.4" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ Ревьюь код как владелец. Приоритет: корректность, безопасность, регрессии, пропущенные тесты. Конкретные находки с шагами воспроизведения. Стилистические замечания — только если за ними прячется реальный баг. """ ``` Исследователь документации (`.codex/agents/docs-researcher.toml`): ```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 они сливаются — непонятно, кто что делает. Никнеймы это решают: ```toml 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` есть три параметра, которые стоит знать: | Параметр | По умолчанию | Что делает | | --------------------------------- | ------------ | -------------------------------------------------------------------- | | agents.max\_threads | 6 | Максимум одновременных потоков агентов | | agents.max\_depth | 1 | Глубина вложенности (1 = субагент не может запускать свои субагенты) | | agents.job\_max\_runtime\_seconds | 1800 | Таймаут на воркера в CSV-батче | Мне кажется, дефолтный `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-агентов: когда какой использовать](https://blog.matveev.tech/patterny-workflow-ai-agentov/?ref=matveev.tech) — когда нужен single agent, а когда мультиагентная схема - [Codex CLI vs Claude Code: что выбрать для кодинга](https://blog.matveev.tech/codex-cli-vs-claude-code-sravnenie/?ref=matveev.tech) — детальное сравнение двух CLI-агентов - [AI-агенты в 2026: что реально работает](https://blog.matveev.tech/ai-agenty-2026-tipy-arhitektury/?ref=matveev.tech) — типы и архитектуры агентов