options che passi quando la avvii. Questa pagina mostra come comporre l’oggetto options e quali file di impostazioni e variabili d’ambiente lo controllano.
Per ogni tipo di opzione e valore predefinito, consulta i riferimenti Options (TypeScript) e ClaudeAgentOptions (Python).
Passa le opzioni a una sessione
Ogni chiamataquery() accetta un oggetto options: Options in TypeScript, ClaudeAgentOptions in Python. Ogni campo è facoltativo e una sessione avviata senza opzioni viene eseguita con i valori predefiniti dell’SDK. L’esempio seguente configura una sessione di sola lettura che riassume i TODO aperti di un progetto. Le coppie si leggono come TypeScript / Python dove gli spelling differiscono:
model: sceglie il modelloallowedTools/allowed_tools: pre-approva un elenco di strumenti di sola letturamaxTurns/max_turns: limita il numero di turnicwd: imposta la directory di lavoro
cwd a uno dei vostri progetti e eseguite l’esempio. Il riassunto dei TODO aperti di quel progetto viene stampato quando arriva il messaggio di risultato.
allowedTools (TypeScript) o allowed_tools (Python) pre-approva gli strumenti elencati, quindi le chiamate a essi vengono eseguite senza fermarsi per l’approvazione. Gli strumenti al di fuori dell’elenco rimangono disponibili. Quando Claude chiama uno strumento non elencato, la modalità di autorizzazione decide se la chiamata viene eseguita. Per ulteriori informazioni, consultate Allow and deny rules.
Carica i file di impostazioni
I file di impostazioni forniscono configurazioni oltre all’oggetto options. Due opzioni controllano come vengono caricati:settingSources/setting_sources: controlla quali fonti del filesystem caricano: user, project e local. I file di impostazioni e i file CLAUDE.md arrivano attraverso queste fonti.settings: carica un percorso di file di impostazioni o una stringa JSON inline in entrambi i linguaggi, e TypeScript accetta anche un oggetto settings. Qualunque forma passiate sostituisce le impostazioni del filesystem user, project e local; solo le impostazioni di policy gestite hanno una priorità più alta. I riferimenti documentano l’ordine di precedenza completo in Settings precedence per TypeScript e Settings precedence per Python.
[] per disabilitare le impostazioni user, project e local. Per ulteriori informazioni, consultate Use Claude Code features in the SDK.
Scegli un modello
A meno che l’opzionemodel, le vostre impostazioni o il vostro ambiente non selezionino un modello, una nuova sessione si avvia sul modello predefinito di Claude Code. Per l’ordine di queste fonti, consultate Setting your model. Impostate model per fissare un modello specifico, o per sceglierne uno più piccolo per agenti più veloci e economici. Il valore accetta un alias di modello o un nome di modello completo; gli alias e le versioni a cui si risolvono sono elencati in Model aliases.
Impostate fallbackModel (TypeScript) o fallback_model (Python) per nominare un modello di backup. Quando il primario è sovraccarico o non disponibile, la sessione passa al backup. Il primario viene ritentato all’inizio di ogni turno dell’utente, quindi la sessione ritorna ad esso una volta che l’interruzione passa.
In entrambi i linguaggi, l’opzione accetta un singolo modello o un elenco separato da virgole di backup. Per l’ordine e il limite della catena, consultate Fallback model chains. In TypeScript, un fallback uguale a model genera un errore all’avvio.
Gli esempi seguenti mostrano un elenco di fallback in TypeScript e un singolo fallback in Python:
I parametri della richiesta dell’API Messages
temperature, top_p e max_tokens non hanno campi sull’oggetto options in nessuno dei due linguaggi. Impostate il livello di sforzo o un limite di spesa invece, oppure chiamate l’API Messages quando avete bisogno di quei parametri direttamente.Imposta le variabili d’ambiente
L’opzioneenv imposta le variabili d’ambiente per il processo Claude Code che esegue la vostra sessione. Se i vostri valori sostituiscono l’ambiente ereditato o si uniscono ad esso differisce per linguaggio:
- TypeScript:
envsostituisce l’ambiente del subprocess - Python: l’SDK unisce i vostri valori all’ambiente ereditato, e i vostri valori sostituiscono quelli ereditati
process.env in env per mantenere le variabili ereditate come PATH, HOME e ANTHROPIC_API_KEY. Quando lasciate env non impostato, il subprocess eredita il vostro ambiente in entrambi i linguaggi.
L’esempio instrada il traffico API attraverso un gateway impostando ANTHROPIC_BASE_URL.
Imposta la directory di lavoro
Impostatecwd per eseguire la sessione in una directory specifica. Quando lasciate cwd non impostato, la sessione viene eseguita nella directory di lavoro del vostro processo. Nessuno dei due SDK ha un setter per cwd. Per eseguire in una directory diversa, avviate un’altra sessione con quel cwd.
Claude Code legge la directory di lavoro per determinare:
- Project settings and hooks: quale impostazioni e hook del progetto caricano
- Skills: dove le skill della sessione vengono scoperte
- Session storage: quale progetto una sessione memorizzata appartiene a
additionalDirectories (TypeScript) o add_dirs (Python). Per l’ambito di quella concessione, consultate Additional directories grant file access, not configuration.
Limita i turni e la spesa
Limitate i turni e la spesa conmaxTurns / max_turns e maxBudgetUsd / max_budget_usd. Entrambi i limiti sono disattivati quando non impostati. Quando una sessione raggiunge un limite, l’esecuzione termina con un messaggio di risultato il cui sottotipo nomina il limite, error_max_turns o error_max_budget_usd. Quello che succede dopo differisce per modalità di input:
- Single-shot
query(): l’SDK produce il risultato del limite e poi genera un’eccezione, quindi avvolgete il ciclo in un blocco try per continuare oltre l’errore - Streaming input: la sessione rimane attiva oltre un risultato di limite, e il conteggio dei turni massimi ricomincia per ogni messaggio in coda. Il totale del budget si accumula tra i messaggi, e una volta che la spesa raggiunge il limite, i messaggi successivi nella stessa conversazione terminano con lo stesso risultato di budget. Un
/clearricomincia il budget
0 diversamente:
maxTurns/max_turns:0esegue la sessione senza un limite di turni, lo stesso che lasciare l’opzione non impostatamaxBudgetUsd/max_budget_usd: la CLI rifiuta0come importo non valido all’avvio, e la sessione non viene mai eseguita
Cambia la configurazione durante la sessione
Quando avviate una sessione con streaming input, potete cambiare il suo modello e la modalità di autorizzazione mentre è in esecuzione. Dove chiamate i setter differisce per linguaggio:- TypeScript: metodi sull’oggetto che
query()restituisce - Python: metodi su
ClaudeSDKClient, poichéquery()restituisce un iteratore semplice senza metodi di controllo
setModel()/set_model(): cambia il modello. Chiamatelo senza modello per passare al modello predefinito di Claude Code piuttosto che almodelche avete passato nelle opzioni.setPermissionMode()/set_permission_mode(): cambia la modalità di autorizzazione
applyFlagSettings() e updateSettings():
applyFlagSettings(): applica le impostazioni in fase di esecuzione, come inawait session.applyFlagSettings({ effortLevel: "high" }). Il metodo accetta chiavi di file di impostazioni piuttosto che campi di opzioni, quindi controllate il riferimentoapplyFlagSettings()per lo schema e per quali chiavi hanno effetto durante la sessione.updateSettings(): scrive un insieme di chiavi consentite nel file di impostazioni locali del progetto, come inawait session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Le chiavi scritte hanno effetto sulla richiesta successiva della sessione e persistono per le sessioni successive che caricano le impostazionilocal. La riga del metodo nella tabella dei metodi nomina le chiavi consentite e il floor della versione.
First turn model: claude-sonnet-5, poi Second turn model: claude-opus-5 dopo il cambio.
Ogni modello ha la sua propria cache del prompt, quindi dopo un cambio durante la sessione la richiesta successiva ricalcola la conversazione completa non memorizzata nella cache alle tariffe del nuovo modello. Per ulteriori informazioni, consultate Switching models.
Configura funzionalità specifiche
La tabella seguente mappa ogni opzione alla funzionalità che configura. Per le opzioni che questa pagina non copre, consultate i riferimenti TypeScript e Python. Se conoscete il vostro obiettivo ma non quale opzione lo serve, iniziate da Choose the right feature.Passaggi successivi
Per vedere la configurazione composta in agenti funzionanti:- Quickstart: costruisci ed esegui un primo agente da capo a fondo
- Examples: trova un progetto completo e eseguibile o una ricetta guidata di Claude Cookbook che corrisponde a quello che vuoi costruire
- Multi-tenant isolation: isola le impostazioni e la memoria di ogni tenant con
settingSources/setting_sources,envecwd