Запуск 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, включая:
--continueдля продолжения разговоров--allowedToolsдля автоматического одобрения инструментов--output-formatдля структурированного вывода
Этот пример задаёт Claude вопрос о вашей кодовой базе и выводит ответ:
claude -p "What does the auth module do?"
Начните быстрее с режимом bare
Добавьте --bare для сокращения времени запуска путём пропуска автоматического обнаружения hooks, skills, plugins, MCP серверов, автоматической памяти и CLAUDE.md. Без этого claude -p загружает тот же контекст, что и интерактивная сессия, включая всё, что настроено в рабочем каталоге или ~/.claude.
Режим bare полезен для CI и скриптов, где вам нужен одинаковый результат на каждой машине. Hook в ~/.claude коллеги или MCP сервер в .mcp.json проекта не будут запущены, потому что режим bare никогда их не читает. Действуют только явно переданные флаги.
Этот пример запускает одноразовую задачу суммирования в режиме bare и предварительно одобряет инструмент Read, чтобы вызов завершился без запроса разрешения:
claude --bare -p "Summarize this file" --allowedTools "Read"
В режиме 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> |
Режим bare пропускает OAuth и чтение из связки ключей. Аутентификация Anthropic должна поступать из ANTHROPIC_API_KEY или apiKeyHelper в JSON, переданном в --settings. Bedrock, Vertex и Foundry используют обычные учётные данные поставщика.
Фоновые задачи при выходе
Если Claude запускает фоновую задачу Bash во время выполнения claude -p, например сервер разработки или сборку с отслеживанием, эта задача завершается примерно через пять секунд после того, как Claude вернул свой окончательный результат и stdin закрыт. Период ожидания позволяет задаче, которая завершается сразу после результата, всё ещё доставить свой вывод. До версии v2.1.163 никогда не завершающийся фоновый процесс держал бы вызов claude -p открытым неопределённо долго.
Примеры
Эти примеры выделяют общие паттерны CLI. Для CI и других скриптовых вызовов добавьте --bare, чтобы они не подхватывали то, что случайно настроено локально.
Передача данных через 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 в скрипт сборки
Вы можете обернуть неинтерактивный вызов в скрипт, чтобы использовать 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.\""
}
}
Получение структурированного вывода
Используйте --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"]}'
Потоковая передача ответов
Используйте --output-format stream-json с --verbose и --include-partial-messages для получения токенов по мере их генерации. Каждая строка — это объект JSON, представляющий событие:
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
Следующий пример использует 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'
Когда запрос API завершается с повторяемой ошибкой, Claude Code выдаёт событие system/api_retry перед повторной попыткой. Вы можете использовать это для отображения прогресса повторной попытки или реализации пользовательской логики отката.
| Поле | Тип | Описание |
|---|---|---|
type |
"system" |
тип сообщения |
subtype |
"api_retry" |
определяет это как событие повторной попытки |
attempt |
целое число | номер текущей попытки, начиная с 1 |
max_retries |
целое число | всего разрешённых повторных попыток |
retry_delay_ms |
целое число | миллисекунды до следующей попытки |
error_status |
целое число или null | код состояния HTTP или null для ошибок соединения без HTTP ответа |
error |
строка | категория ошибки: authentication_failed, oauth_org_not_allowed, billing_error, rate_limit, overloaded, invalid_request, model_not_found, server_error, max_output_tokens или unknown |
uuid |
строка | уникальный идентификатор события |
session_id |
строка | сессия, к которой принадлежит событие |
Событие system/init сообщает метаданные сессии, включая модель, инструменты, MCP серверы и загруженные плагины. Это первое событие в потоке, если не установлена CLAUDE_CODE_SYNC_PLUGIN_INSTALL, в этом случае события plugin_install предшествуют ему. Используйте поля плагина для отказа CI, когда плагин не загрузился:
| Поле | Тип | Описание |
|---|---|---|
plugins |
массив | плагины, которые успешно загрузились, каждый с name и path |
plugin_errors |
массив | ошибки загрузки плагина, каждая с plugin, type и message. Включает неудовлетворённые версии зависимостей и ошибки загрузки --plugin-dir, такие как отсутствующий путь или недействительный архив. Затронутые плагины понижены в приоритете и отсутствуют в plugins. Ключ опускается, когда ошибок нет |
Когда установлена 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 |
строка | сессия, к которой принадлежит событие |
Для программной потоковой передачи с обратными вызовами и объектами сообщений см. Stream responses in real-time в документации Agent SDK.
Автоматическое одобрение инструментов
Используйте --allowedTools для разрешения Claude использовать определённые инструменты без запроса. Этот пример запускает набор тестов и исправляет ошибки, позволяя Claude выполнять команды Bash и читать/редактировать файлы без запроса разрешения:
claude -p "Run the test suite and fix any failures" \
--allowedTools "Bash,Read,Edit"
Чтобы установить базовый уровень для всей сессии вместо перечисления отдельных инструментов, передайте режим разрешений. dontAsk отклоняет всё, что не входит в ваши правила permissions.allow или набор команд только для чтения, что полезно для заблокированных CI запусков. acceptEdits позволяет Claude писать файлы без запроса и также автоматически одобряет общие команды файловой системы, такие как mkdir, touch, mv и cp. Другие команды оболочки и сетевые запросы по-прежнему требуют записи --allowedTools или правила permissions.allow, иначе запуск прерывается при попытке выполнить одну из них:
claude -p "Apply the lint fixes" --permission-mode acceptEdits
Создание коммита
Этот пример проверяет поставленные в очередь изменения и создаёт коммит с соответствующим сообщением:
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 и инструктирует его проверить на уязвимости безопасности:
gh pr diff "$1" | claude -p \
--append-system-prompt "You are a security engineer. Review for vulnerabilities." \
--output-format json
См. флаги системного запроса для получения дополнительных параметров, включая --system-prompt для полной замены запроса по умолчанию.
Продолжение разговоров
Используйте --continue для продолжения самого последнего разговора или --resume с ID сессии для продолжения определённого разговора. Этот пример запускает проверку, а затем отправляет дополнительные запросы:
# 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"
Запустите обе команды из одного каталога: поиск ID сессии ограничен текущим каталогом проекта и его git worktrees. См. Resume a session для полного набора правил области видимости.
Следующие шаги
- Agent SDK quickstart: создайте своего первого агента с помощью Python или TypeScript
- CLI reference: все флаги и параметры CLI
- GitHub Actions: используйте Agent SDK в рабочих процессах GitHub
- GitLab CI/CD: используйте Agent SDK в конвейерах GitLab