Запуск 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, включают:

• --continue для продолжения разговоров
• --allowedTools для автоматического одобрения инструментов
• --output-format для структурированного вывода

Этот пример задаёт 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, чтения файлов и редактирования файлов. Передайте любой необходимый контекст с флагом:

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

Если 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, plugins, автоматической памяти или 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 и продолжит работу с приглашением из командной строки. До версии 2.1.211 нечитаемый stdin на Windows приводил к сбою сеанса или молчаливому выходу без вывода.

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

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

Этот скрипт 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 как аннотацию и не применяет её. До версии 2.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 секунд. До версии 2.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'

Для программной потоковой передачи с обратными вызовами и объектами сообщений см. Потоковая передача ответов в реальном времени в документации 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 версии 2.1.211 или позже.

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

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

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

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

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

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

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

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

Сбой CI, когда plugin или MCP сервер не загружается

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

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

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

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

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

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

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

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

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

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

• auto: передайте --permission-mode auto, чтобы классификатор проверил большинство действий вместо вас
• dontAsk: Claude Code отклоняет каждый вызов, который иначе вызвал бы запрос, что полезно для заблокированных CI запусков. Действия, которые не требуют одобрения в режиме Manual, всё ещё выполняются, такие как чтение файлов в ваших рабочих каталогах и набор команд только для чтения, а также действия, которые охватывают ваши записи --allowedTools или правила permissions.allow. AskUserQuestion, инструменты соединителя которые ваша организация установила на ask и MCP инструменты, отмеченные requiresUserInteraction, отклоняются даже когда правило разрешения совпадает
• acceptEdits: Claude записывает файлы без запроса, и Claude Code автоматически одобряет распространённые команды файловой системы, такие как mkdir, touch, mv и cp. Действия, которые ни один режим не одобряет автоматически, всё ещё применяются. Помимо набора команд только для чтения, другие команды shell и сетевые запросы всё ещё требуют записи --allowedTools или правила permissions.allow. См. что acceptEdits автоматически одобряет для полного списка

Этот пример применяет исправления 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 версии 2.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 в любом проекте на этой машине. До версии 2.1.223 Claude Code искал ID только в текущем каталоге проекта и его git worktrees, поэтому вам пришлось бы запустить обе команды из одного каталога.

Вместо ID сеанса вы можете передать --resume абсолютный путь к файлу транскрипта .jsonl сеанса](/ru/sessions#where-transcripts-are-stored), и Claude Code продолжит разговор, сохранённый в этом файле.

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

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