Claude Code Headless: проверка развертывания из терминала

Режим Claude Code headless выполняет промпт из терминала с помощью claude -p и завершает работу. Вы можете передавать данные через конвейер, сохранять ответ и вызывать утилиту из скрипта. В этом руководстве режим используется для анализа результатов проверок развертывания: конечной точки работоспособности, расчета цены и отчета, который может проанализировать ваш проверяющий скрипт.

Пример отлавливает частую ошибку: /healthz возвращает HTTP 200, тогда как реальный маршрут приложения отдает 503. Вы получите воспроизводимое демо, JSON-отчет и ненулевой код возврата при сбое проверки приложения.

Начните с одной неинтерактивной команды

Установив Claude Code и выполнив вход, запустите:

claude -p "Explain what an HTTP 503 response tells me in two sentences." \
  --tools ""

Флаг -p означает вывод результата и выход. --tools "" отключает встроенные инструменты для текущего запроса. Claude ответит на основе промпта, не читая ваш репозиторий и не выполняя команды оболочки. В справочнике по Claude Code CLI перечислены доступные флаги.

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

Что вам понадобится

Используйте Python 3.10 или новее, актуальную версию Claude Code и аутентифицированный аккаунт. Демо использует стандартную библиотеку Python, поэтому устанавливать сторонние пакеты не нужно. Запускайте примеры в Bash или Zsh на macOS или Linux.

Проверьте установленный CLI и статус аутентификации:

claude --version
claude auth status

Если запрос завершается ошибкой из-за истечения срока действия сеанса, выполните claude auth login и повторите попытку. Сохраненная сессия может присутствовать, даже если следующий запрос к API не сможет ее обновить.

Для дополнительных проверок хостинга установите Lizard CLI и войдите в свой проект. Если вам только предстоит развернуть приложение, сначала изучите Развертывание с помощью Claude Code.

Скачайте пример и запустите демо

Создайте новую папку и скачайте шесть файлов. Изучите их перед запуском. Демо принимает GET-запросы и не хранит данные клиентов.

mkdir claude-deployment-check
cd claude-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

Оставьте этот терминал открытым. В другом окне перейдите в ту же папку. Демо предоставляет эндпоинты /healthz и /api/quote?quantity=3. Каждый товар стоит 1 200 центов; расчет для трех товаров должен вернуть currency: USD и total_cents: 3600.

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

Соберите данные перед запросом к Claude

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

Сборщик выполняет два запроса с таймаутом в пять секунд каждый. Скрипт отклоняет перенаправления, невалидный JSON и ответы размером более 64 КиБ. Проверяется как HTTP-статус, так и ожидаемые поля JSON. В лог записываются время, ожидаемые значения и результаты проверок; произвольный текст ответа в промпт не копируется.

Последнее особенно важно, когда эндпоинт возвращает пользовательский текст. Сообщение в поддержку или строка из базы данных могут содержать инструкции, нацеленные на агента. Этот пример передает Claude лишь небольшой набор конкретных полей для анализа.

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

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

Запустите команду из папки со скачанными файлами:

claude --safe-mode -p \
  "Explain the evidence on stdin. Use no tools. Copy its verdict. List the names of failed checks in failed_checks. Give a short summary and one next_step. Do not infer a root cause from HTTP status alone." \
  --tools "" \
  --no-session-persistence \
  --output-format json \
  --json-schema "$(cat report.schema.json)" \
  < evidence.json > claude-result.json

Пример использует --safe-mode для отключения таких настроек, как хуки, плагины и серверы MCP во время генерации отчета. При этом используется существующая сессия. Проверьте справку вашей версии CLI, если флаг не распознается.

Ответ Claude оборачивается во внешний объект результата. Если вы передаете схему, отчет будет находиться внутри structured_output. Внешний объект также содержит метаданные запуска и поле is_error. Обычный JSON-ответ и ответ со строгой схемой служат разным целям; парсите то поле, которое запрашивала ваша команда.

