Команда codex exec в Codex CLI: назначение, синтаксис и примеры автоматизации

Команда codex exec в Codex CLI служит для запуска Codex в неинтерактивном режиме: вы передаёте ему задачу, а он выполняет её без привычного диалога в терминале, возвращая результат в стандартный вывод или в файл. Это особенно удобно для скриптов, автоматических проверок, CI/CD, анализа репозиториев и любых сценариев, где отвечать на вопросы агента вручную некому.

Интерактивный режим хорош для совместной работы, а codex exec превращает Codex в управляемый этап автоматизированного процесса: получил инструкции, выполнил задачу, выдал результат с предсказуемым форматом.

При этом неинтерактивный запуск — это не просто сокращённая форма обычной команды. Нужно заранее продумать, откуда Codex возьмёт инструкции, в какой директории будет работать, какие права получит, как будет выглядеть вывод и что произойдёт при ошибке. Ниже разберём синтаксис codex exec, режимы песочницы и подтверждений, передачу больших промптов, структурированный вывод, работу в скриптах и практические варианты интеграции с CI/CD.

Обзор команды codex exec

Команда codex exec предназначена для выполнения одной задачи в рамках одного запуска. В отличие от обычного codex, который открывает интерактивный интерфейс, она не ждёт постоянного участия пользователя: получает запрос, анализирует окружение, при доступных разрешениях выполняет действия и завершает процесс.

Главное отличие неинтерактивного запуска — ответственность за решения переносится из диалога с пользователем в параметры команды, текст задания и настройки окружения.

Упрощённо процесс выглядит так:

1. терминал или CI-система запускает codex exec;
2. Codex получает текстовую инструкцию из аргумента командной строки или стандартного ввода;
3. агент работает в текущем каталоге либо в каталоге, указанном через параметр --cd;
4. доступные изменения ограничиваются выбранной песочницей и политикой подтверждений;
5. результат выводится в терминал, передаётся как поток событий JSON или записывается в файл.

Сценарий	Почему подходит codex exec	Типичный результат
Разовая правка кода	Не нужно открывать интерактивный интерфейс	Изменённые файлы и итоговое сообщение
Проверка pull request	Команду можно вызвать из CI	Текстовый или JSON-отчёт
Генерация документации	Инструкции удобно хранить в файле	Обновлённые Markdown-файлы
Анализ репозитория	Ответ можно сохранить и обработать дальше	Отчёт в stdout или отдельном файле
Автоматический рефакторинг	Можно заранее определить рабочую директорию и права	Изменения в рабочем дереве

Важно учитывать, что exec не означает «выполнить любую команду без ограничений». Доступ Codex определяется конфигурацией CLI, выбранным режимом песочницы, политикой подтверждений и возможностями конкретной версии. Перед использованием в автоматизации полезно проверить локальную справку командой codex exec --help: набор опций может расширяться, а отдельные параметры способны зависеть от установленной версии.

Синтаксис команды codex exec

Базовая форма команды выглядит так:

codex exec [OPTIONS] [PROMPT]

PROMPT — необязательная инструкция для агента, а OPTIONS — параметры, определяющие модель, рабочую директорию, разрешения, формат вывода и другие свойства запуска. Если текст задачи не передан последним аргументом, его можно подать через стандартный ввод.

Часть синтаксиса	Обязательность	Назначение
codex exec	Обязательная	Запуск Codex в неинтерактивном режиме
[OPTIONS]	Необязательная	Настройка режима выполнения
[PROMPT]	Необязательная	Текст задания, переданный аргументом
Стандартный ввод	Необязательный альтернативный способ	Передача длинной или сгенерированной инструкции

Аргумент PROMPT

Этот аргумент содержит естественно-языковую инструкцию для Codex. В неё можно включить цель, ограничения, перечень проверок, ожидаемый формат результата и указания о том, какие файлы разрешено изменять.

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

codex exec "Проверь проект, найди очевидные ошибки в обработке исключений и подготовь краткий отчёт без изменения файлов."

Способ передачи	Когда использовать	Особенность
Один аргумент в кавычках	Короткая команда	Прост в ручном запуске
Here-document	Многострочная инструкция	Хорошо читается в скрипте
Перенаправление файла	Большой или версионируемый промпт	Инструкции можно хранить рядом с проектом
Конвейер через stdin	Динамически собранный запрос	Удобно для CI и генераторов заданий

