Definir variáveis de ambiente

A opção env define variáveis de ambiente para o processo Claude Code que executa sua sessão. Se seus valores substituem o ambiente herdado ou se mesclam com ele difere por idioma:

• TypeScript: env substitui o ambiente do subprocesso
• Python: o SDK mescla seus valores sobre o ambiente herdado, e seus valores substituem os herdados

Em TypeScript, espalhe process.env em env para manter variáveis herdadas como PATH, HOME e ANTHROPIC_API_KEY. Quando você deixa env indefinido, o subprocesso herda seu ambiente em ambos os idiomas.

O exemplo roteia o tráfego de API através de um gateway definindo 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"},
)

As variáveis que você passa também podem configurar o próprio Claude Code. Para as variáveis que o processo Claude Code lê, consulte Variáveis de ambiente. Para ajustar os tempos limite de API e detecção de travamento dessa forma, siga a seção Lidar com respostas de API lentas ou travadas na referência TypeScript ou na referência Python.

Definir o diretório de trabalho

Defina cwd para executar a sessão em um diretório específico. Quando você deixa cwd indefinido, a sessão é executada no diretório de trabalho do seu processo. Nenhum SDK tem um setter para cwd. Para executar em um diretório diferente, inicie outra sessão com esse cwd.

Claude Code lê o diretório de trabalho para determinar:

• Configurações e hooks do projeto: qual configuração e hooks do projeto são carregados
• Skills: onde as skills da sessão são descobertas
• Armazenamento de sessão: qual projeto uma sessão armazenada pertence

Para permitir que as ferramentas acessem arquivos fora do diretório de trabalho, adicione caminhos com additionalDirectories (TypeScript) ou add_dirs (Python). Para o escopo dessa concessão, consulte Diretórios adicionais concedem acesso a arquivos, não configuração.

Limitar turnos e gastos

Limite turnos e gastos com maxTurns / max_turns e maxBudgetUsd / max_budget_usd. Ambos os limites estão desativados quando indefinidos. Quando uma sessão atinge um limite, a execução termina com uma mensagem de resultado cujo subtipo nomeia o limite, error_max_turns ou error_max_budget_usd. O que acontece a seguir difere por modo de entrada:

• query() de disparo único: o SDK produz o resultado do limite e depois lança, portanto envolva o loop em um bloco try para continuar além do erro
• Entrada de streaming: a sessão permanece viva além de um resultado de limite, e a contagem de turnos máximos recomeça para cada mensagem enfileirada. O total do orçamento se acumula entre mensagens, e uma vez que o gasto atinge o limite, mensagens posteriores na mesma conversa terminam com o mesmo resultado de orçamento. Um /clear reinicia o orçamento

Os dois limites tratam 0 de forma diferente:

• maxTurns / max_turns: 0 executa a sessão sem um limite de turnos, o mesmo que deixar a opção indefinida
• maxBudgetUsd / max_budget_usd: a CLI rejeita 0 como um valor inválido na inicialização, e a sessão nunca é executada

Para mais informações sobre ambos os limites, incluindo gastos de subagentes, consulte Turnos e orçamento.

Alterar configuração no meio da sessão

Quando você inicia uma sessão com entrada de streaming, você pode alternar seu modelo e modo de permissão enquanto ela é executada. Onde você chama os setters difere por idioma:

• TypeScript: métodos no objeto que query() retorna
• Python: métodos em ClaudeSDKClient, já que query() retorna um iterador simples sem métodos de controle

Ambos os idiomas têm os mesmos setters:

• setModel() / set_model(): alterna o modelo. Chame-o sem modelo para alternar para o modelo padrão do Claude Code em vez do model que você passou nas opções.
• setPermissionMode() / set_permission_mode(): alterna o modo de permissão

TypeScript também tem applyFlagSettings() e updateSettings():

• applyFlagSettings(): aplica configurações em tempo de execução, como em await session.applyFlagSettings({ effortLevel: "high" }). O método aceita chaves de arquivo de configuração em vez de campos de opções, portanto verifique a referência applyFlagSettings() para o esquema e para quais chaves têm efeito no meio da sessão.
• updateSettings(): escreve uma chave na lista de permissões para um arquivo de configuração. A referência updateSettings() nomeia a chave que cada fonte aceita e o piso de versão.
  • Passe "localSettings" para escrever o arquivo de configurações locais do projeto, como em await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). A chave escrita tem efeito na próxima solicitação da sessão e persiste para sessões posteriores que carregam configurações local.
  • Passe "userSettings" para escrever effortLevel, a única chave que a fonte aceita. Claude Code a salva como o nível de esforço padrão para o modelo atual da sessão, e o esforço da sessão em execução não muda.

O exemplo abaixo executa uma sessão de dois turnos, altera a configuração entre os turnos e imprime o modelo que respondeu cada turno. Em TypeScript, o fluxo de prompt mantém a segunda mensagem até que os setters tenham sido executados, e o segundo turno é executado no novo modelo.

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())

Na API Claude, o programa imprime First turn model: claude-sonnet-5, depois Second turn model: claude-opus-5 após a mudança.

Configurar recursos específicos

A tabela abaixo mapeia cada opção para o recurso que ela configura. Para opções que esta página não cobre, consulte as referências TypeScript e Python. Se você conhece seu objetivo mas não qual opção o serve, comece em Escolher o recurso certo.

Próximas etapas

Para ver a configuração composta em agentes funcionais:

• Quickstart: construa e execute um primeiro agente de ponta a ponta
• Exemplos: encontre um projeto completo e executável ou uma receita guiada do Claude Cookbook que corresponda ao que você deseja construir
• Isolamento multi-tenant: isole as configurações e memória de cada tenant com settingSources / setting_sources, env e cwd