Схема запрашивает четыре поля:

В документации по программному выполнению описаны эти форматы вывода. Корректная структура JSON не гарантирует правильность объяснения, поэтому скрипт-обертка сверяет отчет с фактическими результатами проверок.

Запустите полную проверку

Скрипт run.py собирает свежие данные, вызывает Claude с таймаутом процесса 180 секунд, извлекает отчет и проверяет его. Указывайте для каждого запуска новую выходную папку:

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

Папка содержит evidence.json, claude-result.json, report.json и stderr.log. Сохраняйте сырой результат при отладке сбоев; ошибка аутентификации может появиться в stdout.

Обертка использует три кода возврата:

Код 0 от процесса Claude означает лишь то, что запуск агента завершен. Обертка принимает отдельное решение о состоянии приложения. Некорректный отчет не может превратить неудачную HTTP-проверку в успешную задачу.

Воспроизведите сбой, который пропускает проверка работоспособности

Запустите второе демо в другом терминале:

python3 demo.py --port 8788 --broken

Затем выполните:

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

Второе демо по-прежнему отвечает на /healthz кодом HTTP 200. Однако его маршрут расчета возвращает HTTP 503. Поэтому в данных фиксируется fail, а quote указывается как непройденная проверка. Получив корректный ответ от Claude, обертка завершается с кодом 1.

Вы также можете протестировать HTTP-проверки и логику проверки отчета без вызова модели:

python3 verify.py

Скрипт тестирует исправное и сломанное демо, а затем удостоверяется, что проверяющий скрипт отклоняет ложный отчет об успехе и неполные данные. Это не расходует кредиты Claude.

Примените проверку к приложению на Lizard

Выберите URL приложения из вашего проекта. Изучите текущий контекст проекта и состояние сервиса с помощью Lizard CLI:

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 status показывает привязку папки к проекту. lizard ps читает состояние сервиса для выбранного проекта. JSON-логи возвращают ограниченный снимок и завершаются; они не продолжают отслеживать сервис в реальном времени.

Используйте публичный URL сервиса с тем же проверяющим скриптом, предварительно адаптировав проверки маршрутов под ваше приложение. Если вы хостите само предоставленное демо, привяжите его к 0.0.0.0 и настройте порт сервиса соответствующим образом. Локальные примеры привязываются к 127.0.0.1.

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

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

Режим headless, аутентификация и автоматические задачи

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

Claude также предлагает команду --bare, которая пропускает большую часть стандартного контекста запуска. Ее путь аутентификации Anthropic использует переменную ANTHROPIC_API_KEY или настроенный помощник для API-ключей; она не читает учетные данные OAuth из подписки. Поэтому наш пример использует --safe-mode. Изучите актуальную документацию перед переносом задачи в CI, где настройка аутентификации может отличаться.

Для отслеживания прогресса в реальном времени Claude поддерживает формат --output-format stream-json --verbose, где каждая строка — это событие. Используйте обычный json, когда вам нужен только один итоговый результат, как в этом примере. Избегайте возобновления старого разговора для независимой проверки развертывания; каждый запуск должен опираться на свежие данные.

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

Область тестирования и следующий шаг

28 сентября 2026 года мы запустили локальные HTTP-тесты и проверку отчётов на Python 3.12.10. Они покрыли исправные ответы, сбой расчёта стоимости, ложный отчёт об успехе и неполные данные. Флаги команд сверили с Claude Code 2.1.259, Lizard CLI 4.0.8 и официальной документацией. Ответ модели Claude не входил в завершённые тесты: выше описан формат из документации. Эти учебные тесты не подтверждают работу приложения в продакшене.

Тот же паттерн с событиями JSONL и отдельным файлом итогового отчета описан в статье Проверки развертывания Codex Exec. Чтобы разместить собственное приложение в сети, изучите Руководство по развертыванию Claude Code, а затем добавьте проверку операции, которая больше всего нужна вашим пользователям.