Опция --cd

Параметр --cd задаёт рабочую директорию для запуска. Это полезно, когда скрипт вызывается не из корня репозитория или когда нужно явно исключить неоднозначность с текущим каталогом shell.

codex exec --cd ./backend "Изучи сервисы в этом каталоге и предложи план оптимизации запросов."

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

Вариант пути	Плюсы	Риск	Рекомендация
./project	Переносимость внутри репозитория	Зависит от текущего каталога	Использовать после явного cd
$GITHUB_WORKSPACE	Удобен в CI	Зависит от переменной среды	Проверять, что переменная задана
Абсолютный путь	Максимальная однозначность	Меньшая переносимость	Подходит для локальных системных скриптов

Опция --add-dir

--add-dir добавляет каталог, доступный Codex в рамках рабочего окружения. Параметр полезен, когда основная рабочая директория одна, но для задачи требуется чтение материалов из другого каталога.

codex exec --cd ./app --add-dir ./shared "Сравни настройки приложения с общими конфигурациями и укажи несовпадения."

Добавляйте только те каталоги, которые действительно нужны задаче. Чем шире область доступа, тем сложнее контролировать, какие файлы агент анализирует или изменяет. Особенно осторожно следует обращаться с домашним каталогом, каталогами секретов и общими рабочими пространствами.

Опция --model

Параметр --model позволяет явно выбрать модель, если установленная конфигурация и доступный аккаунт поддерживают такой выбор. Конкретные допустимые идентификаторы зависят от версии Codex CLI и доступной конфигурации.

codex exec --model gpt-5 "Проанализируй архитектуру проекта и выдели наиболее рискованные места."

Не стоит без проверки переносить имя модели из одного окружения в другое. В CI выбранная модель может быть недоступна, переименована или ограничена политикой организации. Для переносимых скриптов часто лучше полагаться на профиль конфигурации либо задавать модель через переменную среды и предварительно проверять её доступность.

Подход	Преимущество	Когда уместен
Модель по умолчанию	Меньше жёстко заданных зависимостей	Для обычных локальных задач
Явный --model	Предсказуемость характеристик запуска	Для воспроизводимых пайплайнов
Профиль через --profile	Централизованная настройка	Для нескольких окружений и команд

Опция --profile

Параметр --profile выбирает профиль из конфигурации Codex. Профиль может заранее содержать модель, режимы и другие настройки, поэтому команда становится короче, а параметры можно менять централизованно.

codex exec --profile ci-review "Проведи проверку изменений и верни только список блокирующих проблем."

Профили особенно полезны для разделения локального и автоматического запуска. Например, профиль разработчика может быть ориентирован на подробную работу в рабочем каталоге, а профиль CI — на чтение файлов и формирование отчёта без самостоятельного изменения проекта.

Опция --sandbox

--sandbox выбирает режим песочницы. В актуальном интерфейсе Codex CLI используются режимы read-only, workspace-write и danger-full-access. Они определяют, какие операции с файловой системой и окружением допускаются во время выполнения.

Режим	Что обычно разрешает	Подходящий сценарий	Уровень риска
read-only	Чтение и анализ доступных файлов	Аудит, ревью, подготовка отчёта	Низкий
workspace-write	Изменения в рабочей области с ограничениями	Рефакторинг, генерация файлов, исправление тестов	Средний
danger-full-access	Доступ без обычных ограничений песочницы	Только специально контролируемая среда	Высокий

Для анализа без изменений предпочтителен read-only. Если задача действительно предполагает правки, обычно разумнее начать с workspace-write. Режим danger-full-access не следует включать просто потому, что «так быстрее»: он увеличивает последствия ошибки в инструкции, зависимости или самом проекте.

Опция --ask-for-approval

--ask-for-approval задаёт политику подтверждений. В зависимости от выбранного значения Codex может запрашивать разрешение на действия, делать это только при ошибке или не запрашивать его вообще. Для конкретных допустимых значений и поведения лучше обращаться к справке установленной версии: политика подтверждений тесно связана с режимом запуска и песочницей.

codex exec --ask-for-approval on-failure --sandbox workspace-write "Исправь failing-тесты и запусти относящиеся к ним проверки."

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

Опция --full-auto

--full-auto — удобный сокращённый режим для автоматического выполнения в рабочей области. Он предназначен для сценариев, где Codex должен самостоятельно выполнять разрешённые действия без постоянного запроса подтверждений, но при этом не получает безграничный доступ ко всей системе.

