Skip to main content
Una sesión del Agent SDK lee la configuración desde archivos de configuración, variables de entorno y el objeto options que pasas cuando la inicias. Esta página muestra cómo componer el objeto options y qué archivos de configuración y variables de entorno lo controlan. Para cada tipo de opción y valor predeterminado, consulta las referencias Options (TypeScript) y ClaudeAgentOptions (Python).

Pasar opciones a una sesión

Cada llamada a query() acepta un objeto de opciones: Options en TypeScript, ClaudeAgentOptions en Python. Cada campo es opcional, y una sesión iniciada sin opciones se ejecuta con los valores predeterminados del SDK. El ejemplo a continuación configura una sesión de solo lectura que resume los TODOs abiertos de un proyecto. Los pares se leen como TypeScript / Python donde los nombres difieren:
  • model: elige el modelo
  • allowedTools / allowed_tools: aprueba previamente una lista de herramientas de solo lectura
  • maxTurns / max_turns: limita el número de turnos
  • cwd: establece el directorio de trabajo
Apunta cwd a uno de tus propios proyectos y ejecuta el ejemplo. El resumen de los TODOs abiertos de ese proyecto se imprime cuando llega el mensaje de resultado. allowedTools (TypeScript) o allowed_tools (Python) aprueba previamente las herramientas listadas, por lo que las llamadas a ellas se ejecutan sin detenerse para solicitar aprobación. Las herramientas fuera de la lista siguen disponibles. Cuando Claude llama a una herramienta no listada, el modo de permisos decide si la llamada se ejecuta. Para más información, consulta Reglas de permitir y denegar.

Cargar archivos de configuración

Los archivos de configuración proporcionan configuración más allá del objeto de opciones. Dos opciones controlan cómo se cargan:
  • settingSources / setting_sources: controla qué fuentes del sistema de archivos se cargan: usuario, proyecto y local. Los archivos de configuración y los archivos CLAUDE.md llegan a través de estas fuentes.
  • settings: carga una ruta de archivo de configuración o una cadena JSON en línea en cualquier idioma, y TypeScript también acepta un objeto de configuración. Sea cual sea la forma que pases, anula la configuración del sistema de archivos de usuario, proyecto y local; solo la configuración de política administrada tiene un rango más alto. Las referencias documentan el orden de precedencia completo bajo Precedencia de configuración para TypeScript y Precedencia de configuración para Python.
Pasa [] para desactivar la configuración de usuario, proyecto y local. Para más información, consulta Usar características de Claude Code en el SDK.

Elige un modelo

A menos que la opción model, tu configuración o tu entorno seleccione un modelo, una nueva sesión comienza en el modelo predeterminado de Claude Code. Para el orden de esas fuentes, consulta Establecer tu modelo. Establece model para fijar un modelo específico, o para elegir uno más pequeño para agentes más rápidos y económicos. El valor toma un alias de modelo o un nombre de modelo completo; los alias y las versiones a las que se resuelven se enumeran bajo Alias de modelos. Establece fallbackModel (TypeScript) o fallback_model (Python) para nombrar un modelo de respaldo. Cuando el principal está sobrecargado o no disponible, la sesión cambia al respaldo. El principal se reintenta al inicio de cada turno del usuario, por lo que la sesión vuelve a él una vez que la interrupción pasa. En cualquier idioma, la opción acepta un único modelo o una lista separada por comas de respaldos. Para el orden y el límite de cadena, consulta Cadenas de modelo de respaldo. En TypeScript, un respaldo igual a model lanza un error al inicio. Los ejemplos a continuación muestran una lista de respaldo en TypeScript y un único respaldo en Python:
Los parámetros de solicitud de la API de Mensajes temperature, top_p y max_tokens no tienen campos en el objeto de opciones en ninguno de los idiomas. Establece el nivel de esfuerzo o un límite de gasto en su lugar, o llama a la API de Mensajes cuando necesites esos parámetros directamente.

Establecer variables de entorno

La opción env establece variables de entorno para el proceso de Claude Code que ejecuta tu sesión. Si tus valores reemplazan el entorno heredado o se fusionan con él difiere según el idioma:
  • TypeScript: env reemplaza el entorno del subproceso
  • Python: el SDK fusiona tus valores sobre el entorno heredado, y tus valores anulan los heredados
En TypeScript, expande process.env en env para mantener variables heredadas como PATH, HOME y ANTHROPIC_API_KEY. Cuando dejas env sin establecer, el subproceso hereda tu entorno en ambos idiomas. El ejemplo enruta el tráfico de API a través de una puerta de enlace estableciendo ANTHROPIC_BASE_URL.
Las variables que pasas también pueden configurar Claude Code en sí. Para las variables que el proceso de Claude Code lee, consulta Variables de entorno. Para ajustar los tiempos de espera de API y la detección de estancamiento de esta manera, sigue la sección Manejar respuestas de API lentas o estancadas en la referencia de TypeScript o la referencia de Python.

