options que você passa ao iniciá-la. Esta página mostra como compor o objeto options e quais arquivos de configuração e variáveis de ambiente o controlam.
Para cada tipo de opção e padrão, consulte as referências Options (TypeScript) e ClaudeAgentOptions (Python).
Passar opções para uma sessão
Cada chamadaquery() aceita um objeto de opções: Options em TypeScript, ClaudeAgentOptions em Python. Cada campo é opcional, e uma sessão iniciada sem opções é executada com os padrões do SDK. O exemplo abaixo configura uma sessão somente leitura que resume os TODOs abertos de um projeto. Os pares são lidos como TypeScript / Python onde as grafias diferem:
model: escolhe o modeloallowedTools/allowed_tools: pré-aprova uma lista de ferramentas somente leituramaxTurns/max_turns: limita a contagem de turnoscwd: define o diretório de trabalho
cwd para um de seus próprios projetos e execute o exemplo. O resumo dos TODOs abertos desse projeto é impresso quando a mensagem de resultado chega.
allowedTools (TypeScript) ou allowed_tools (Python) pré-aprova as ferramentas listadas, portanto as chamadas para elas são executadas sem parar para aprovação. As ferramentas fora da lista permanecem disponíveis. Quando Claude chama uma ferramenta não listada, o modo de permissão decide se a chamada é executada. Para mais informações, consulte Regras de permissão e negação.
Carregar arquivos de configuração
Os arquivos de configuração fornecem configuração além do objeto de opções. Duas opções controlam como eles são carregados:settingSources/setting_sources: controla quais fontes do sistema de arquivos são carregadas: usuário, projeto e local. Os arquivos de configuração e arquivos CLAUDE.md chegam através dessas fontes.settings: carrega um caminho de arquivo de configuração ou uma string JSON embutida em qualquer idioma, e TypeScript também aceita um objeto de configuração. Qualquer forma que você passar substitui as configurações do sistema de arquivos do usuário, projeto e local; apenas as configurações de política gerenciada têm classificação mais alta. As referências documentam a ordem de precedência completa em Precedência de configurações para TypeScript e Precedência de configurações para Python.
[] para desabilitar as configurações do usuário, projeto e local. Para mais informações, consulte Usar recursos do Claude Code no SDK.
Escolher um modelo
A menos que a opçãomodel, suas configurações ou seu ambiente selecionem um modelo, uma nova sessão é iniciada no modelo padrão do Claude Code. Para a ordem dessas fontes, consulte Definir seu modelo. Defina model para fixar um modelo específico ou para escolher um menor para agentes mais rápidos e baratos. O valor aceita um alias de modelo ou um nome de modelo completo; os aliases e as versões que eles resolvem estão listados em Aliases de modelo.
Defina fallbackModel (TypeScript) ou fallback_model (Python) para nomear um modelo de backup. Quando o primário está sobrecarregado ou indisponível, a sessão muda para o backup. O primário é retentado no início de cada turno do usuário, portanto a sessão retorna a ele assim que a interrupção passa.
Em qualquer idioma, a opção aceita um único modelo ou uma lista separada por vírgulas de backups. Para a ordem e o limite da cadeia, consulte Cadeias de modelo de fallback. Em TypeScript, um fallback igual a model lança um erro na inicialização.
Os exemplos abaixo mostram uma lista de fallback em TypeScript e um único fallback em Python:
Os parâmetros de solicitação da API de Mensagens
temperature, top_p e max_tokens não têm campos no objeto de opções em nenhum idioma. Defina o nível de esforço ou um limite de gastos em vez disso, ou chame a API de Mensagens quando você precisar desses parâmetros diretamente.Definir variáveis de ambiente
A opçãoenv 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:
envsubstitui o ambiente do subprocesso - Python: o SDK mescla seus valores sobre o ambiente herdado, e seus valores substituem os herdados
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.
Definir o diretório de trabalho
Definacwd 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
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 commaxTurns / 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
/clearreinicia o orçamento
0 de forma diferente:
maxTurns/max_turns:0executa a sessão sem um limite de turnos, o mesmo que deixar a opção indefinidamaxBudgetUsd/max_budget_usd: a CLI rejeita0como um valor inválido na inicialização, e a sessão nunca é executada
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á quequery()retorna um iterador simples sem métodos de controle
setModel()/set_model(): alterna o modelo. Chame-o sem modelo para alternar para o modelo padrão do Claude Code em vez domodelque você passou nas opções.setPermissionMode()/set_permission_mode(): alterna o modo de permissão
applyFlagSettings() e updateSettings():
applyFlagSettings(): aplica configurações em tempo de execução, como emawait 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ênciaapplyFlagSettings()para o esquema e para quais chaves têm efeito no meio da sessão.updateSettings(): escreve um conjunto de chaves na lista de permissões para o arquivo de configuração local do projeto, como emawait session.updateSettings("localSettings", { outputStyle: "Explanatory" }). As chaves escritas têm efeito na próxima solicitação da sessão e persistem para sessões posteriores que carregam configuraçõeslocal. A linha do método na tabela de métodos nomeia as chaves na lista de permissões e o piso de versão.
First turn model: claude-sonnet-5, depois Second turn model: claude-opus-5 após a mudança.
Cada modelo tem seu próprio cache de prompt, portanto após uma mudança no meio da sessão a próxima solicitação recomputa a conversa completa sem cache nas taxas do novo modelo. Para mais informações, consulte Alternando modelos.
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,envecwd