SpyBara
Go Premium

headless.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 132 additions and 32 deletions.

2026
Thu 10 23:00 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Запуск Claude Code программно

Используйте Agent SDK для программного запуска Claude Code из CLI, Python или TypeScript.

Agent SDK предоставляет вам те же инструменты, цикл агента и управление контекстом, которые питают Claude Code. Он доступен как CLI для скриптов и CI/CD, или как пакеты Python и TypeScript для полного программного управления.

Чтобы запустить Claude Code в неинтерактивном режиме, передайте -p с вашим запросом и параметрами CLI, которые вам нужны:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

На этой странице рассматривается использование Agent SDK через CLI (claude -p). Для пакетов Python и TypeScript SDK со структурированными выходами, обратными вызовами одобрения инструментов и собственными объектами сообщений см. полную документацию Agent SDK.

Базовое использование

Добавьте флаг -p (или --print) к любой команде claude для запуска её в неинтерактивном режиме. Не все параметры CLI работают с -p. Claude Code отклоняет --bg и отклоняет --cloud с описанием задачи с ошибкой, указывающей на конфликт; --cloud с ID сессии и -p вместо этого ставит сообщение в очередь в эту облачную сессию и выходит. Параметры, которые вы часто будете использовать с -p, включают:

Этот пример задаёт Claude вопрос о вашей кодовой базе и выводит ответ:

claude -p "What does the auth module do?"

Claude Code выходит с кодом 0 при успехе и с ненулевым кодом при сбое запуска, поэтому ваши скрипты могут ветвиться в зависимости от кода выхода. Если вы передадите неверный флаг, Claude Code сообщит об ошибке в stderr перед началом запуска. Когда сбой происходит внутри запуска, например отсутствие аутентификации, Claude Code выводит сбой как результат на stdout.

Начните быстрее с режима bare

Добавьте --bare для сокращения времени запуска путём пропуска автоматического обнаружения hooks, skills, пользовательских команд, подагентов, plugins, MCP серверов, автоматической памяти и CLAUDE.md. Без этого claude -p загружает тот же контекст, что и интерактивная сессия, включая всё, что настроено в рабочем каталоге или ~/.claude.

Режим bare полезен для CI и скриптов, где вам нужен одинаковый результат на каждой машине. Hook в ~/.claude коллеги или MCP сервер в .mcp.json проекта не будут запущены, потому что режим bare никогда их не читает. Каталог, который вы указываете с помощью --add-dir, является частичным исключением: режим bare загружает skills из его папки .claude/skills/, но всё ещё пропускает его папки .claude/commands/ и .claude/agents/. Skills из дополнительных каталогов охватывает то, что загружается и что не загружается.

Без --bare сессия -p запускает hooks в .claude/settings.json проекта и подключает серверы в его .mcp.json, даже в папке, которой вы никогда не доверяли. Сессия -p не показывает диалог доверия рабочей области и не показывает запрос одобрения для каждого сервера. Что запускается перед тем, как вы доверите папку охватывает каждый вид содержимого репозитория под -p и как его избежать.

Этот пример запускает одноразовую задачу суммирования в режиме bare и предварительно одобряет инструмент Read, чтобы вызов завершился без запроса разрешения. Установите ANTHROPIC_API_KEY перед запуском, потому что режим bare не использует вашу подписку:

claude --bare -p "Summarize README.md" --allowedTools "Read"

В режиме bare Claude Code никогда не читает учётные данные OAuth или системную связку ключей. Для Anthropic API установите ANTHROPIC_API_KEY в окружении с ключом, созданным в Claude Console, или предоставьте apiKeyHelper в JSON --settings. Amazon Bedrock, Google Cloud's Agent Platform и Microsoft Foundry продолжают читать свои собственные учётные данные поставщика как обычно.

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

Для загрузки Используйте
Дополнения системного запроса --append-system-prompt, --append-system-prompt-file
Параметры --settings <file-or-json>
MCP серверы --mcp-config <file-or-json>
Пользовательские агенты --agents <json>
Плагин --plugin-dir <path>, --plugin-url <url>

Фоновые задачи при выходе

Если Claude запускает фоновую задачу Bash во время выполнения claude -p, например сервер разработки или сборку с отслеживанием, эта оболочка завершается примерно через пять секунд после того, как Claude вернул свой окончательный результат и stdin закрыт. Период ожидания позволяет задаче, которая завершается сразу после результата, всё ещё доставить свой вывод.

