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, доступний трьома способами:

BINANCEДосі дивишся збоку?Ринок працює без вихідних. Рахунок на Binance відкривається за 2 хвилини.Почати зараз

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 розраховані на інтерактивний чат. В автономному скрипті випливають обмеження, про які звичайні гайди мовчать:

BINANCE COPY TRADINGКопітрейдинг на BinanceВідкрита статистика трейдерів, старт з $10, вимкнення одним кліком.Обрати трейдера

• Розмір 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 — той самий рушій, але як бібліотека. Що таке Claude Agent SDK по суті? Це той самий агентний цикл Claude Code, який ви обгортаєте власним кодом.

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 Code у скриптах логічно продовжується в пайплайнах. Офіційний спосіб підключити 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 гнучкіший, але потребує коду й підтримки; готовий агент швидший на старті, але менш керований.