Dev Tools

Мультиагенты в OpenAI Codex — настройка и примеры

Пошаговая настройка multi-agent в OpenAI Codex — от включения экспериментального флага до создания своих ролей агентов.

Pavel Matveev

Pavel Matveev

— 4 min read
Мультиагенты в OpenAI Codex — настройка и примеры
TL;DR: Настраиваем мультиагентный режим в OpenAI Codex CLI — несколько AI-агентов работают параллельно над разными частями задачи. Включение занимает одну строчку в конфиге, а дальше можно создавать собственные роли с разными моделями и инструкциями.

Codex от OpenAI научился запускать несколько агентов одновременно. Вместо того чтобы последовательно проверять код на баги, потом на безопасность, потом на качество — можно отправить три агента параллельно. Каждый сфокусируется на своей задаче, а Codex соберёт результаты в один ответ. Больше всего это пригодится для code review и исследования больших кодовых баз.

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

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

  • OpenAI Codex CLI — установленный и авторизованный. Если ещё нет — npm install -g @openai/codex или brew install codex
  • Подписка ChatGPT (Plus, Pro, Business, Enterprise) или API-ключ OpenAI
  • Git-репозиторий — мультиагенты работают в контексте проекта, так что нужна реальная кодовая база
  • macOS, Windows или Linux — CLI работает на всех трёх

Шаг 1. Включить multi-agent в конфигурации

Мультиагентный режим по умолчанию выключен — это экспериментальная фича. Есть два способа включить.

Через CLI:

Запусти Codex и выполни команду /experimental. В списке найди Multi-agents и включи. После этого перезапусти Codex.

Через конфиг-файл:

Открой ~/.codex/config.toml (или создай, если его нет) и добавь:

[features]
multi_agent = true

Для проектного конфига — положи файл .codex/config.toml в корень репозитория. Так мультиагенты будут включены только для конкретного проекта.

После изменения конфига перезапусти Codex.

Шаг 2. Запустить первый мультиагентный промпт

Теперь проверим, что всё работает. Открой Codex в директории своего проекта и отправь такой промпт:

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

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

Не обязательно просить мультиагентов явно. Codex сам решает, когда имеет смысл распараллелить задачу. Но ты можешь форсировать это фразой «запусти отдельного агента на каждый пункт» или «spawn one agent per point».

Шаг 3. Управлять агентами в реальном времени

Пока агенты работают, можно за ними подглядывать:

  • /agent — переключиться между активными потоками агентов и посмотреть, что происходит в каждом
  • Написать Codex прямо в чате — попросить остановить конкретного агента, перенаправить его или закрыть завершённые потоки

Мультиагентная активность пока видна только в CLI. Поддержка в десктопном приложении и IDE-расширении — в планах OpenAI.

Шаг 4. Настроить свои роли агентов

Дефолтные агенты — это ок, но самое полезное — свои роли. Можно задать каждому агенту отдельную модель, уровень доступа и инструкции.

Роли настраиваются в секции [agents] конфиг-файла ~/.codex/config.toml:

[agents]
max_threads = 4

[agents.default]
description = "Универсальный помощник."

[agents.reviewer]
description = "Ищет проблемы безопасности, баги и риски в тестах."
config_file = "agents/reviewer.toml"

[agents.explorer]
description = "Быстрый исследователь кодовой базы для read-heavy задач."
config_file = "agents/explorer.toml"

Параметр max_threads ограничивает количество одновременно работающих агентов. По умолчанию Codex сам решает, сколько запускать.

Теперь создадим конфиг-файлы для каждой роли.

Файл ~/.codex/agents/reviewer.toml:

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
developer_instructions = "Фокусируйся на критичных проблемах. Пиши тесты для проверки гипотез перед тем, как сообщать о баге. При нахождении уязвимостей описывай конкретные шаги воспроизведения."

Файл ~/.codex/agents/explorer.toml:

model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

Explorer здесь в режиме read-only — он может только читать файлы, но не трогать их. Для исследования кода это разумно: и случайно ничего не сломает, и модель можно взять подешевле.

Что можно переопределить в роли

Параметр Зачем
model Выбрать модель — быструю для простых задач, мощную для сложных
model_reasoning_effort Уровень рассуждений: low, medium, high
sandbox_mode Ограничить доступ, например read-only
developer_instructions Кастомные инструкции для роли

Всё, что не указано в конфиге роли, наследуется от родительской сессии.

Шаг 5. Создать проектные роли

Роли можно определять не только глобально, но и на уровне проекта — в файле .codex/config.toml в корне репозитория. Это удобно, когда разным проектам нужны разные агенты.

Например, для фронтенд-проекта:

[agents.stylelint]
description = "Проверяет CSS и стили на соответствие код-стайлу."
config_file = "agents/stylelint.toml"

[agents.a11y]
description = "Проверяет доступность компонентов."
config_file = "agents/a11y.toml"

А для бэкенда на Python:

[agents.typing]
description = "Проверяет типизацию и mypy-совместимость."
config_file = "agents/typing.toml"

[agents.perf]
description = "Ищет проблемы производительности и N+1 запросы."
config_file = "agents/perf.toml"

Проектные конфиги загружаются только для доверенных проектов — Codex спросит при первом открытии.

Результат

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

На моих тестах code review с 6 параллельными агентами отработал примерно в 3 раза быстрее, чем последовательные промпты. Правда, и токенов потратил заметно больше — каждый агент работает в своей сессии. Но когда нужно быстро разобраться в большом PR, это того стоит.

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

Мультиагенты не запускаются — скорее всего, фича не включена. Проверь ~/.codex/config.toml: там должна быть секция [features] с multi_agent = true. И не забудь перезапустить Codex после правки конфига.

Агент падает с ошибкой доступа — субагенты работают в неинтерактивном режиме. Если агент пытается сделать что-то, требующее твоего одобрения, действие просто упадёт. Тут два варианта: заранее разрешить нужные действия в approval_policy или пометить агента как read-only.

Конфиг-файл роли не загружается — проверь пути. Относительные пути в config_file считаются от того config.toml, где определена роль. Если роль в ~/.codex/config.toml ссылается на agents/reviewer.toml, файл должен лежать в ~/.codex/agents/reviewer.toml.

FAQ

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

По умолчанию Codex сам определяет лимит. Ты можешь ограничить его параметром agents.max_threads в конфиге. На практике 4-6 параллельных агентов — разумный максимум, дальше начинают расти задержки.

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

Пока нет. На февраль 2026 мультиагентная активность видна только в CLI. OpenAI обещают поддержку в приложении и IDE-расширении в ближайших обновлениях.

Можно ли переопределить встроенные роли default, worker и explorer?

Да. Если создать роль с таким же именем — твоя версия приоритетнее встроенной. Например, можно назначить explorer более дешёвую модель или добавить кастомные инструкции.

Мультиагенты стоят дороже обычных запросов?

Каждый агент — это отдельная сессия с моделью, так что да, расход токенов растёт пропорционально количеству агентов. Чтобы сэкономить, используй быстрые модели вроде gpt-5.3-codex-spark для простых задач типа исследования кода.

Как остановить зависшего агента?

Напиши в чат Codex просьбу остановить конкретный агент, или используй /agent для просмотра и управления активными потоками.

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