Если Claude запускает фоновый подагент или рабочий процесс, claude -p вместо этого остаётся открытым до завершения этой работы, потому что её результат является частью окончательного вывода.

По умолчанию ожидание заканчивается после 10 минут непрерывного простоя, поэтому застрявший подагент или рабочий процесс не может держать процесс открытым неопределённо долго. В этот момент Claude Code останавливает всё, что ещё выполняется, и отбрасывает его частичный результат. Чтобы изменить ограничение, установите CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS или установите его на 0 для ожидания без ограничений.

Если Claude запускает наблюдение Monitor во время выполнения claude -p, Claude Code ждёт наблюдения до истечения времени ожидания или до того, как десятиминутный лимит завершит ожидание, в зависимости от того, что произойдёт раньше. Пока он ждёт, Claude продолжает отвечать на то, что сообщает наблюдение. По умолчанию наблюдение истекает через пять минут после того, как Claude его запустит.

Остановите запуск с помощью SIGTERM

Если вы остановите запуск claude -p с помощью SIGTERM, например с помощью kill или от супервизора процесса, Claude Code выходит с кодом 143. Claude Code оставляет ход, который был в процессе, незавершённым и не записывает для него результат. Чтобы вместо этого завершить ход, отправьте SIGINT или вызовите interrupt() Agent SDK перед остановкой процесса.

При SIGTERM Claude Code завершает дерево процессов любой команды Bash, которая всё ещё выполняется. Claude Code затем запускает SessionEnd hooks и выходит. При выходе Claude Code не запускает новый вызов инструмента, не отправляет новый запрос модели и не запускает никакой hook, кроме SessionEnd. Если запуск был в середине команды или ожидал ответа на запрос разрешения, когда пришёл сигнал, Claude Code обрабатывает этот шаг следующим образом:

  • Выполнение команды: Claude Code записывает команду как убитую в сессии.
  • Ожидание ответа на запрос разрешения: если вы отправите SIGTERM процессу, Claude Code оставляет запрос без ответа. Если ваша программа закрывает сессию через Agent SDK, SDK завершает ввод Claude Code перед отправкой любого сигнала, и Claude Code отменяет запрос, как только ввод завершается.

Когда вы возобновляете сессию, Claude Code продолжает ход, который SIGTERM оставил незавершённым.

Примеры

Эти примеры выделяют общие паттерны CLI. Если команда называет файл, например auth.py или build-error.txt, подставьте файл из вашего собственного проекта. В CI или других скриптовых окружениях добавьте --bare, чтобы Claude Code запустился без загрузки hooks хоста, плагинов, автоматической памяти или CLAUDE.md.

Передача данных через Claude

Неинтерактивный режим читает stdin, поэтому вы можете передавать данные и перенаправлять ответ, как любой другой инструмент командной строки.

Этот пример передаёт журнал сборки в Claude и записывает объяснение в файл:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

С --output-format json полезная нагрузка ответа включает total_cost_usd и разбивку затрат по моделям, поэтому скриптовые вызывающие стороны могут отслеживать расходы на вызов без обращения к панели использования. Обе цифры являются оценками на стороне клиента и могут отличаться от вашего фактического счёта.

Если Claude Code не может прочитать stdin, например потому что процесс, который его запустил, отключил его конец, Claude Code выводит предупреждение в stderr и продолжает работу с запросом из командной строки. До версии v2.1.211 нечитаемый stdin на Windows приводил к сбою сессии или молчаливому выходу без вывода.

Добавление Claude в скрипт сборки

Вы можете обернуть неинтерактивный вызов в скрипт, чтобы использовать Claude как проектный линтер или рецензент.

Этот скрипт package.json передаёт diff относительно main в Claude и просит его сообщить об опечатках. Передача diff означает, что Claude не нуждается в разрешении Bash для его чтения, а экранированные двойные кавычки делают скрипт портативным для Windows:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Запустите его с помощью npm run lint:claude.

Получение структурированного вывода

Используйте --output-format для управления тем, как возвращаются ответы:

  • text (по умолчанию): простой текстовый вывод
  • json: структурированный JSON с результатом, ID сессии и метаданными
  • stream-json: JSON с разделением по строкам для потоковой передачи в реальном времени

Этот пример возвращает сводку проекта в виде JSON с метаданными сессии, с текстовым результатом в поле result:

claude -p "Summarize this project" --output-format json

Чтобы получить вывод, соответствующий определённой схеме, используйте --output-format json с --json-schema и определением JSON Schema. Ответ включает метаданные о запросе (ID сессии, использование и т.д.) со структурированным выводом в поле structured_output.

