Установка переменных окружения

Параметр env устанавливает переменные окружения для процесса Claude Code, который запускает ваш сеанс. Различаются ли ваши значения заменяют унаследованное окружение или объединяются с ним в зависимости от языка:

• TypeScript: env заменяет окружение подпроцесса
• Python: SDK объединяет ваши значения с унаследованным окружением, и ваши значения переопределяют унаследованные

В TypeScript распределите process.env в env для сохранения унаследованных переменных, таких как PATH, HOME и ANTHROPIC_API_KEY. Когда вы оставляете env неустановленным, подпроцесс наследует ваше окружение на обоих языках.

Пример маршрутизирует трафик API через шлюз путём установки ANTHROPIC_BASE_URL.

const options = {
env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

options = ClaudeAgentOptions(
env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},
)

Переменные, которые вы передаёте, также могут настраивать сам Claude Code. Для переменных, которые читает процесс Claude Code, см. Переменные окружения. Для настройки тайм-аутов API и обнаружения зависания таким образом следуйте разделу Handle slow or stalled API responses в справочнике TypeScript или справочнике Python.

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

Установите 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(): переключает режим разрешений

TypeScript также имеет applyFlagSettings() и updateSettings():

• applyFlagSettings(): применяет настройки во время выполнения, как в await session.applyFlagSettings({ effortLevel: "high" }). Метод принимает ключи файла настроек, а не поля параметров, поэтому проверьте справочник applyFlagSettings() для схемы и для того, какие ключи вступают в силу во время сеанса.
• updateSettings(): записывает один разрешённый ключ в файл настроек. Справочник updateSettings() называет ключ, который принимает каждый источник, и минимальные версии.
  • Передайте "localSettings" для записи в файл локальных настроек проекта, как в await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Записанный ключ вступает в силу при следующем запросе сеанса и сохраняется для более поздних сеансов, которые загружают настройки local.
  • Передайте "userSettings" для записи effortLevel, единственного ключа, который принимает этот источник. Claude Code сохраняет его как уровень усилий по умолчанию для текущей модели сеанса, и усилия работающего сеанса не изменяются.

Пример ниже запускает двухходовой сеанс, изменяет конфигурацию между ходами и выводит модель, которая ответила на каждый ход. В TypeScript поток подсказок удерживает второе сообщение до тех пор, пока установщики не будут запущены, и второй ход выполняется на новой модели.

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

function userMessage(text: string): SDKUserMessage {
return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
yield userMessage("Reply with exactly: ready");
await secondTurnReady;
yield userMessage("Reply with exactly: done");
}

const session = query({
prompt: turnPrompts(),
options: {
model: "claude-sonnet-5",
},
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
if (message.type === "assistant") {
turnModel = message.message.model;
} else if (message.type === "result") {
completedTurns += 1;
if (completedTurns === 1) {
console.log(`First turn model: ${turnModel}`);
await session.setModel("claude-opus-5");
await session.setPermissionMode("acceptEdits");
startSecondTurn();
} else {
console.log(`Second turn model: ${turnModel}`);
break;
}
}
}

import asyncio

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

async def main():
options = ClaudeAgentOptions(model="claude-sonnet-5")

async with ClaudeSDKClient(options=options) as client:
await client.query("Reply with exactly: ready")
first_model = ""
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
first_model = message.model

await client.set_model("claude-opus-5")
await client.set_permission_mode("acceptEdits")

await client.query("Reply with exactly: done")
second_model = ""
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
second_model = message.model

print(f"First turn model: {first_model}")
print(f"Second turn model: {second_model}")

asyncio.run(main())

На Claude API программа выводит First turn model: claude-sonnet-5, затем Second turn model: claude-opus-5 после переключения.

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

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

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

Чтобы увидеть конфигурацию, составленную в рабочих агентов:

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