codex exec --full-auto "Обнови документацию по публичным функциям и проверь форматирование Markdown."

Название параметра не означает абсолютную безопасность и не отменяет необходимости проверять изменения. Это скорее удобный пресет для автоматизации внутри рабочего каталога. Если требуется точный контроль, лучше явно указывать --sandbox и политику подтверждений, чтобы намерение команды было видно из самого скрипта.

Опция --dangerously-bypass-approvals-and-sandbox

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

codex exec --dangerously-bypass-approvals-and-sandbox "Выполни подготовленную миграцию в тестовом изолированном окружении."

Использовать такой режим в обычном репозитории, на рабочем ноутбуке или в CI с непроверенными входными данными крайне нежелательно. Если команда получает часть инструкции из issue, pull request или внешнего API, злоумышленник теоретически может попытаться встроить в неё вредоносные указания. Изоляция здесь важнее удобства.

Опция --skip-git-repo-check

По умолчанию Codex может проверять, находится ли рабочая директория в Git-репозитории. Параметр --skip-git-repo-check отключает эту проверку и позволяет запускать задачу в каталоге, который не является Git-репозиторием.

mkdir -p ./temporary-input
codex exec --cd ./temporary-input --skip-git-repo-check "Проанализируй файлы в каталоге и составь их краткое описание."

Опция полезна для временных каталогов, распакованных архивов и рабочих областей, где Git намеренно отсутствует. Однако при ревью кода её не стоит добавлять автоматически: проверка репозитория помогает убедиться, что Codex работает именно там, где ожидает оператор.

Опция --image

Параметр --image позволяет передать одно или несколько изображений в задачу, если такая возможность поддерживается текущей конфигурацией и моделью. Это может быть полезно при анализе скриншотов интерфейса, диаграмм, макетов или сообщений об ошибках.

codex exec --image ./artifacts/login-error.png "Определи, какие элементы интерфейса на скриншоте выглядят сломанными, и предложи изменения в CSS."

Изображение не заменяет текстовую постановку задачи. Лучше описать, что именно требуется проверить: визуальное соответствие макету, читаемость сообщения, расположение элементов или возможную причину дефекта.

Опция --json

--json переводит вывод в поток JSON-событий. Это основной вариант для программной обработки, когда результат должен читать не человек, а другой скрипт. В потоке могут присутствовать события о ходе выполнения, сообщениях агента, действиях и финальном результате.

codex exec --json "Проверь проект и сообщи о найденных проблемах." > codex-events.jsonl

Не следует считать весь вывод одним JSON-объектом без проверки формата: поток обычно организован построчно, поэтому его часто называют JSONL. Автоматический обработчик должен уметь пропускать неизвестные типы событий и отдельно находить финальное сообщение, а не зависеть от случайного порядка второстепенных событий.

Формат	Для кого	Преимущество	Сложность
Обычный текст	Человек в терминале	Легко читать	Труднее надёжно парсить
--json	Скрипт или CI	Структурированные события	Нужно обрабатывать поток
--output-last-message	Следующий этап пайплайна	Отдельный финальный ответ	Не содержит весь журнал событий
--output-schema	Машинно проверяемый результат	Заданный формат ответа	Требует корректной JSON-схемы

Опция --output-last-message

Параметр --output-last-message записывает последнее сообщение Codex в указанный файл. Это удобно, если поток выполнения нужен для логов, а итоговый текст — для последующего шага скрипта.

codex exec --output-last-message ./artifacts/summary.txt "Проанализируй изменения и дай итоговую оценку качества."

Файл с последним сообщением не следует путать с полным журналом. Если требуется расследовать, какие действия выполнял агент, сохраняйте также стандартный вывод или используйте --json. Итоговый файл лучше помещать в каталог артефактов CI, а не в рабочее дерево проекта.

Опция --output-schema

--output-schema задаёт JSON-схему для структурированного финального результата. Такой подход полезен, когда следующий этап автоматизации ожидает поля вроде passed, issues или recommendation, а не свободный текст.

codex exec --json --output-schema ./schemas/review-result.json "Проведи ревью и заполни результат строго по схеме."

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

Опция --color

--color управляет цветным выводом. Обычно применяются значения always, never и auto. Для логов CI чаще выбирают never, чтобы управляющие ANSI-последовательности не попадали в артефакты и сообщения системы сборки.

