Субагенты в Codex CLI вышли из превью — параллельные агенты, кастомные TOML-конфиги и CSV batch, за который можно случайно отдать $350

Субагенты в Codex CLI вышли из превью — параллельные агенты, кастомные TOML-конфиги и CSV batch, за который можно случайно отдать $350

OpenAI тихо перевела субагенты в Codex CLI из feature flag в GA. Версия 0.115.0 вышла 16 марта — и теперь любой пользователь Codex может запустить несколько AI-агентов параллельно прямо из терминала. Фича, которую месяцами просили в GitHub Issues, наконец добралась до прода.

TL;DR: Codex CLI 0.115.0 получил субагенты в GA — можно спавнить параллельных агентов для ревью, дебага и исследования кода. Кастомные агенты описываются в TOML-файлах, есть batch-режим через CSV. Но каждый субагент жрёт токены отдельно, и без контроля бюджета можно улететь на сотни долларов за неделю.

Что такое субагенты и зачем они нужны

Проблема, которую решают субагенты, — context pollution. Когда основной агент лезет в 15 файлов, запускает тесты, читает логи — его контекст засоряется промежуточным мусором. Субагент берёт грязную работу на себя и возвращает только выжимку.

На практике это выглядит так: вместо одного агента, который последовательно ревьюит PR, ты запускаешь трёх — один проверяет безопасность, второй гоняет тесты, третий читает документацию. Они работают параллельно и возвращают результаты в основной тред.

Важный нюанс: Codex не спавнит субагенты автоматически. Нужно явно попросить:

Review this branch with parallel subagents. Spawn one for security,
one for tests, one for maintainability. Summarize findings by category.

Или проще: «spawn two agents», «delegate this work in parallel», «use one agent per point».

Три встроенных агента

Из коробки Codex даёт три типа:

• default — универсальный агент, fallback для всего
• worker — заточен под выполнение задач: имплементация, фиксы, рефакторинг
• explorer — read-only исследование кодовой базы, поиск зависимостей, трассировка вызовов

Разница между default и worker размытая — как заметил Simon Willison, «worker, видимо, предназначен для массовых мелких задач», судя по примерам с CSV.

Кастомные агенты через TOML

Самое интересное — можно создать своих агентов. Файлы кладутся в ~/.codex/agents/ (персональные) или .codex/agents/ (проектные):

name = "security_reviewer"
description = "Reviews code for security vulnerabilities, injection risks, and auth issues"
developer_instructions = """
Focus exclusively on security concerns. Check for:
- SQL injection, XSS, command injection
- Authentication and authorization bypass
- Hardcoded secrets and credentials
- Insecure deserialization
Report only confirmed or high-probability issues.
"""
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

Обрати внимание на model = "gpt-5.3-codex-spark" — для субагентов можно использовать более дешёвую и быструю модель, а GPT-5.4 оставить для основного координатора. Это не просто совет — это способ не разориться (подробнее ниже).

Другие опциональные поля: nickname_candidates (отображаемое имя в UI), mcp_servers (подключение MCP-серверов к конкретному агенту), skills.config.

CSV batch processing — киллер-фича для рутины

Экспериментальная, но мощная штука: spawn_agents_on_csv позволяет веерно обработать десятки файлов или задач из CSV:

Process all files in audit.csv — for each row, check the file
at {file_path} for security issues and report findings as JSON.

Параметры: csv_path, instruction (шаблон с ), output_schema (структура JSON-ответа), max_concurrency, max_runtime_seconds. Каждый воркер должен вызвать report_agent_job_result ровно один раз — необработанные строки получают error-статус в выходном CSV.

Для чего реально полезно: массовый аудит кода, миграция конфигов, batch-переименование с проверкой, генерация тестов для списка файлов.

Практические паттерны из документации

PR Review (три агента, все read-only):

• pr_explorer — маппит кодовую базу, собирает контекст
• reviewer — проверяет корректность, безопасность, тестовое покрытие
• docs_researcher — сверяет с документацией через MCP

Frontend Debugging (смешанные права):

• code_mapper — находит нужные code paths (read-only)
• browser_debugger — воспроизводит баг, собирает скриншоты (workspace-write)
• ui_fixer — имплементирует минимальный фикс (default permissions)

