options, который вы передаёте при его запуске. На этой странице показано, как составить объект options и какие файлы настроек и переменные окружения его контролируют.
Для каждого параметра его типа и значения по умолчанию см. ссылки Options (TypeScript) и ClaudeAgentOptions (Python).
Передача параметров в сеанс
Каждый вызовquery() принимает объект параметров: Options в TypeScript, ClaudeAgentOptions в Python. Каждое поле является необязательным, и сеанс, запущенный без параметров, работает с значениями по умолчанию SDK. Пример ниже настраивает сеанс только для чтения, который суммирует открытые TODO проекта. Пары читаются как TypeScript / Python, где написание отличается:
model: выбирает модельallowedTools/allowed_tools: предварительно одобряет список инструментов только для чтенияmaxTurns/max_turns: ограничивает количество ходовcwd: устанавливает рабочий каталог
cwd на один из ваших собственных проектов и запустите пример. Сводка открытых TODO этого проекта выводится при поступлении сообщения результата.
allowedTools (TypeScript) или allowed_tools (Python) предварительно одобряет перечисленные инструменты, поэтому вызовы к ним выполняются без остановки для одобрения. Инструменты вне списка остаются доступными. Когда Claude вызывает инструмент, не указанный в списке, режим разрешений определяет, будет ли вызов выполнен. Для получения дополнительной информации см. Правила разрешения и запрета.
Загрузка файлов настроек
Файлы настроек предоставляют конфигурацию за пределами объекта параметров. Два параметра контролируют способ их загрузки:settingSources/setting_sources: контролирует, какие источники файловой системы загружаются: пользователь, проект и локальный. Файлы настроек и файлы CLAUDE.md поступают через эти источники.settings: загружает путь файла настроек или встроенную строку JSON на любом языке, и TypeScript также принимает объект настроек. Какую бы форму вы ни передали, она переопределяет пользовательские, проектные и локальные настройки файловой системы; только управляемые политики имеют более высокий приоритет. Ссылки документируют полный порядок приоритета в разделе Приоритет настроек для TypeScript и Приоритет настроек для Python.
[] для отключения пользовательских, проектных и локальных настроек. Для получения дополнительной информации см. Использование функций Claude Code в SDK.
Выбор модели
Если параметрmodel, ваши настройки или окружение не выбирают модель, новый сеанс запускается на модели по умолчанию Claude Code. Для порядка этих источников см. Установка вашей модели. Установите model для закрепления определённой модели или выберите меньшую для более быстрых и дешёвых агентов. Значение принимает псевдоним модели или полное имя модели; псевдонимы и версии, на которые они разрешаются, перечислены в разделе Псевдонимы моделей.
Установите fallbackModel (TypeScript) или fallback_model (Python) для указания резервной модели. Когда основная модель перегружена или недоступна, сеанс переключается на резервную. Основная модель повторяется в начале каждого хода пользователя, поэтому сеанс возвращается к ней после окончания сбоя.
На обоих языках параметр принимает одну модель или разделённый запятыми список резервных копий. Для порядка и ограничения цепи см. Цепи резервных моделей. В TypeScript резервная копия, равная model, вызывает ошибку при запуске.
Примеры ниже показывают список резервных копий в TypeScript и одну резервную копию в Python:
Параметры запроса Messages API
temperature, top_p и max_tokens не имеют полей в объекте параметров ни на одном языке. Установите уровень усилий или ограничение расходов вместо этого, или вызовите Messages API, когда вам нужны эти параметры напрямую.Установка переменных окружения
Параметрenv устанавливает переменные окружения для процесса Claude Code, который запускает ваш сеанс. Различаются ли ваши значения заменяют унаследованное окружение или объединяются с ним в зависимости от языка:
- TypeScript:
envзаменяет окружение подпроцесса - Python: SDK объединяет ваши значения с унаследованным окружением, и ваши значения переопределяют унаследованные
process.env в env для сохранения унаследованных переменных, таких как PATH, HOME и ANTHROPIC_API_KEY. Когда вы оставляете env неустановленным, подпроцесс наследует ваше окружение на обоих языках.
Пример маршрутизирует трафик API через шлюз путём установки ANTHROPIC_BASE_URL.
Установка рабочего каталога
Установитеcwd для запуска сеанса в определённом каталоге. Когда вы оставляете cwd неустановленным, сеанс запускается в рабочем каталоге вашего процесса. Ни один SDK не имеет установщика для cwd. Для запуска в другом каталоге запустите другой сеанс с этим cwd.
Claude Code читает рабочий каталог для определения:
- Настройки проекта и hooks: какие настройки и hooks проекта загружаются
- Skills: где обнаруживаются skills сеанса
- Хранилище сеанса: какому проекту принадлежит сохранённый сеанс
additionalDirectories (TypeScript) или add_dirs (Python). Для области этого разрешения см. Дополнительные каталоги предоставляют доступ к файлам, а не конфигурацию.
Ограничение ходов и расходов
Ограничьте ходы и расходы с помощьюmaxTurns / max_turns и maxBudgetUsd / max_budget_usd. Оба ограничения отключены, когда не установлены. Когда сеанс достигает ограничения, запуск заканчивается сообщением результата, подтип которого называет ограничение, error_max_turns или error_max_budget_usd. Что происходит дальше, зависит от режима ввода:
- Одноразовый
query(): SDK выдаёт результат ограничения, а затем вызывает исключение, поэтому оберните цикл в блок try для продолжения после ошибки - Потоковый ввод: сеанс остаётся активным после результата ограничения, и счётчик максимальных ходов начинается заново для каждого сообщения в очереди. Общий бюджет накапливается по сообщениям, и как только расходы достигают ограничения, более поздние сообщения в одном разговоре заканчиваются тем же результатом бюджета.
/clearначинает бюджет заново
0 по-разному:
maxTurns/max_turns:0запускает сеанс без ограничения ходов, то же самое, что оставить параметр неустановленнымmaxBudgetUsd/max_budget_usd: CLI отклоняет0как недопустимую сумму при запуске, и сеанс никогда не запускается
Изменение конфигурации во время сеанса
Когда вы запускаете сеанс с потоковым вводом, вы можете переключать его модель и режим разрешений во время его работы. Где вы вызываете установщики, зависит от языка:- TypeScript: методы на объекте, который возвращает
query() - Python: методы на
ClaudeSDKClient, так какquery()возвращает простой итератор без методов управления
setModel()/set_model(): переключает модель. Вызовите её без модели для переключения на модель по умолчанию Claude Code вместоmodel, которую вы передали в параметрах.setPermissionMode()/set_permission_mode(): переключает режим разрешений
applyFlagSettings() и updateSettings():
applyFlagSettings(): применяет настройки во время выполнения, как вawait session.applyFlagSettings({ effortLevel: "high" }). Метод принимает ключи файла настроек, а не поля параметров, поэтому проверьте справочникapplyFlagSettings()для схемы и для того, какие ключи вступают в силу во время сеанса.updateSettings(): записывает разрешённый набор ключей в локальный файл настроек проекта, как вawait session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Записанные ключи вступают в силу при следующем запросе сеанса и сохраняются для более поздних сеансов, которые загружают настройкиlocal. Строка метода в таблице методов называет разрешённые ключи и минимальную версию.
First turn model: claude-sonnet-5, затем Second turn model: claude-opus-5 после переключения.
Каждая модель имеет свой собственный кэш подсказок, поэтому после переключения во время сеанса следующий запрос пересчитывает полный разговор без кэша по ставкам новой модели. Для получения дополнительной информации см. Переключение моделей.
Настройка конкретных функций
Таблица ниже сопоставляет каждый параметр с функцией, которую он настраивает. Для параметров, которые эта страница не охватывает, см. справочники TypeScript и Python. Если вы знаете вашу цель, но не знаете, какой параметр её обслуживает, начните с Выбор правильной функции.Следующие шаги
Чтобы увидеть конфигурацию, составленную в рабочих агентов:- Quickstart: создайте и запустите первого агента от начала до конца
- Примеры: найдите полный, запускаемый проект или управляемый рецепт Claude Cookbook, который соответствует тому, что вы хотите создать
- Изоляция мультитенантности: изолируйте настройки и память каждого тенанта с помощью
settingSources/setting_sources,envиcwd