codex exec --color never "Составь краткий отчёт о структуре проекта."

В интерактивном терминале auto обычно удобнее: цвета используются, когда вывод направлен на терминал, и отключаются при перенаправлении. Для машинного парсинга важнее использовать --json, а не пытаться извлекать смысл из раскрашенного текста.

Опция --config

--config позволяет передавать точечные переопределения конфигурации в формате key=value. Это удобно для единичного запуска, когда не хочется изменять основной конфигурационный файл или создавать отдельный профиль.

codex exec --config model="gpt-5" "Проанализируй исходный код и перечисли потенциальные проблемы."

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

Опции --enable и --disable

Параметры --enable и --disable включают или отключают отдельные возможности, доступные в конкретной версии Codex CLI. Их набор зависит от поддерживаемых функций и может меняться, поэтому названия возможностей нужно сверять через codex exec --help и документацию установленного релиза.

codex exec --enable some-feature "Выполни задачу с включённой возможностью, если она доступна в текущей версии CLI."

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

Как передавать инструкции без интерактивного интерфейса

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

Хорошая инструкция для автоматизации отвечает не только на вопрос «что сделать», но и на вопросы «где сделать», «чего не делать» и «как понять, что задача завершена».

Практичная структура промпта может выглядеть так:

• Контекст: что представляет собой проект или набор файлов.
• Цель: конкретный ожидаемый результат.
• Область: какие каталоги и файлы можно анализировать или изменять.
• Ограничения: что запрещено менять, какие зависимости нельзя добавлять.
• Проверки: какие тесты, линтеры или команды следует запустить.
• Формат ответа: обычный текст, краткий отчёт или структура по схеме.

cat <<'PROMPT' | codex exec --sandbox workspace-write
Контекст: это Python-сервис в текущем репозитории.

Задача:
1. Найди функции с дублирующейся логикой валидации.
2. Вынеси повторяющийся код в небольшой общий модуль.
3. Не меняй публичные имена функций и формат ответов API.
4. Добавь или обнови тесты для изменённых случаев.
5. Запусти относящиеся к задаче тесты.

В финальном сообщении укажи изменённые файлы и выполненные проверки.
PROMPT

Для больших инструкций полезно хранить промпты как обычные файлы. Это позволяет проводить code review самих требований, версионировать их и переиспользовать в нескольких пайплайнах.

Источник инструкции	Плюсы	Минусы	Рекомендация
Аргумент командной строки	Коротко и быстро	Плохо подходит для многострочного текста	Для простых задач
Here-document	Удобно читать в shell-скрипте	Нужно учитывать синтаксис оболочки	Для локальных и CI-скриптов
Файл промпта	Версионирование и повторное использование	Появляется дополнительный файл	Для стабильных процессов
Сгенерированный stdin	Можно добавлять сведения о diff и окружении	Есть риск передать лишние данные	Для динамического анализа

Пример: инструкция из файла

Файл с промптом удобен, когда задание длинное, регулярно повторяется и должно изменяться независимо от shell-скрипта.

cat prompts/review.md | codex exec --json --output-last-message artifacts/review.txt

В таком варианте файл prompts/review.md может быть частью репозитория, а итоговый отчёт — артефактом сборки. Если инструкция содержит переменные, их лучше подставлять явно и безопасно, не позволяя данным из внешнего источника незаметно изменить смысл задания.

Пример: передача diff в задачу

Для ревью конкретных изменений можно передать diff через стандартный ввод вместе с поясняющей инструкцией. Это снижает объём лишнего контекста, но не отменяет необходимости дать Codex доступ к репозиторию, если он должен сопоставить изменения с исходными файлами.

{
  printf '%sn' 'Проведи ревью следующего diff. Ищи ошибки, регрессии и проблемы безопасности. Не исправляй файлы.'
  git diff --cached
} | codex exec --sandbox read-only --output-last-message artifacts/review.txt

Перед отправкой diff убедитесь, что в нём нет токенов, паролей, персональных данных и других секретов. Git-дифф иногда раскрывает больше, чем кажется, особенно после изменения конфигурации.

Вывод, коды завершения и обработка результатов

Автоматизация должна учитывать не только текст ответа, но и код завершения процесса. Успешно напечатанный ответ ещё не гарантирует, что задача выполнена в требуемом смысле, а ненулевой код завершения означает, что запуск нельзя считать штатно завершившимся.