Establecer el directorio de trabajo

Establece cwd para ejecutar la sesión en un directorio específico. Cuando dejas cwd sin establecer, la sesión se ejecuta en el directorio de trabajo de tu proceso. Ninguno de los SDK tiene un setter para cwd. Para ejecutar en un directorio diferente, inicia otra sesión con ese cwd. Claude Code lee el directorio de trabajo para determinar: Para permitir que las herramientas accedan a archivos fuera del directorio de trabajo, agrega rutas con additionalDirectories (TypeScript) o add_dirs (Python). Para el alcance de esa concesión, consulta Los directorios adicionales otorgan acceso a archivos, no configuración.

Limitar turnos y gasto

Limita turnos y gasto con maxTurns / max_turns y maxBudgetUsd / max_budget_usd. Ambos límites están desactivados cuando no se establecen. Cuando una sesión alcanza un límite, la ejecución termina con un mensaje de resultado cuyo subtipo nombra el límite, error_max_turns o error_max_budget_usd. Lo que sucede después difiere según el modo de entrada:
  • query() de un solo disparo: el SDK produce el resultado del límite y luego lanza, así que envuelve el bucle en un bloque try para continuar más allá del error
  • Entrada de transmisión: la sesión permanece activa después de un resultado de límite, y el conteo de turnos máximos comienza de nuevo para cada mensaje en cola. El total del presupuesto se acumula entre mensajes, y una vez que el gasto alcanza el límite, los mensajes posteriores en la misma conversación terminan con el mismo resultado de presupuesto. Un /clear comienza el presupuesto de nuevo
Los dos límites tratan 0 de manera diferente:
  • maxTurns / max_turns: 0 ejecuta la sesión sin un límite de turnos, lo mismo que dejar la opción sin establecer
  • maxBudgetUsd / max_budget_usd: la CLI rechaza 0 como una cantidad inválida al inicio, y la sesión nunca se ejecuta
Para más información sobre ambos límites, incluido el gasto de subagentes, consulta Turnos y presupuesto.

Cambiar configuración durante la sesión

Cuando inicias una sesión con entrada de transmisión, puedes cambiar su modelo y modo de permisos mientras se ejecuta. Dónde llamas a los setters difiere según el idioma:
  • TypeScript: métodos en el objeto que query() devuelve
  • Python: métodos en ClaudeSDKClient, ya que query() devuelve un iterador simple sin métodos de control
Ambos idiomas tienen los mismos setters:
  • setModel() / set_model(): cambia el modelo. Llámalo sin modelo para cambiar al modelo predeterminado de Claude Code en lugar del model que pasaste en opciones.
  • setPermissionMode() / set_permission_mode(): cambia el modo de permisos
TypeScript también tiene applyFlagSettings() y updateSettings():
  • applyFlagSettings(): aplica configuración en tiempo de ejecución, como en await session.applyFlagSettings({ effortLevel: "high" }). El método toma claves de archivo de configuración en lugar de campos de opciones, así que consulta la referencia de applyFlagSettings() para el esquema y para qué claves tienen efecto durante la sesión.
  • updateSettings(): escribe un conjunto permitido de claves en el archivo de configuración local del proyecto, como en await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Las claves escritas tienen efecto en la siguiente solicitud de la sesión y persisten para sesiones posteriores que cargan configuración local. La fila del método en la tabla de métodos nombra las claves permitidas y el piso de versión.
El ejemplo a continuación ejecuta una sesión de dos turnos, cambia la configuración entre los turnos e imprime el modelo que respondió cada turno. En TypeScript, la transmisión de solicitud mantiene el segundo mensaje hasta que los setters se hayan ejecutado, y el segundo turno se ejecuta en el nuevo modelo.
En la API de Claude, el programa imprime First turn model: claude-sonnet-5, luego Second turn model: claude-opus-5 después del cambio.
Cada modelo tiene su propio caché de solicitud, por lo que después de un cambio durante la sesión, la siguiente solicitud recomputa la conversación completa sin caché a las tasas del nuevo modelo. Para más información, consulta Cambiar modelos.

Configurar características específicas

La tabla a continuación asigna cada opción a la característica que configura. Para opciones que esta página no cubre, consulta las referencias de TypeScript y Python. Si conoces tu objetivo pero no qué opción lo sirve, comienza desde Elige la característica correcta.

Próximos pasos

Para ver la configuración compuesta en agentes funcionales:
  • Inicio rápido: construye y ejecuta un primer agente de principio a fin
  • Ejemplos: encuentra un proyecto completo y ejecutable o una receta guiada de Claude Cookbook que coincida con lo que quieres construir
  • Aislamiento multiinquilino: aísla la configuración y la memoria de cada inquilino con settingSources / setting_sources, env y cwd