Этот пример извлекает имена функций и возвращает их как массив строк:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Если значение не является действительной JSON Schema, claude выходит с Error: --json-schema is not a valid JSON Schema, за которым следует диагностика валидатора. Claude Code принимает схемы, которые используют ключевое слово format, такие как "format": "email", но рассматривает format как аннотацию и не применяет его. До версии v2.1.205 Claude Code молча игнорировал недействительную схему и возвращал неструктурированный текст, а также рассматривал любую схему, содержащую format, как недействительную.

Потоковая передача ответов

Используйте --output-format stream-json с --verbose и --include-partial-messages для получения токенов по мере их генерации. Каждая строка — это объект JSON, представляющий событие:

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

Последняя строка потока — это сообщение result с финальным текстом ответа, стоимостью и метаданными сессии.

Если ваш потребитель читает поток медленно, Claude Code ждёт, пока очередной вывод будет слит, прежде чем выйти, масштабируя ожидание в зависимости от того, сколько ещё в очереди, с максимумом 30 секунд. До версии v2.1.214 ожидание выхода было ограничено примерно двумя секундами, что могло обрезать конец большого ответа.

Следующий пример использует jq для фильтрации текстовых дельт и отображения только потокового текста. Флаг -r выводит необработанные строки (без кавычек), а -j объединяет без новых строк, чтобы токены передавались непрерывно:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Для программной потоковой передачи с обратными вызовами и объектами сообщений см. Stream responses in real-time в документации Agent SDK.

Отслеживание сообщений подагентов

Сообщения от подагентов появляются в потоке как сообщения assistant и user, чьё поле parent_tool_use_id является ID вызова инструмента, который запустил подагента. Сообщения из основного разговора содержат null в этом поле.

Первое сообщение от подагента, работающего на переднем плане, — это сообщение user, содержащее запрос, который его управляет. После этого первого сообщения Claude Code выдаёт:

  • По умолчанию: блоки tool_use и tool_result подагента.
  • С --forward-subagent-text или CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: также текстовые и thinking блоки подагента, чтобы вы могли восстановить транскрипт каждого подагента. Это требует Claude Code v2.1.211 или позже.

Когда вы включаете любой из этих параметров, Claude Code пересылает сообщения от подагентов на каждом уровне вложенности: когда подагент запускает собственного подагента, сообщения вложенного подагента содержат ID вызова Agent инструмента, который его запустил, в parent_tool_use_id, поэтому вы можете перестроить полное дерево вложенности, следуя этим ID. До версии v2.1.219 сообщения от вложенных подагентов не появлялись в потоке.

Skills, которые работают в подагенте, появляются в потоке так же: первое сообщение разветвлённого skill — это сообщение user, содержащее содержимое skill, которое управляет запуском. Если вы включаете любой из этих параметров, поток также содержит текстовые и thinking блоки разветвлённого skill. До версии v2.1.265 в потоке появлялись только блоки tool_use и tool_result разветвлённого skill.

Обработка повторных попыток API

Когда запрос API завершается с повторяемой ошибкой, Claude Code выдаёт событие system/api_retry перед повторной попыткой. На версии v2.1.246 или позже, когда 401 или 403 отклоняет учётные данные apiKeyHelper, Claude Code делает первые две повторные попытки молча без события, затем выдаёт событие как обычно с третьей последовательной повторной попытки и далее. Молчаливые повторные попытки по-прежнему учитываются в attempt. Вы можете использовать событие для отображения прогресса повторной попытки в вашем собственном интерфейсе.

Поле Тип Описание
type "system" тип сообщения
subtype "api_retry" определяет это как событие повторной попытки
attempt целое число номер текущей попытки, начиная с 1
max_retries целое число всего разрешённых повторных попыток для этой причины отказа, что может быть меньше, чем бюджет на уровне сессии
retry_delay_ms целое число миллисекунды до следующей попытки
error_status целое число или null код состояния HTTP неудачной попытки или null, когда попытка не получила HTTP ответ от API
no_response объект, опционально присутствует только когда неудачная попытка получила отсутствие заголовков ответа вовремя. waited_ms — это время ожидания этой попытки, а retry_wait_ms — это время ожидания повторной попытки. В этих событиях max_retries отражает одну повторную попытку, которую обычно получает эта причина, а не бюджет на уровне сессии. Требует Claude Code v2.1.261 или позже
error строка категория ошибки: authentication_failed, oauth_org_not_allowed, account_on_hold, billing_error, rate_limit, overloaded, invalid_request, model_not_found, server_error, max_output_tokens, cloud_credential_error или unknown
uuid строка уникальный идентификатор события
session_id строка сессия, к которой принадлежит событие