В CI полезно разделять технический успех запуска и содержательный результат проверки: первое сообщает shell, второе должен определить ваш обработчик отчёта.

Минимальная схема обработки выглядит так:

1. запустить codex exec;
2. сохранить stdout и stderr;
3. проверить код завершения;
4. при JSON-режиме разобрать события;
5. извлечь итоговое сообщение или структурированный результат;
6. решить, должен ли pipeline завершиться успешно.

set -o pipefail

if codex exec --json 
  --output-last-message artifacts/last-message.txt 
  "Проверь проект и сформируй итоговый отчёт." 
  > artifacts/codex-events.jsonl 2> artifacts/codex-error.log
then
  echo "Codex завершил запуск успешно"
else
  echo "Codex завершился с ошибкой" >&2
  exit 1
fi

Не стоит строить надёжный процесс на поиске фразы вроде «всё хорошо» в обычном тексте. Формулировки модели могут меняться. Если решение должно быть машинным, используйте схему с явным булевым полем, например passed, и дополнительно валидируйте JSON.

Пример: сохранение обычного отчёта

Для простого внутреннего скрипта может быть достаточно сохранить финальный ответ в файл и вывести его в консоль.

mkdir -p artifacts
codex exec --output-last-message artifacts/codex-summary.md 
  "Проведи аудит документации. Перечисли устаревшие разделы и предложи конкретные исправления."
cat artifacts/codex-summary.md

Такой вариант удобен человеку, но не подходит для строгого автоматического решения. Если отчёт используется следующим программным шагом, добавьте JSON-вывод или отдельную схему результата.

Пример: разбор JSONL-событий

Поскольку JSON-режим может выдавать несколько событий, обработчик должен читать файл построчно и не падать из-за событий, которые не нужны именно этому процессу.

codex exec --json "Проанализируй тесты и сообщи о проблемах." 
  > artifacts/events.jsonl

while IFS= read -r line; do
  printf '%sn' "$line" | jq -e . > /dev/null || {
    echo "Обнаружена некорректная JSON-строка" >&2
    exit 1
  }
done < artifacts/events.jsonl

В реальном обработчике следует дополнительно проверять тип события и извлекать только нужные поля. Не привязывайтесь к внутренним полям, которые не обещаны документацией, без теста на обновление версии CLI.

Пример: структурированный результат по схеме

Предположим, CI должен определить, есть ли блокирующие проблемы в pull request. В этом случае свободный текст лучше заменить небольшим контрактом.

