Codex Exec: Автоматизация проверок развертывания из терминала

codex exec запускает Codex без интерактивного интерфейса терминала. Передайте промпт или данные через конвейер, а затем сохраните ответ для следующего шага скрипта. В этом руководстве создается отчет о развертывании с событиями JSONL, результатом, ограниченным схемой, и кодом возврата на основе реальных HTTP-проверок.

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

Запуск Codex без интерактивного интерфейса

Из доверенного Git-репозитория выполните:

codex exec --sandbox read-only \
  "Summarize this repository in three sentences. Do not change files."

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

Для отчета о развертывании мы передадим наблюдения через stdin. Небольшой сборщик на Python выполняет сетевые запросы. Codex объясняет полученные данные, а отдельная функция проверяет отчет на соответствие этим результатам проверок.

Понимание трех выходных файлов

Эти файлы выполняют разные роли:

--json превращает stdout в поток событий, а не в единый объект отчета. --output-schema описывает итоговый ответ, а -o сохраняет его отдельно. Это различие предотвращает частую ошибку автоматизации: попытку распарсить весь журнал событий за одно чтение JSON.

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

Используйте Python 3.10 или новее и аутентифицированный Codex CLI. Файлам Python не требуются сторонние пакеты. Приведенные ниже команды оболочки предназначены для Bash или Zsh в macOS или Linux.

codex --version
codex login status
mkdir codex-deployment-check
cd codex-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done

Прочитайте скачанные файлы перед их выполнением. Запустите демо-версию и оставьте ее работать:

python3 demo.py --port 8787

Приложение имеет два GET-маршрута. /healthz возвращает status: ok. /api/quote?quantity=3 рассчитывает стоимость для трех товаров по 1 200 центов каждый. Ожидаемый результат — $36.00 (3 600 центов). В примере используются целые центы, чтобы избежать округления при проверке.

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

Сбор и проверка HTTP-данных

python3 collect.py http://127.0.0.1:8787 > evidence.json

Сборщик записывает URL, время проверки, статус HTTP и соответствие каждого ответа ожидаемым полям. Скрипт выполняет два ограниченных запроса, отклоняет перенаправления и обрезает каждый ответ до 64 КиБ. Модели отправляются ожидаемые значения и логические флаги без копирования произвольного текста ответа.

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

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

Запрос структурированного отчета

Из доверенного Git-репозитория, содержащего файлы, выполните:

codex exec --ignore-user-config --ephemeral \
  --sandbox read-only \
  --json \
  --output-schema report.schema.json \
  -o report.json \
  "Explain the evidence on stdin. Use no tools. Copy its verdict, list failed check names in failed_checks, and give a summary and next_step. Do not infer a root cause from HTTP status alone." \
  < evidence.json > events.jsonl 2> stderr.log

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

--ignore-user-config пропускает основной конфигурационный файл Codex пользователя, сохраняя обычную аутентификацию. --ephemeral предотвращает сохранение развертывания сеанса. Обертка по-прежнему сохраняет три явных выходных файла, указанных выше. --sandbox read-only ограничивает команды, сгенерированные моделью; перенаправления оболочки записывают артефакты.

Схема требует verdict, failed_checks, summary и next_step, запрещая дополнительные поля. Отчет должен объяснять, что именно подтверждают предоставленные проверки. Ответ может предложить проверить логи приложения после ошибки 503, но один лишь код статуса не доказывает сбой базы данных.

Раздельный парсинг потока и итогового ответа

В нашем живом тесте Codex выдал эти типы событий по порядку:

thread.started
turn.started
item.completed
turn.completed

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

Обертка читает каждое событие и отклоняет turn.failed или error. Также требуется turn.completed, успешное завершение процесса и итоговый отчет, который можно распарсить. Затем вердикт отчета и имена непройденных проверок сравниваются с HTTP-данными.

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

Запуск полного рабочего процесса

python3 run.py codex http://127.0.0.1:8787 runs/healthy

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

Чтобы воспроизвести сбой, запустите вторую демо-версию в другом терминале:

python3 demo.py --port 8788 --broken

Затем запустите тот же рабочий процесс для этого экземпляра:

python3 run.py codex http://127.0.0.1:8788 runs/broken

Маршрут проверки работоспособности возвращает 200, а маршрут расчета стоимости — 503. Codex получает эти наблюдения и возвращает отчет об ошибке. Обертка завершается с кодом 1. Процесс создания отчета может успешно завершиться, даже если проверка приложения не пройдена; автоматизация должна использовать код возврата обертки для принятия решения о приложении.

Результаты рабочего примера

Мы запустили оба сценария с Codex CLI 0.156.1 и Python 3.12.10 28 сентября 2026 года. Мы также проверили команды Lizard CLI на версии 4.0.8.

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

Локальные тесты проверок также отклоняют ложный отчет об успехе и неполные данные. Запустите их без вызова модели:

python3 verify.py

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

Добавление состояния сервиса и логов Lizard

Для приложения на Lizard подтвердите цель перед интерпретацией сбоев:

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

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

Запустите адаптированный HTTP-сборщик для публичного URL-адреса сервиса. Контейнер, отмеченный как работающий, не доказывает, что поиск цены или чтение базы данных работает. Сравните время сбоя HTTP с логами сервиса, чтобы сузить область дальнейшего расследования. Удалите секреты и личные данные из логов перед отправкой их модели.

Если вам сначала нужно выполнить развертывание, начните с руководства по развертыванию coding-agent. Для приложений с зависимостями от данных руководство по Postgres MCP и руководство по Redis MCP объясняют ограниченный доступ для проверки тестовых данных.

Использование результата в автоматизации

Сделайте три исхода явными: приложение прошло проверку, приложение не прошло проверку и задание отчета завершилось с ошибкой. Эта обертка использует 0, 1 и 2 соответственно. Тайм-аут, проблема аутентификации CLI, недействительный отчет или противоречие в выводе приводят к коду 2.

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

На вашей собственной доверенной машине codex exec может повторно использовать сохраненный логин CLI. Для GitHub Actions следуйте официальному руководству по действиям Codex для настройки аутентификации и разрешений. Не храните учетные данные API в файлах репозитория и избегайте их раскрытия ненадежным шагам сборки. Изучите эти специфичные для раннера требования перед переносом локальной команды в CI.

Используйте свежие данные для каждой независимой проверки. codex exec resume может продолжить диалог, но это не нужно для этого одноразового отчета. Эфемерный режим примера делает каждый запуск независимым.

Устранение неполадок

Что дальше

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

Если ваша команда использует Claude Code, руководство по Claude Code в headless-режиме показывает те же HTTP-проверки с его оболочкой результатов. Чтобы запустить само приложение, используйте Lizard CLI и добавьте отчет после шага развертывания.