-p с вашим запросом и любыми параметрами CLI:
claude -p). Для пакетов Python и TypeScript SDK со структурированными выходами, обратными вызовами одобрения инструментов и собственными объектами сообщений см. полную документацию Agent SDK.
Базовое использование
Добавьте флаг-p (или --print) к любой команде claude для запуска её в неинтерактивном режиме. Все параметры CLI работают с -p, включая:
--continueдля продолжения разговоров--allowedToolsдля автоматического одобрения инструментов--output-formatдля структурированного вывода
Начните быстрее с режимом bare
Добавьте--bare для сокращения времени запуска путём пропуска автоматического обнаружения hooks, skills, plugins, MCP серверов, автоматической памяти и CLAUDE.md. Без этого claude -p загружает тот же контекст, что и интерактивная сессия, включая всё, что настроено в рабочем каталоге или ~/.claude.
Режим bare полезен для CI и скриптов, где вам нужен одинаковый результат на каждой машине. Hook в ~/.claude коллеги или MCP сервер в .mcp.json проекта не будут запущены, потому что режим bare никогда их не читает. Действуют только явно переданные флаги.
Этот пример запускает одноразовую задачу суммирования в режиме bare и предварительно одобряет инструмент Read, чтобы вызов завершился без запроса разрешения:
Режим bare пропускает OAuth и чтение из связки ключей. Аутентификация Anthropic должна поступать из
ANTHROPIC_API_KEY или apiKeyHelper в JSON, переданном в --settings. Amazon Bedrock, Google Cloud’s Agent Platform и Microsoft Foundry используют обычные учётные данные поставщика.
--bare — это рекомендуемый режим для скриптовых и SDK вызовов, и он станет режимом по умолчанию для -p в будущем выпуске.Фоновые задачи при выходе
Если Claude запускает фоновую задачу Bash во время выполненияclaude -p, например сервер разработки или сборку с отслеживанием, эта задача завершается примерно через пять секунд после того, как Claude вернул свой окончательный результат и stdin закрыт. Период ожидания позволяет задаче, которая завершается сразу после результата, всё ещё доставить свой вывод. До версии v2.1.163 никогда не завершающийся фоновый процесс держал бы вызов claude -p открытым неопределённо долго.
Фоновые подагенты и рабочие процессы освобождены от пятисекундного периода ожидания, потому что их результат является частью окончательного вывода, поэтому claude -p ждёт их завершения. Начиная с версии v2.1.182, это ожидание ограничено десятью минутами по умолчанию, чтобы застрявший фоновый агент не мог держать процесс открытым неопределённо долго. Отрегулируйте ограничение с помощью CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS или установите его на 0, чтобы ждать без ограничений.
Примеры
Эти примеры выделяют общие паттерны CLI. Для CI и других скриптовых вызовов добавьте--bare, чтобы они не подхватывали то, что случайно настроено локально.
Передача данных через Claude
Неинтерактивный режим читает stdin, поэтому вы можете передавать данные и перенаправлять ответ, как любой другой инструмент командной строки. Этот пример передаёт журнал сборки в Claude и записывает объяснение в файл:--output-format json полезная нагрузка ответа включает total_cost_usd и разбивку затрат по моделям, поэтому скриптовые вызывающие стороны могут отслеживать расходы на вызов без обращения к панели использования.
Начиная с Claude Code v2.1.128, piped stdin ограничен 10MB. Если вы превысите лимит, Claude Code выходит с чётким сообщением об ошибке и ненулевым статусом. Для работы с большими входными данными запишите содержимое в файл и ссылайтесь на путь файла в вашем запросе вместо передачи через pipe.
Добавление Claude в скрипт сборки
Вы можете обернуть неинтерактивный вызов в скрипт, чтобы использовать Claude как проектный линтер или рецензент. Этот скриптpackage.json передаёт diff относительно main в Claude и просит его сообщить об опечатках. Передача diff означает, что Claude не нуждается в разрешении Bash для его чтения, а экранированные двойные кавычки делают скрипт портативным для Windows:
Получение структурированного вывода
Используйте--output-format для управления тем, как возвращаются ответы:
text(по умолчанию): простой текстовый выводjson: структурированный JSON с результатом, ID сессии и метаданнымиstream-json: JSON с разделением по строкам для потоковой передачи в реальном времени
result:
--output-format json с --json-schema и определением JSON Schema. Ответ включает метаданные о запросе (ID сессии, использование и т.д.) со структурированным выводом в поле structured_output.
Этот пример извлекает имена функций и возвращает их как массив строк:
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, представляющий событие:
result с финальным текстом ответа, стоимостью и метаданными сессии. До версии v2.1.208 передача большого ответа могла обрезать финальную строку и опустить сообщение result.
Следующий пример использует jq для фильтрации текстовых дельт и отображения только потокового текста. Флаг -r выводит необработанные строки (без кавычек), а -j объединяет без новых строк, чтобы токены передавались непрерывно:
system/api_retry перед повторной попыткой. Вы можете использовать это для отображения прогресса повторной попытки или реализации пользовательской логики отката.
Событие
system/init сообщает метаданные сессии, включая модель, инструменты, MCP серверы и загруженные плагины. Это первое событие в потоке, если не установлены события запуска:
- события
plugin_install, когда установленаCLAUDE_CODE_SYNC_PLUGIN_INSTALL. - события
hook_started,hook_progressиhook_response, пока работает настроенный hookSessionStartилиSetup. Они передаются потоком по мере их создания. Claude Code v2.1.169 через v2.1.203 доставлял их одной партией после завершения hook, всё ещё впередиsystem/init; v2.1.204 восстановил живую доставку.
capabilities строк, называющих поведения протокола, которые реализует эта версия Claude Code, такие как interrupt_receipt_v1. Проверьте его для обнаружения функций вместо сравнения строк версий и игнорируйте значения, которые вы не распознаёте. Поле требует Claude Code v2.1.205 или позже и отсутствует в более ранних версиях. См. SDKSystemMessage для списка возможностей.
Используйте поля плагина для отказа CI, когда плагин не загрузился:
Когда установлена
CLAUDE_CODE_SYNC_PLUGIN_INSTALL, Claude Code выдаёт события system/plugin_install во время установки плагинов marketplace перед первым ходом. Используйте их для отображения прогресса установки в вашем собственном пользовательском интерфейсе.
Для программной потоковой передачи с обратными вызовами и объектами сообщений см. Stream responses in real-time в документации Agent SDK.
Автоматическое одобрение инструментов
Используйте--allowedTools для разрешения Claude использовать определённые инструменты без запроса. Этот пример запускает набор тестов и исправляет ошибки, позволяя Claude выполнять команды Bash и читать/редактировать файлы без запроса разрешения:
dontAsk отклоняет всё, что не входит в ваши правила permissions.allow или набор команд только для чтения, что полезно для заблокированных CI запусков. AskUserQuestion, инструменты соединителя которые ваша организация установила на ask и MCP инструменты, отмеченные requiresUserInteraction, отклоняются даже когда правило разрешения совпадает.
acceptEdits позволяет Claude писать файлы без запроса и также автоматически одобряет общие команды файловой системы, такие как mkdir, touch, mv и cp. Другие команды оболочки и сетевые запросы по-прежнему требуют записи --allowedTools или правила permissions.allow, иначе запуск прерывается при попытке выполнить одну из них:
Создание коммита
Этот пример проверяет поставленные в очередь изменения и создаёт коммит с соответствующим сообщением:--allowedTools использует синтаксис правил разрешений. Завершающий * включает сопоставление префиксов, поэтому Bash(git diff *) разрешает любую команду, начинающуюся с git diff. Пробел перед * важен: без него Bash(git diff*) также совпадал бы с git diff-index.
Вызываемые пользователем skills и пользовательские команды работают в режиме
-p: включите /skill-name в строку запроса, и Claude Code развернёт её перед запуском. Встроенные команды, которые только работают в интерфейсе терминала, такие как /login, недоступны в режиме -p. /model, /effort, /fast, /color и /rename принимают значение как аргумент, например /model sonnet, и /mcp без аргумента выводит текстовую сводку статуса сервера; эти формы требуют Claude Code v2.1.205 или позже и следуют примечаниям доступности каждой команды. Чтобы изменить параметр из вызова -p, передайте key=value в /config, например /config thinking=false.Настройка системного запроса
Используйте--append-system-prompt для добавления инструкций при сохранении поведения Claude Code по умолчанию. Этот пример передаёт diff PR в Claude и инструктирует его проверить на уязвимости безопасности:
--system-prompt для полной замены запроса по умолчанию.
Продолжение разговоров
Используйте--continue для продолжения самого последнего разговора или --resume с ID сессии для продолжения определённого разговора. Этот пример запускает проверку, а затем отправляет дополнительные запросы:
Следующие шаги
- Agent SDK quickstart: создайте своего первого агента с помощью Python или TypeScript
- CLI reference: все флаги и параметры CLI
- GitHub Actions: используйте Agent SDK в рабочих процессах GitHub
- GitLab CI/CD: используйте Agent SDK в конвейерах GitLab