Агенты

Что такое 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 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →