Skip to main content
Сеанс Agent SDK читает конфигурацию из файлов настроек, переменных окружения и объекта 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 объединяет ваши значения с унаследованным окружением, и ваши значения переопределяют унаследованные
В TypeScript распределите process.env в env для сохранения унаследованных переменных, таких как PATH, HOME и ANTHROPIC_API_KEY. Когда вы оставляете env неустановленным, подпроцесс наследует ваше окружение на обоих языках. Пример маршрутизирует трафик API через шлюз путём установки ANTHROPIC_BASE_URL.
Переменные, которые вы передаёте, также могут настраивать сам Claude Code. Для переменных, которые читает процесс Claude Code, см. Переменные окружения. Для настройки тайм-аутов API и обнаружения зависания таким образом следуйте разделу Handle slow or stalled API responses в справочнике TypeScript или справочнике Python.

Установка рабочего каталога

Установите cwd для запуска сеанса в определённом каталоге. Когда вы оставляете cwd неустановленным, сеанс запускается в рабочем каталоге вашего процесса. Ни один SDK не имеет установщика для cwd. Для запуска в другом каталоге запустите другой сеанс с этим cwd. Claude Code читает рабочий каталог для определения: Чтобы позволить инструментам получать доступ к файлам вне рабочего каталога, добавьте пути с помощью 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(): переключает режим разрешений
TypeScript также имеет applyFlagSettings() и updateSettings():
  • applyFlagSettings(): применяет настройки во время выполнения, как в await session.applyFlagSettings({ effortLevel: "high" }). Метод принимает ключи файла настроек, а не поля параметров, поэтому проверьте справочник applyFlagSettings() для схемы и для того, какие ключи вступают в силу во время сеанса.
  • updateSettings(): записывает разрешённый набор ключей в локальный файл настроек проекта, как в await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Записанные ключи вступают в силу при следующем запросе сеанса и сохраняются для более поздних сеансов, которые загружают настройки local. Строка метода в таблице методов называет разрешённые ключи и минимальную версию.
Пример ниже запускает двухходовой сеанс, изменяет конфигурацию между ходами и выводит модель, которая ответила на каждый ход. В TypeScript поток подсказок удерживает второе сообщение до тех пор, пока установщики не будут запущены, и второй ход выполняется на новой модели.
На Claude API программа выводит First turn model: claude-sonnet-5, затем Second turn model: claude-opus-5 после переключения.
Каждая модель имеет свой собственный кэш подсказок, поэтому после переключения во время сеанса следующий запрос пересчитывает полный разговор без кэша по ставкам новой модели. Для получения дополнительной информации см. Переключение моделей.

Настройка конкретных функций

Таблица ниже сопоставляет каждый параметр с функцией, которую он настраивает. Для параметров, которые эта страница не охватывает, см. справочники TypeScript и Python. Если вы знаете вашу цель, но не знаете, какой параметр её обслуживает, начните с Выбор правильной функции.

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

Чтобы увидеть конфигурацию, составленную в рабочих агентов:
  • Quickstart: создайте и запустите первого агента от начала до конца
  • Примеры: найдите полный, запускаемый проект или управляемый рецепт Claude Cookbook, который соответствует тому, что вы хотите создать
  • Изоляция мультитенантности: изолируйте настройки и память каждого тенанта с помощью settingSources / setting_sources, env и cwd