Что такое headless-режим ИИ-агента — и почему он молча пропускает шаги

Ты просишь агента в скрипте: «запусти тесты и почини, что упало». Скрипт отработал, вернул «успех». Открываешь код — ничего не изменилось.
Агент не сломался. Он просто никого не нашёл, чтобы спросить разрешения. И вежливо пропустил всё, на что разрешения не было.
Это главная ловушка headless-режима. Сейчас разберём, что это такое и как с ним дружить.
Что такое headless-режим
Headless-режим — это запуск ИИ-агента без интерфейса: одна команда на входе, готовый ответ на выходе. Без окна чата, без кнопок, без тебя рядом.
Слово пришло из мира браузеров. «Headless» — «без головы», то есть без экрана. Программа делает ту же работу, но её никто не видит.
В Claude Code такой режим включает флаг -p (или --print):
claude -p "Что делает модуль auth?"
Агент прочитает код, ответит текстом в терминал и завершится. Как обычная консольная программа.
Как это работает
В обычном режиме ты с агентом разговариваешь. В headless он ведёт себя как инструмент в цепочке. Три вещи, которые это дают.
Ввод через трубу. Агент читает стандартный ввод. Значит, ему можно скормить что угодно через пайп:
cat build-error.txt | claude -p "объясни причину ошибки" > fix.txt
Лимит на такой ввод — 10 МБ. Больше — положи в файл и назови путь в промпте.
Код выхода. Если запуск упал, агент вернёт ненулевой код. Скрипт может на это реагировать: остановиться, отправить уведомление.
Машиночитаемый ответ. С флагом --output-format json вместо текста приходит JSON. В нём ответ в поле result, номер сессии и даже total_cost_usd — примерная цена запуска. Удобно, чтобы следить за расходами.
А ещё разговор можно продолжить. --continue подхватит последнюю сессию, --resume <id> — конкретную. Так агент делает работу в несколько заходов и помнит, что было в прошлом.
Где подвох: некому сказать «да»
Вернёмся к началу. В интерактивном режиме агент перед опасным шагом спрашивает тебя. Изменить файл? Запустить команду? Ты жмёшь «разрешить».
В headless жать некому. И Claude Code поступает просто: шаг, которому нужно разрешение, отклоняется. Без паузы и без ошибки. Агент получает отказ и идёт дальше, как может.
Поэтому права выдают заранее, флагом --allowedTools:
claude -p "Запусти тесты и почини, что упало" \
--allowedTools "Bash,Read,Edit"
Можно точнее — разрешить только конкретные команды:
--allowedTools "Bash(git diff *),Bash(git commit *)"
И вот тонкость, о которую легко споткнуться. Пробел перед звёздочкой важен. Bash(git diff *) — это git diff с любыми аргументами. А Bash(git diff*) без пробела заодно разрешит git diff-index — уже другую команду.
Как узнать, что что-то отклонили? В JSON-выводе есть список permission_denials. Проверяй его в скрипте, а не только код выхода.
Второй подвох: чужие настройки
Без дополнительных флагов claude -p грузит всё, что есть в проекте: хуки, MCP-серверы, правила. Даже в папке, которой ты никогда не доверял, — вопроса о доверии тут нет.
Для скриптов и CI документация советует флаг --bare. Он запускает агента «голым»: без чужих хуков и настроек, одинаково на любой машине. Только учти: в этом режиме нужен API-ключ, вход по подписке не используется.
Зачем это тебе
Headless — это момент, когда агент перестаёт быть чатом и становится деталью твоих процессов. Что можно собрать уже сегодня:
- Ревью перед пушем.
git diff main | claude -p "найди баги в этом диффе"— в виде скрипта вpackage.json. - Ночной разбор логов. Через cron агент раз в сутки читает логи и пишет короткую сводку.
- Проверка в CI. Агент смотрит каждый пулл-реквест в CI/CD и оставляет замечания.
Правило одно: в headless заранее решай, что агенту можно. Он не спросит.
Начни с малого: дай только чтение (--allowedTools "Read") и попроси отчёт. Когда увидишь, что агент делает то, что нужно, — добавляй права по одному.
Частые вопросы
Чем headless-режим отличается от API модели?
API даёт только ответ модели. Headless-агент сам читает файлы, запускает команды и делает несколько шагов подряд — как в обычном чате, только без окна.
Можно ли разрешить агенту в headless вообще всё?
Технически да, флагом --dangerously-skip-permissions. Но тогда он сможет удалить файлы или выполнить любую команду. Запускай так только в одноразовом контейнере, где ломать нечего.
Работают ли в headless мои слэш-команды?
Да. Напиши имя команды прямо в промпте: claude -p "/review". А вот команды, которые нужны только для интерфейса, например /login, там недоступны.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





