Как работает Codex: цикл, инструменты, контекст

Когда вы пишете Codex «почини падающий тест», агент делает не один запрос к модели, а десятки: читает файлы, запускает команды, смотрит на результат и решает, что дальше. Понимание этого цикла объясняет почти всё в поведении агента: почему он иногда «забывает» сказанное, почему ему нужны команды для тестов и почему длинная сессия работает хуже свежей.

Агентный цикл

Устройство цикла подробно описал инженер OpenAI Майкл Болин в статье Unrolling the Codex agent loop. Если упростить, ход выглядит так:

1. Ваше сообщение вместе с инструкциями и историей превращается в запрос к модели.
2. Модель отвечает одним из двух способов: либо даёт финальный ответ, либо просит вызвать инструмент — например, выполнить команду в терминале.
3. Обвязка агента (harness) выполняет вызов и добавляет результат к запросу.
4. Модель получает обновлённый запрос, и всё повторяется.

Ход (turn) заканчивается, когда модель выдаёт сообщение для вас. За один ход могут быть сотни вызовов инструментов. Весь разговор — последовательность ходов — называется тредом (thread), в интерфейсе — чатом или сессией.

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

Инструменты

Основные инструменты Codex:

• Shell — выполнение команд: ls, grep, php artisan, npm test, git diff. Через него агент и читает код, и запускает проверки.
• Правка файлов — изменения вносятся патчами, и каждое изменение потом видно в git diff.
• План — для многошаговых задач агент ведёт список шагов и отмечает выполненные.
• Веб-поиск — по умолчанию из кэшированного индекса; живой поиск включается флагом --search.
• MCP-инструменты — всё, что вы подключили через протокол MCP: браузер, база данных, трекер. Об этом — в курсе «Настройка и расширение».

Важная деталь из той же статьи: песочница Codex ограничивает именно его shell-инструмент и запущенные из него процессы. MCP-серверы Codex не изолирует — они сами отвечают за свои ограничения. Поэтому подключать стоит только серверы, которым вы доверяете.

Из чего собирается запрос

Перед вашим первым сообщением в запрос к модели уже попадает много всего. По описанию Болина, порядок такой:

1. Системные инструкции и описание инструментов.
2. Правила песочницы: что можно писать, есть ли сеть, когда спрашивать разрешения.
3. Инструкции проекта — содержимое файлов AGENTS.md из вашего домашнего каталога Codex и из репозитория. Им посвящён урок «AGENTS.md».
4. Описание окружения: текущий каталог, оболочка.
5. Ваше сообщение.

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

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

Контекстное окно

Всё перечисленное занимает контекстное окно модели — ограниченный объём текста, который она видит за раз. В окно попадают и инструкции, и каждый прочитанный файл, и вывод каждой команды. Многословный прогон тестов или чтение большого файла с фикстурами съедают заметную часть окна за один шаг.

Когда окно подходит к пределу, Codex сжимает историю (compaction): старые шаги заменяются сжатым представлением, чтобы освободить место. Сжатие можно запустить и вручную командой /compact. Подробности сжатия и способы экономить окно — в уроке «Контекст».

Что из этого следует:

• Постоянные правила — в AGENTS.md, а не в первом сообщении. Документация Codex прямо называет ошибкой перегружать промпт долговременными правилами.
• Одна сессия — одна задача. Сессия, в которой обсудили три разные темы, хуже справляется с каждой.
• Узкая постановка экономит окно. «Добавь валидацию телефона в компонент формы FeedbackForm» — это пара прочитанных файлов. «Улучши формы на сайте» — десятки.

Вы внутри цикла

Пока агент работает, вы не обязаны ждать. В CLI можно:

• нажать Enter и дописать указание — оно попадёт в текущий ход («не трогай миграции, только модель»);
• нажать Tab — сообщение встанет в очередь и уйдёт следующим ходом;
• прервать агента, если он явно пошёл не туда.

Если действие выходит за границы песочницы — нужна сеть, запись вне проекта, — цикл останавливается и ждёт вашего одобрения. Как это настроить, разберём в уроке «Песочница и одобрения».

Тем, кто хочет глубже — как устроен промпт, кэш и компакция изнутри, — в курсе Harness engineering есть урок «Агентный цикл Codex изнутри».