Claude Code без интерфейса: headless-режим, Agent SDK и подводные камни автоматизации

Коротко (TL;DR)

Claude Code умеет работать не только в интерактивном чате, но и без интерфейса — как обычная команда внутри скрипта или CI-пайплайна. За это отвечают две вещи, которые на самом деле являются одним движком в разных обёртках:

• headless-режим (claude -p) — запускаете Claude из терминала, он прогоняет полный агентный цикл и печатает результат в stdout;
• Claude Agent SDK — тот же цикл, но программно, из Python или TypeScript, когда одной команды мало и нужна логика вокруг.

Главное, что стоит понять сразу: лимиты и поведение по умолчанию заточены под человека у экрана, а не под автономный скрипт. Именно из-за этого автоматизация чаще ломается не на самих флагах, а на граблях — 60-секундном таймауте вопроса, тихой подмене подписки API-ключом и нестабильном биллинге. Разберём и флаги, и грабли.

Отдельный больной вопрос — можно ли гонять это на подписке Pro/Max или обязательно платить за API. Ответ на 11 июля 2026 года: официальные документы Anthropic формулируют по-разному, и это открытая неопределённость, а не чёткое «да/нет». Подробно — ниже.

Headless и Agent SDK: одна платформа, три интерфейса

Частая путаница: люди думают, что headless-режим и Agent SDK — разные продукты. На деле это один и тот же агентный движок Claude Code, доступный тремя способами:

Bybit · Rewards Hubдо $30,100Внеси депозит, торгуй 14 дней — и забери награды в Rewards HubЗабрать бонус →

1. CLI — команда claude -p "запрос" в терминале.
2. Python-библиотека — claude-agent-sdk.
3. TypeScript-библиотека — @anthropic-ai/claude-agent-sdk.

Под капотом у всех трёх — один и тот же цикл: чтение контекста, вызов инструментов, управление контекстным окном. Разница только в том, как вы его вызываете: разовой командой из bash, или программно, обвешивая своей логикой (ветвления, обработка ошибок, склейка нескольких вызовов).

Генератор против критика: как несколько ИИ ловят баги, которые пропускает один

«Готово» — это оценка агента или чека? TDD и eval-driven разработка с ИИ

Как запускать несколько агентов Claude Code одновременно и не ловить конфликты файлов

Пять периметров безопасности Claude Code: что реально настроить, а что вас удивит

Чаты Claude утекли в поиск: у страниц с общими ссылками не было запрета на индексацию

Выбор простой. Нужно один раз прогнать задачу в скрипте или CI — берите CLI -p. Нужна программа, которая сама решает, что и когда запускать, хранит состояние между вызовами и обрабатывает результаты — берите SDK. В отличие от постоянного ИИ-коллеги вроде Claude Tag, который живёт в Slack и ждёт обращений, headless-Claude живёт в вашем терминале или пайплайне и отрабатывает ровно один вызов.

Как запустить claude -p: флаги и форматы вывода

-p — это неинтерактивный режим: команда выполняется от начала до конца без диалога, в отличие от обычного чата. Базовый вызов:

claude -p "проанализируй тесты и почини падающие" --output-format json

Флаг --output-format определяет, что вы получите на выходе:

Формат json с полем total_cost_usd — ваш главный инструмент учёта: он позволяет логировать стоимость каждого автономного вызова и ловить, когда скрипт начинает жечь бюджет.

Отдельного внимания заслуживает флаг --bare. Формально он «ускоряет старт», но важнее его побочный эффект: --bare не подхватывает авто-обнаружение хуков, скиллов, плагинов, MCP-серверов и файла CLAUDE.md. Это и есть причина №1 классической ситуации «локально всё работает, в CI — нет»: локально агент видит ваш проектный CLAUDE.md и хуки, а в «голом» режиме — нет. Если автоматизация ведёт себя по-разному в двух средах, первым делом проверьте, не запущена ли она с --bare. По документации этот режим со временем станет дефолтом для -p, так что закладывайтесь на него заранее.

Лимиты, о которых не пишут в туториалах

Дефолты Claude Code рассчитаны на интерактивный чат. В автономном скрипте всплывают ограничения, о которых обычные гайды молчат:

BYBIT EARNЗаставь крипту работатьПроценты на USDT и BTC без блокировки — деньги остаются под рукой.Разместить