Чтение метаданных сессии

Событие system/init сообщает метаданные сессии, включая модель, инструменты, MCP серверы и загруженные плагины. Это первое событие в потоке, если не установлены события запуска:

  • события plugin_install, когда установлена CLAUDE_CODE_SYNC_PLUGIN_INSTALL.
  • события hook_started, hook_progress и hook_response, пока работает настроенный hook SessionStart или Setup. Они передаются потоком по мере их создания. Claude Code v2.1.169 через v2.1.203 доставлял их одной партией после завершения hook, всё ещё впереди system/init; v2.1.204 восстановил живую доставку.

Событие также содержит опциональный массив capabilities строк, называющих поведения протокола, которые реализует эта версия Claude Code, такие как interrupt_receipt_v1 или interrupt_cancel_queued_v1. Проверьте его для обнаружения функций вместо сравнения строк версий и игнорируйте значения, которые вы не распознаёте. Поле требует Claude Code v2.1.205 или позже и отсутствует в более ранних версиях. См. SDKSystemMessage для списка возможностей.

Отказ CI, когда плагин или MCP сервер не загружается

Используйте поля плагина в событии system/init для отказа плагина, который не загрузился:

Поле Тип Описание
plugins массив плагины, которые успешно загрузились, каждый с name и path
plugin_errors массив ошибки загрузки плагина, каждая с plugin, type и message. Включает неудовлетворённые версии зависимостей и ошибки загрузки --plugin-dir, такие как отсутствующий путь или недействительный архив. Затронутые плагины понижены в приоритете и отсутствуют в plugins. Ключ опускается, когда ошибок нет

Используйте поля MCP сервера так же. Когда вы передаёте --mcp-config с -p, Claude Code ждёт всё ещё ожидающих серверов перед запуском первого хода, до MCP_TIMEOUT стартового таймаута, 30 секунд по умолчанию. Удалённый сервер с кэшированным списком инструментов пропускает ожидание, показывает pending в system/init и подключается при первом вызове инструмента. Ожидание требует Claude Code v2.1.221 или позже.

Claude Code проверяет каждую запись --mcp-config при запуске и пропускает записи, которые не прошли проверку, например запись url без type. Запуск продолжается и выходит чисто, поэтому проверьте эти поля для отказа сервера, который никогда не загружался:

Поле Тип Описание
mcp_servers массив MCP серверы в сессии, каждый с name и status
mcp_server_errors массив записи --mcp-config, пропущенные проверкой конфигурации, каждая с name, type и message. type — это категория пропуска, такая как unknown_type, url_missing_type, invalid_config или reserved_name; рассматривайте значения, которые вы не распознаёте, как общий пропуск. Затронутые серверы отсутствуют в mcp_servers. Ключ опускается, когда ошибок нет, поэтому ворота CI могут отказать на непустом массиве. Требует Claude Code v2.1.219 или позже

Когда вы запускаете команду вручную в терминале, Claude Code также выводит предупреждение при запуске в stderr, такое как Warning: 1 MCP server skipped due to invalid config:, за которым следует причина для каждой пропущенной записи. Когда вы перенаправляете stderr или когда программа, такая как CI runner или SDK хост, захватывает его, Claude Code не выводит предупреждение и сообщает пропущенные записи только в поле mcp_server_errors. Предупреждение требует Claude Code v2.1.219 или позже.

Отслеживание установок плагинов

Когда установлена CLAUDE_CODE_SYNC_PLUGIN_INSTALL, Claude Code выдаёт события system/plugin_install во время установки плагинов marketplace перед первым ходом. Используйте их для отображения прогресса установки в вашем собственном пользовательском интерфейсе.

Поле Тип Описание
type "system" тип сообщения
subtype "plugin_install" определяет это как событие установки плагина
status "started", "installed", "failed" или "completed" started и completed охватывают общую установку; installed и failed сообщают об отдельных marketplaces
name строка, опционально имя marketplace, присутствует на installed и failed
error строка, опционально сообщение об ошибке, присутствует на failed
uuid строка уникальный идентификатор события
session_id строка сессия, к которой принадлежит событие

Автоматическое одобрение инструментов