{
  "type": "object",
  "properties": {
    "passed": { "type": "boolean" },
    "blocking_issues": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["passed", "blocking_issues"],
  "additionalProperties": false
}

codex exec --json 
  --output-schema schemas/review-result.json 
  --output-last-message artifacts/review-result.json 
  "Проведи ревью изменений. Если есть блокирующая проблема, установи passed в false. Ответь строго по заданной схеме."

После выполнения внешний скрипт должен проверить, что файл существует, содержит допустимый JSON и имеет ожидаемые поля. Даже хороший контракт не заменяет валидацию: автоматизация не должна слепо доверять любому файлу, созданному процессом.

Практические сценарии использования

Сила codex exec проявляется не в одиночной команде, а в повторяемом процессе. Ниже — сценарии, где агент становится отдельным инструментом командной строки: анализирует репозиторий, готовит изменения, формирует отчёты или помогает другим инструментам принимать решения.

Пример: автоматическое обновление документации

Такой запуск подходит для периодического задания, которое сверяет документацию с исходным кодом и вносит ограниченные изменения.

codex exec --cd "$GITHUB_WORKSPACE" --full-auto 
  "Сверь публичные функции Python-пакетов с документацией. Обновляй только Markdown-файлы в docs/. Не меняй исходный код. После правок запусти проверку ссылок и перечисли изменённые файлы."

Здесь явно определена область изменения. Это важнее, чем общая фраза «обнови документацию»: агенту проще соблюдать границы, а ревью изменений становится предсказуемее.

Пример: статический анализ в CI

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

codex exec --sandbox read-only --json 
  --output-last-message artifacts/ai-analysis.txt 
  "Проанализируй только изменения текущего pull request. Ищи потенциальные ошибки, нарушения обратной совместимости и уязвимости. Не меняй файлы. Для каждой проблемы укажи файл, строку, причину и уровень серьёзности."

Результат можно прикрепить к сборке или передать в систему ревью. При этом критические проверки компиляции, тесты и сканеры зависимостей должны оставаться независимыми: модельный анализ — полезное дополнение, но не единственный защитный барьер.

Пример: исправление failing-теста

В автоматическом окружении можно попросить Codex локализовать причину падения и внести минимальную правку в рабочую область.

codex exec --sandbox workspace-write --ask-for-approval on-failure 
  "Запусти тесты, относящиеся к последнему изменению. Найди причину падения, внеси минимальное исправление и повтори тест. Не добавляй новые зависимости. В финале укажи команды тестирования и их результаты."

Для такого сценария полезно ограничивать задачу последним изменением, иначе агент может начать исправлять давно существующие проблемы, расширив область работы далеко за пределы ожидаемого.

Пример: генерация миграционного плана

Не каждую задачу следует выполнять с правом изменения файлов. Иногда безопаснее сначала получить план, проверить его человеком, а уже затем запускать отдельный этап реализации.

codex exec --sandbox read-only --output-last-message artifacts/migration-plan.md 
  "Изучи схемы базы данных и код доступа к ним. Подготовь пошаговый план миграции для переименования поля customer_status. Не меняй файлы и не выполняй миграции. Укажи риски, обратимость и необходимые проверки."

Разделение планирования и исполнения снижает риск: сначала появляется объяснимый артефакт, затем оператор решает, можно ли переходить к изменениям.

Пример: анализ нескольких каталогов

Если проект состоит из основного приложения и общей библиотеки, можно явно предоставить оба каталога и попросить Codex сопоставить их интерфейсы.

codex exec --cd ./service --add-dir ./shared-lib --sandbox read-only 
  "Сравни использование общей библиотеки в service/ с её текущими публичными интерфейсами. Найди несовместимые вызовы и составь отчёт с приоритетами исправлений."

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

Пример: обработка входных данных из генератора

Иногда промпт собирается из результатов других команд: списка изменённых файлов, метаданных сборки или результатов тестов.

{
  printf '%snn' 'Проанализируй результаты проверки. Не меняй файлы.'
  printf 'Изменённые файлы:n'
  git diff --name-only
  printf 'nРезультаты тестов:n'
  cat artifacts/test-results.txt
} | codex exec --sandbox read-only --output-last-message artifacts/diagnosis.txt

Перед передачей внешних данных отделяйте их от инструкций понятными заголовками и считайте их недоверенным содержимым. Это помогает снизить риск так называемой prompt-инъекции, когда текст внутри issue или файла пытается выдать себя за команду операторов.

Пример: ночной отчёт по техническому долгу

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

codex exec --cd /srv/repository --sandbox read-only 
  --output-last-message /srv/reports/technical-debt-$(date +%F).md 
  "Изучи открытые TODO, устаревшие зависимости и повторяющиеся предупреждения линтеров. Подготовь отчёт с группировкой по компонентам и предложением следующего шага. Ничего не изменяй."

Для такого процесса важно ограничить срок хранения отчётов и исключить из рабочей области секретные файлы. Также стоит запускать задачу под отдельным пользователем с минимальными правами.

Пример: проверка формата конфигурации

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

if ! ./scripts/validate-config.sh; then
  codex exec --sandbox read-only 
    "Изучи вывод валидатора конфигурации ниже. Объясни причину ошибки, предложи исправление и перечисли возможные побочные эффекты. Не меняй файлы."
fi

Так агент включается только при необходимости и работает как диагностический помощник, а не как единственный механизм контроля корректности.

Пример: подготовка release notes

После объединения изменений можно автоматически подготовить черновик заметок к релизу на основе Git-истории и заданных правил.

{
  printf '%sn' 'Подготовь черновик release notes на русском языке.'
  printf '%sn' 'Группируй изменения по категориям: новые возможности, исправления, несовместимые изменения.'
  printf '%sn' 'Не придумывай факты, которых нет в сообщениях коммитов.'
  git log "$PREVIOUS_TAG..HEAD" --pretty=format:'- %s'
} | codex exec --sandbox read-only 
  --output-last-message artifacts/release-notes.md

Требование «не придумывай факты» здесь принципиально. Генеративная система умеет делать текст убедительным даже там, где исходных данных недостаточно, поэтому итоговые release notes всё равно стоит проверить.

Использование в CI/CD

В CI/CD команда должна быть максимально явной: рабочая директория, режим песочницы, источник инструкции, формат результата, место логов и политика ошибок. Не рассчитывайте на интерактивный ввод и не оставляйте критические параметры на случайные настройки runner-системы.

Для CI лучше запускать узкий и проверяемый сценарий, чем давать агенту широкую задачу вроде «улучши проект» и надеяться, что он сам угадает границы.

Перед интеграцией проверьте:

• Codex CLI установлен в требуемой версии;
• аутентификация доступна процессу сборки;
• рабочая директория действительно содержит нужный checkout;
• секреты исключены из контекста и логов;
• вывод сохраняется как артефакт;
• ненулевой код завершения обрабатывается явно;
• результат не влияет на релиз без дополнительной проверки.

Этап CI/CD	Рекомендуемый режим	Вывод	Что проверять
Ревью diff	--sandbox read-only	--json и отчёт	Найденные блокирующие проблемы
Планирование изменений	--sandbox read-only	Файл с планом	Полноту и реалистичность плана
Автоправка документации	--full-auto	Git diff и лог	Область изменённых файлов
Исправление теста	workspace-write	Тестовый отчёт	Повторный запуск тестов
Release notes	read-only	Markdown-файл	Фактическое соответствие истории

Пример: job для ревью pull request

Ниже показан общий shell-сценарий. Названия переменных и шагов нужно адаптировать к конкретной CI-системе, но принцип остаётся одинаковым.

set -euo pipefail

mkdir -p artifacts

git diff "$BASE_SHA" "$HEAD_SHA" > artifacts/change.diff

codex exec 
  --sandbox read-only 
  --json 
  --output-last-message artifacts/review.txt 
  "Проведи ревью изменений между базовым и текущим состоянием репозитория. Не изменяй файлы. Для каждой проблемы укажи серьёзность, файл, строку и объяснение. Если блокирующих проблем нет, напиши это явно." 
  > artifacts/review-events.jsonl

В настоящем pipeline нужно также проверить код завершения, размер diff и наличие секретов. Если diff может быть очень большим, его следует ограничивать или разбивать на логические части, иначе контекст задачи станет избыточным.

Пример: job с изменением рабочей области

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

set -euo pipefail

codex exec --full-auto 
  --output-last-message artifacts/agent-summary.txt 
  "Обнови устаревшие примеры API в docs/. Не изменяй каталоги src/ и tests/. Запусти документационные проверки."

git diff --check
git diff -- docs/ > artifacts/docs.patch

Команда git diff --check здесь проверяет базовые проблемы с пробелами и конфликтными маркерами, но не качество содержания. После этого можно запускать отдельные тесты документации и только затем отправлять изменения на дальнейшее ревью.

Безопасность и воспроизводимость

Неинтерактивный агент особенно чувствителен к ошибкам в разрешениях. Команда, которая локально выглядит безобидной, в CI может получить доступ к переменным среды, токенам, артефактам других задач или общему файловому хранилищу.

Безопасность запуска определяется не только флагом песочницы, но и тем, какие данные попали в контекст и под какой учётной записью работает процесс.

Практические правила:

• используйте отдельного пользователя CI с минимальными правами;
• не подключайте домашний каталог и каталоги секретов без крайней необходимости;
• не передавайте секреты в промпте, аргументах и открытых логах;
• для анализа начинайте с read-only;
• для изменений ограничивайте рабочую область и проверяйте diff;
• не включайте --dangerously-bypass-approvals-and-sandbox в общий шаблон без изоляции;
• фиксируйте версию Codex CLI и проверяйте совместимость параметров;
• рассматривайте данные из issue, PR и внешних файлов как недоверенные.

Риск	Как возникает	Мера снижения
Изменение лишних файлов	Слишком широкая инструкция	Явно перечислить разрешённые каталоги
Утечка секрета	Секрет попал в diff или контекст	Фильтрация входных данных и маскирование логов
Непредсказуемый режим	Используются настройки окружения	Явно задавать ключевые опции
Сломанный парсинг	Скрипт ожидает один JSON вместо JSONL	Разбирать поток построчно
Скрытая регрессия	Смотрят только на ответ агента	Запускать тесты и проверять diff отдельно
Несовместимость версии	Флаг отсутствует в другом CLI	Фиксировать версию и проверять --help

Типичные ошибки при работе с codex exec

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

Наиболее распространённые ошибки:

• Слишком общий промпт. Формулировка «улучши код» не задаёт критериев успеха и границ изменений.
• Отсутствие режима песочницы. Скрипт случайно наследует неочевидные настройки окружения.
• Парсинг обычного текста регулярным выражением. Небольшое изменение формулировки ломает автоматизацию.
• Игнорирование stderr и кода завершения. В логах остаётся причина ошибки, но pipeline считает запуск успешным.
• Отсутствие проверки diff. Даже полезная задача может привести к неожиданным изменениям.
• Передача слишком большого контекста. В промпт попадают логи, секреты и нерелевантные файлы.
• Использование опасного режима как универсального решения. Ограничения отключаются вместо того, чтобы уточнить задачу.

Пример: слишком расплывчатая команда

Такой запуск оставляет слишком много решений на усмотрение агента.

codex exec "Сделай проект лучше."

Гораздо надёжнее описать конкретную область, ожидаемые изменения и проверки:

codex exec --sandbox workspace-write 
  "В каталоге src/payments найди дублирование проверки валюты. Вынеси общую логику без изменения публичного API, добавь тесты для существующих сценариев и запусти только тесты payments."

Чем уже задача, тем проще оценить результат и тем меньше вероятность, что агент начнёт заниматься «заодно» несвязанными улучшениями.

Пример: безопасный предварительный запуск

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

codex exec --sandbox read-only --output-last-message artifacts/plan.txt 
  "Изучи задачу и репозиторий. Не изменяй файлы. Опиши предполагаемые изменения, команды, которые потребуется выполнить, и возможные риски."

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

Рекомендованный шаблон для надёжного запуска

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

1. Проверьте версию и справку: codex --version, codex exec --help.
2. Перейдите в нужный checkout или задайте --cd.
3. Определите, нужен ли только анализ или запись.
4. Для анализа выберите --sandbox read-only.
5. Для ограниченной записи рассмотрите --sandbox workspace-write или --full-auto.
6. Сформулируйте инструкцию с ограничениями и критериями готовности.
7. Для автоматической обработки включите --json и при необходимости --output-schema.
8. Сохраните итоговый ответ, события и ошибки в разные артефакты.
9. Проверьте код завершения, diff и результаты тестов.

Задача	Минимальная конфигурация	Дополнительная проверка
Только объяснение	codex exec --sandbox read-only	Проверить фактическую точность ответа
Ревью изменений	--sandbox read-only --json	Разобрать события и сохранить отчёт
Правка файлов	--sandbox workspace-write	Проверить diff и тесты
Жёсткий машинный контракт	--json --output-schema	Валидировать JSON внешним инструментом
Работа вне Git	--cd ... --skip-git-repo-check	Проверить правильность каталога

Хороший шаблон запуска может выглядеть так:

set -euo pipefail

WORKDIR="${WORKDIR:-$PWD}"
PROMPT_FILE="${PROMPT_FILE:-prompts/task.md}"
ARTIFACTS="${ARTIFACTS:-artifacts/codex}"

mkdir -p "$ARTIFACTS"

test -d "$WORKDIR"
test -f "$PROMPT_FILE"

codex exec 
  --cd "$WORKDIR" 
  --sandbox read-only 
  --json 
  --output-last-message "$ARTIFACTS/last-message.txt" 
  < "$PROMPT_FILE" 
  > "$ARTIFACTS/events.jsonl" 
  2> "$ARTIFACTS/stderr.log"

test -s "$ARTIFACTS/last-message.txt"

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

Итоги

codex exec — это интерфейс для запуска Codex как обычного автоматизируемого инструмента командной строки. Он подходит для разовых заданий, анализа репозиториев, подготовки отчётов, генерации документации, ревью pull request и ограниченных изменений в CI/CD.

Чтобы использовать его надёжно, нужно помнить о нескольких принципах:

• передавайте инструкции явно — аргументом или через stdin;
• для длинных заданий используйте версионируемые файлы промптов;
• выбирайте минимально необходимые права и режим песочницы;
• для программной обработки используйте --json, а для финального ответа — --output-last-message;
• если требуется строгий контракт, применяйте --output-schema и внешнюю валидацию;
• в CI проверяйте код завершения, логи, артефакты, diff и тесты;
• не отключайте песочницу без изоляции и чёткого понимания последствий;
• проверяйте справку своей версии Codex CLI перед переносом скрипта в другое окружение.

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