• Размер stdin — 10 МБ (с версии v2.1.128). Передадите больше — процесс завершится с ненулевым кодом. Актуально, когда вы пайпите большой лог или дамп в промпт.
• Фоновые задачи. После получения результата фоновым bash-задачам даётся grace-период около 5 секунд; фоновые субагенты ждут дольше — до 10 минут (потолок настраивается через CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, версии v2.1.163 и v2.1.182).
• Таймаут AskUserQuestion — 60 секунд. Вот самая коварная грабля. Если агент в автономном цикле решает задать уточняющий вопрос, а ответить некому, он раньше падал по 60-секундному таймауту (версии v2.1.198–199). Реальная боль автоматизаторов задокументирована в issue #73125 на GitHub — 407 реакций. С версии v2.1.200+ этот таймаут выключен по умолчанию, а поведение настраивается переменной CLAUDE_AFK_TIMEOUT_MS. Обход на практике — заранее задать permission-mode и allowedTools, чтобы агенту вообще не пришлось спрашивать.

Вывод из этого списка простой: перед тем как оставить скрипт работать без присмотра, уберите все точки, где агент может «зависнуть в ожидании человека».

Claude Agent SDK на Python и TypeScript

Когда CLI мало, в дело идёт SDK — тот же движок, но как библиотека.

Python (требует 3.10+):

pip install claude-agent-sdk

На 11 июля 2026 года актуальная версия пакета — 0.2.116.

TypeScript:

npm install @anthropic-ai/claude-agent-sdk

SDK даёт то же, что и интерактивный Claude Code: управление контекстом, инструменты, субагентов. Субагенты вызываются через инструмент Agent и описываются структурой AgentDefinition; связь дочернего вызова с родительским отслеживается полем parent_tool_use_id. Хуки и права доступа тоже настраиваются программно.

Важно не путать Agent SDK с двумя соседними вещами. Если вы сами пишете цикл вызова инструментов поверх голого API — это уже Client SDK, другой уровень. А если хотите, чтобы агент крутился не в вашей инфраструктуре, а на серверах Anthropic по REST — это Managed Agents. Официальный путь эскалации выглядит так: прототип на Agent SDK локально, а когда он созрел для продакшена — перенос на Managed Agents. Держать это в голове полезно, чтобы не строить свой хостинг там, где уже есть готовый.

Логирование, таймауты и ретраи

Поведение headless-вызовов настраивается переменными окружения. Основные:

Про ретраи есть важная тонкость: отдельного CLI-флага вроде --max-retries не существует. Повторные попытки при сбоях API Claude Code делает внутренне, а увидеть их можно только через событие system/api_retry в потоке stream-json. То есть для наблюдаемости ретраев вы не ставите флаг, а фильтруете поток событий (например, jq-пайплайном по типу события) — это готовый паттерн мониторинга без сторонних библиотек. Не ищите несуществующий флаг: управление повторами тут не через параметр запуска.

Ещё одна ловушка биллинга, которую легко пропустить: если задана переменная ANTHROPIC_API_KEY, в режиме -p она всегда используется вместо подписки, причём без запроса подтверждения (в отличие от интерактивного режима, где Claude бы переспросил). Проверяйте окружение CI: случайно проброшенный ключ молча уведёт вас с подписки на платный API.

Подписка или API-ключ: зона неопределённости

Самый спорный вопрос — можно ли использовать логин подписки (OAuth Pro/Max) в headless-скриптах и Agent SDK, или обязательно платить за API отдельно. Документы Anthropic на эту тему расходятся.

• Страница legal-and-compliance предписывает разработчикам, которые строят продукты на Agent SDK, использовать API-ключ, а сторонним продуктам прямо запрещает пробрасывать чужой Free/Pro/Max-логин.
• При этом биллинг-страница поддержки на 11 июля 2026 года подтверждает, что claude -p и Agent SDK сейчас тянут из лимитов подписки. Anthropic анонсировала вывод этой нагрузки в отдельный кредитный пул 14 мая 2026 года, но приостановила изменение в день вступления в силу — 15 июня 2026 года, нового срока не назначено.

Что это значит на практике. Для личных скриптов формулировка «разрешено» нигде не дана прямо, но и техническая возможность работать на подписке пока сохраняется. Для продуктов, которыми пользуются другие люди, официальная позиция ясна — API-ключ. Планировать автоматизацию стоит с оглядкой на то, что политика может развернуться: она уже один раз менялась и ставилась на паузу за месяц. Если ваш пайплайн критичен, безопаснее закладывать API-ключ и считать его стоимость заранее.

Haiku 4.5 как дешёвый маршрутизатор

Не каждый headless-шаг требует топовой модели. Простые операции — классификация, извлечение данных, короткое summarize — дешевле и быстрее гонять на Haiku, выбирая её флагом --model.