Пример промпта для дебага:

Investigate why the settings modal fails to save. Have browser_debugger
reproduce it, code_mapper trace the responsible code path, and ui_fixer
implement the smallest fix once the failure mode is clear.

Конфигурация и лимиты

Глобальные настройки в [agents] секции конфига:

• max_threads — максимум параллельных тредов, по умолчанию 6
• max_depth — глубина вложенности агентов, по умолчанию 1 (агент не может спавнить субагента)
• job_max_runtime_seconds — таймаут на воркера в CSV-режиме

Субагенты наследуют sandbox-политику родительской сессии. Если в основном треде включён --yolo, дети тоже получат yolo. Кастомные агенты могут переопределить это — например, явно выставить read-only.

Команда /agent позволяет переключаться между активными тредами и инспектировать работу субагентов. Запросы на approval могут всплывать из фоновых тредов — нажми o, чтобы открыть исходный тред перед одобрением.

Подводные камни

Токены умножаются, а не складываются. Каждый субагент — это отдельный контекст с отдельными вызовами модели. Три субагента на ревью PR — это не 1× стоимость, а ближе к 3×. Пользователь на GitHub сообщил, что превысил бюджет Pro-плана на $350 за неделю. OpenAI в ответ сказал, что токены тарифицируются линейно и предложил использовать дешёвые модели для субагентов — но не добавил ни бюджетного лимита на сессию, ни предупреждения о стоимости перед запуском.

Нет прогноза стоимости. Перед запуском субагентов Codex не показывает, сколько примерно это будет стоить. Ты узнаёшь цену постфактум. Для Pro-плана это терпимо, но на API-тарификации — опасно.

Write-конфликты в параллели. Документация прямо предупреждает: субагенты лучше всего работают для read-heavy задач. Если два агента одновременно правят один файл — получишь конфликты и координационный overhead, который съест весь выигрыш от параллелизма.

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

TUI зависает. В changelog 0.115.0 отдельно упомянут фикс «tui freeze when sub-agents are present» — значит, проблема была достаточно массовой, чтобы попасть в release notes. Полностью ли решена — вопрос.

Альтернативы

• Claude Code Agent Teams — аналогичная система от Anthropic: субагенты с типами explorer, worker, default. Глубже интегрирована с терминалом, богаче система пермишенов (5 уровней автономности), но привязана к моделям Claude и тоже пропорционально жрёт лимиты подписки. На Max-плане за $200/мес ощущается болезненнее, потому что лимиты и так тесные.

• Gemini CLI — Google-вский open-source CLI с 1M контекстом по умолчанию и бесплатным тиром (1000 запросов/день на Flash). Deep Think mode для сложного reasoning. Субагенты есть, но менее зрелые. Главный плюс — цена: gpt-5.3-codex-spark стоит в разы дороже, чем Gemini Flash для аналогичных задач. Минус — first-pass correctness около 85-88% против ~95% у Claude и Codex.

• Goose (Block) — open-source фреймворк с нативной поддержкой субагентов. Можно подключить любую модель через любого провайдера. Нет привязки к подписке — платишь только за API. Для тех, кто хочет полный контроль над оркестрацией.

Вердикт

Субагенты в Codex — не революция, а выравнивание с Claude Code, который запустил Agent Teams раньше. Реальная ценность — в TOML-конфигах кастомных агентов и CSV batch processing: если у тебя 50 файлов на аудит или миграцию, это экономит часы. Но без бюджетных лимитов на сессию запускать субагенты на API-тарификации — как дать ребёнку кредитку. Если сидишь на Pro/Plus плане с фиксированной ценой — пробуй смело, но следи за лимитами. Если платишь за токены — ставь gpt-5.3-codex-spark для субагентов и начинай с read-only задач.

Как попробовать

1. Обнови Codex CLI: npm i -g @openai/codex@0.115.0
2. Создай папку .codex/agents/ в проекте и добавь TOML-файл кастомного агента (пример выше)
3. Запусти Codex и попроси: «spawn two agents — one to explore the auth module, one to check for security issues»
4. Переключайся между тредами через /agent
5. Документация: developers.openai.com/codex/subagents