codex exec: Codex в скриптах

codex exec — это Codex без интерфейса: одна команда, одна задача, результат в stdout. На нём построено почти всё в этом курсе, от job в GitLab CI до GitHub Action. В уроке — как он устроен, какие у него права по умолчанию и какие флаги нужны, чтобы запуск в пайплайне вёл себя одинаково каждый раз.

Базовый вызов

Задача передаётся одним аргументом:

codex exec "опиши структуру репозитория и назови пять самых рискованных мест"

Пока Codex работает, ход выполнения — команды, рассуждения, правки — идёт в stderr. В stdout попадает только финальное сообщение агента. Поэтому результат удобно перенаправить в файл или передать дальше:

codex exec "составь заметки о релизе по последним 10 коммитам" | tee release-notes.md

У команды есть короткий алиас codex e. Работать она должна внутри Git-репозитория: это защита от необратимых изменений. Для одноразовых каталогов без Git есть --skip-git-repo-check, но пользуйтесь им, только если уверены, что в каталоге нечего ломать.

Данные через pipe

Если на вход подан stdin и есть аргумент-промпт, аргумент считается инструкцией, а stdin — дополнительным контекстом. Это самый частый приём в агентстве: выход одной команды становится материалом для Codex.

vendor/bin/phpunit 2>&1 \
  | codex exec "кратко перечисли упавшие тесты и предложи минимальное исправление" \
  > test-summary.md

tail -n 300 storage/logs/system.log \
  | codex exec "найди вероятную первопричину ошибок и предложи три шага для отладки" \
  > log-triage.md

Если промпт целиком собирается скриптом, передайте его через stdin, указав - вместо аргумента:

cat .codex/prompts/weekly-report.md | codex exec -

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

Права: по умолчанию только чтение

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

# разрешить правки внутри рабочего каталога
codex exec --sandbox workspace-write "исправь падающий тест в tests/OrderTest.php"

# полный доступ — только в изолированном раннере или контейнере
codex exec --sandbox danger-full-access "<задача>"

Есть и промежуточный вариант — --approve-for-me: песочница workspace-write, а запросы на выход за её пределы рассматривает агент-ревьюер вместо человека. Этот флаг нельзя совмещать с --sandbox и --yolo. Подробнее о том, как работает автоматическое ревью одобрений и почему оно не гарантирует безопасность, — в документации.

В режиме workspace-write сеть по умолчанию выключена. Если задача требует сети, например установить зависимость, это настраивается отдельно в конфигурации — см. урок «Песочница всерьёз».

Если вы читали старые инструкции. Флаг --full-auto больше не поддерживается. Вместо него — --sandbox workspace-write или --approve-for-me. В старых статьях и даже в некоторых примерах OpenAI Cookbook он ещё встречается.

Воспроизводимый запуск

На машине разработчика codex exec подхватывает личный ~/.codex/config.toml, правила и сохранённую авторизацию. В пайплайне это чаще мешает: результат зависит от того, чей конфиг оказался на раннере. Полезные флаги:

Пример запуска, который не зависит от окружения разработчика:

codex exec \
  --ephemeral \
  --ignore-user-config \
  --sandbox read-only \
  -c model_reasoning_effort=medium \
  "проверь, что все миграции в updates/ имеют откат"

В этом примере модель не указана, и Codex возьмёт модель по умолчанию. Для CI её стоит закрепить флагом -m: модель по умолчанию меняется, и вместе с ней меняется поведение пайплайна. Названия моделей на октябрь 2026 года смотрите в документации.

Ещё одна деталь: если в конфиге MCP-сервер помечен required = true и не смог запуститься, codex exec завершается с ошибкой, а не продолжает без него. Для CI это хорошо: лучше упасть, чем выдать результат без нужного инструмента.

Авторизация в автоматизации

Локально codex exec использует сохранённый вход. В CI ключ обычно передают явно, и рекомендованный по умолчанию вариант — API-ключ в переменной CODEX_API_KEY. Документация настаивает на важной детали: задавайте ключ только для того вызова, которому он нужен, а не для всего job.

CODEX_API_KEY="$OPENAI_API_KEY" codex exec --json "разбери открытые баг-репорты"

Причина простая. Если ключ лежит в переменных окружения всего job, его могут прочитать сборочные скрипты, тесты, хуки установки зависимостей — любой код из репозитория, который выполняется в том же job. Подробно о том, как устроить это в GitLab, — в уроке «Codex в GitLab CI».

Вход через аккаунт ChatGPT в CI тоже возможен, но это продвинутый сценарий: файл ~/.codex/auth.json содержит токены доступа, и обращаться с ним нужно как с паролем. Документация не рекомендует этот путь для публичных репозиториев. Детали — на странице Maintain Codex account auth in CI/CD.

Отладка запуска

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

RUST_LOG=info codex exec "..." 2> codex-debug.log

Для разбора поведения агента полезнее поток событий --json — о нём следующий урок.