Цена Claude Haiku 4.5 на 11 июля 2026 года — 1 доллар за миллион входных токенов и 5 долларов за миллион выходных; в batch-режиме вдвое дешевле (0,5 и 2,5 доллара). Сама Anthropic позиционирует Haiku как модель для параллельного исполнения, субагентов и высокочастотных операций.

Практический приём: в автономном пайплайне маршрутизируйте лёгкие шаги на --model haiku, а тяжёлые (сложный рефакторинг, архитектурные решения) оставляйте Sonnet или Opus. На тысячах вызовов такая маршрутизация экономит заметную часть бюджета, не роняя качество там, где оно действительно нужно.

Claude Code в CI/CD за 10 минут

Официальный способ подключить Claude к GitHub — экшен claude-code-action@v1 (в статусе GA). Схема короткая:

1. Выполните /install-github-app и выдайте приложению права на Contents, Issues и Pull requests.
2. Добавьте в секреты репозитория ANTHROPIC_API_KEY (именно API-ключ, не OAuth).
3. Пропишите экшен в workflow — он построен на том же Agent SDK.

Полезные предохранители: --max-turns ограничивает число ходов агента за вызов (в GitHub Actions по умолчанию 10), а --max-budget-usd — расход в долларах. Оба стоит выставлять явно, чтобы автономный прогон не ушёл в разнос. Для GitLab CI/CD подход аналогичный, через собственный раннер и тот же секрет с API-ключом, но это тема отдельного разбора. Главное правило для любого CI: выставляйте лимиты ходов и бюджета явно и никогда не оставляйте автономный прогон совсем без потолка.

Риски и слабые места

Соберём подводные камни в одном месте — именно они, а не флаги, решают судьбу автоматизации:

• Нестабильный биллинг. Пока -p и SDK тянут из подписки, ваша автоматизация конкурирует за одно окно квоты с ручным кодингом. Политика на паузе с 15 июня 2026 года и может развернуться — планируйте с запасом.
• Тихая подмена ключом. Проброшенный ANTHROPIC_API_KEY молча уводит с подписки на платный API. Проверяйте окружение.
• Зависание на вопросе. Автономный цикл, который решил спросить человека, без настройки CLAUDE_AFK_TIMEOUT_MS или заранее заданных прав может встать. Убирайте точки ожидания.
• Расхождение сред из-за --bare. «Локально работает, в CI нет» — почти всегда про неподхваченные хуки/MCP/CLAUDE.md.
• Быстрая смена версий. Поведение привязано к конкретным версиям CLI (v2.1.128, v2.1.182, v2.1.200 и далее). Фиксируйте версию в пайплайне и сверяйтесь с документацией при обновлении.

Ни один из этих рисков не смертелен, но каждый способен тихо сломать автоматизацию через неделю работы. Заложите их в дизайн скрипта сразу.

FAQ

Сломает ли headless мою подписку или спишет лишнее? На 11 июля 2026 года claude -p и Agent SDK тянут из лимитов вашей подписки — то есть автономные прогоны едят ту же квоту, что и ручной кодинг. Anthropic анонсировала вынос этой нагрузки в отдельный кредит, но поставила изменение на паузу с 15 июня 2026 года. Следите за биллинг-страницей: политика может измениться.

Нужен ли API-ключ для личного скрипта? Технически на 11 июля 2026 года headless работает и на подписке. Но официальная страница legal-and-compliance предписывает API-ключ для продуктов на Agent SDK, а для личного использования прямой формулировки «разрешено» нет. Если скрипт критичен или им пользуется кто-то ещё — берите API-ключ и считайте его стоимость.

Как настроить число повторных попыток при сбоях API? Отдельного флага для этого нет. Ретраи Claude Code делает внутренне; наблюдать их можно через событие system/api_retry в выводе stream-json. Управлять поведением напрямую параметром запуска нельзя — закладывайте это в логику обработки на своей стороне.

Почему скрипт работает локально, но падает в CI? Самая частая причина — флаг --bare (или окружение, эквивалентное ему): в «голом» режиме Claude не подхватывает проектные хуки, MCP-серверы и CLAUDE.md, которые есть у вас локально. Вторая причина — проброшенный в CI ANTHROPIC_API_KEY, который меняет источник оплаты и лимиты.

Чем Agent SDK отличается от готового личного агента? Готовый агент вроде OpenClaw — это собранное решение, которое вы ставите и используете. Agent SDK — конструктор: вы сами пишете программу вокруг движка Claude Code под свою задачу. SDK гибче, но требует кода и поддержки; готовый агент быстрее в старте, но менее управляем.