Используйте --allowedTools для разрешения Claude использовать определённые инструменты без запроса. Этот пример запускает набор тестов и исправляет ошибки, позволяя Claude выполнять команды Bash и читать/редактировать файлы без запроса разрешения:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Чтобы установить базовый уровень для всей сессии вместо перечисления отдельных инструментов, передайте режим разрешений. Для -p встроенный стартовый режим разрешений — это Manual на каждом плане, поэтому передайте нужный вам режим разрешений:

Этот пример применяет исправления lint с acceptEdits в качестве базовой линии:

claude -p "Apply the lint fixes" --permission-mode acceptEdits

Отключение запросов разрешений в автоматических запусках

Передайте --permission-prompts none, когда никто не доступен для ответа на запросы разрешений, например в запланированном задании. Флаг имеет наибольшее значение, когда ваш запуск имеет хост разрешений: приложение Agent SDK с обратным вызовом canUseTool или инструмент MCP, который вы передаёте с --permission-prompt-tool. Без флага ваш запуск консультирует хост по каждому запросу разрешения и ждёт его.

С флагом ваш запуск не консультирует хост и не ждёт его. Всё, что вызвало бы запрос, отклоняется, если hook PermissionRequest не разрешает это, Claude сообщается, что никто не может одобрить запрос и не должен повторять попытку, и запуск продолжается. В запуске -p без хоста эти запросы отклоняются в любом случае, и флаг также сообщает Claude не повторять попытку. Правила разрешений, hooks PermissionRequest и режим разрешений, который вы установили, по-прежнему решают каждый вызов в первую очередь; Claude Code отклоняет только запросы, которые ничто другое не разрешает.

Этот пример запускает автоматическое задание в режиме auto. Классификатор проверяет каждое действие как обычно, и Claude Code отклоняет всё, что в противном случае привело бы к запросу разрешения:

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

С --permission-prompts none, Claude Code удаляет инструменты, которые требуют ответа от человека, такие как AskUserQuestion, поэтому Claude не может их вызвать. Любой запрос MCP elicitation, на который не ответит hook Elicitation, отменяется.

С --output-format stream-json, отказы появляются как системные сообщения permission_denied, и финальное сообщение результата перечисляет их в permission_denials.

Создание коммита

Этот пример проверяет поставленные в очередь изменения и создаёт коммит с соответствующим сообщением:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Флаг --allowedTools использует синтаксис правил разрешений. Завершающий * включает сопоставление префиксов, поэтому Bash(git diff *) разрешает любую команду, начинающуюся с git diff. Пробел перед * важен: без него Bash(git diff*) также совпадал бы с git diff-index.

Настройка системного запроса

Используйте --append-system-prompt для добавления инструкций при сохранении поведения Claude Code по умолчанию. Этот пример передаёт diff PR в Claude и инструктирует его проверить на уязвимости безопасности. Сохраните его как shell скрипт, например review.sh:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

В скрипте "$1" обозначает первый аргумент, который вы передаёте в командной строке. Запустите bash review.sh 123, и shell заменит "$1" на 123, поэтому скрипт получает diff для PR 123. Claude Code выводит рецензию как JSON, с текстом в поле result.

См. флаги системного запроса для получения дополнительных параметров, включая --system-prompt для полной замены запроса по умолчанию.

Продолжение разговоров

Используйте --continue для продолжения самого последнего разговора или --resume с ID сессии для продолжения определённого разговора. На Claude Code v2.1.257 или позже, когда вы передаёте --continue, Claude Code открывает фоновую сессию, которая завершилась, но не ту, которая всё ещё работает. Этот пример запускает проверку, а затем отправляет дополнительные запросы:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Если вы запускаете несколько разговоров, захватите ID сессии для возобновления определённого:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Вы можете запустить две команды из разных каталогов: Claude Code находит сессию по её ID в любом проекте на этой машине. До версии v2.1.223 Claude Code искал ID только в текущем каталоге проекта и его git worktrees, поэтому вам приходилось запускать обе команды из одного каталога.

Вместо ID сессии вы можете передать --resume абсолютный путь к файлу транскрипта .jsonl сессии, и Claude Code продолжит разговор, сохранённый в этом файле.

Следующие шаги

  • Agent SDK quickstart: создайте своего первого агента с помощью Python или TypeScript
  • CLI reference: все флаги и параметры CLI
  • GitHub Actions: используйте Agent SDK в рабочих процессах GitHub
  • GitLab CI/CD: используйте Agent SDK в конвейерах GitLab