Variables de entorno

Referencia para variables de entorno que controlan el comportamiento de Claude Code.

Las variables de entorno pueden controlar el comportamiento de Claude Code, como la selección de modelo, autenticación, enrutamiento de solicitudes y alternadores de características. Muchos de los mismos comportamientos también se pueden configurar a través de un campo de archivo de configuración, una bandera CLI o un comando en sesión como /model.

Esta página cubre cómo:

• Establecer variables de entorno en su shell o en un archivo de configuración
• Verificar qué valor se aplica cuando un comportamiento se puede establecer de más de una manera
• Buscar las variables que Claude Code lee
• Ver qué características dejan de funcionar cuando una variable desactiva la obtención de marcas de características

Establecer variables de entorno

Una variable que establezca en su shell dura durante esa sesión de terminal, mientras que una variable en un archivo de configuración se aplica cada vez que se ejecuta claude.

En su shell

Establezca la variable antes de lanzar claude:

export API_TIMEOUT_MS="1200000"
claude

$env:API_TIMEOUT_MS = "1200000"
claude

set API_TIMEOUT_MS=1200000
claude

La línea de asignación no imprime nada en caso de éxito. Para confirmar que la variable está establecida, imprímala en el mismo shell:

echo $API_TIMEOUT_MS

echo $env:API_TIMEOUT_MS

echo %API_TIMEOUT_MS%

En archivos de configuración

Agregue variables bajo la clave env en un archivo settings.json, creando el archivo si no existe. Claude Code las lee directamente del archivo, por lo que surten efecto sin importar cómo se haya lanzado claude. Una sesión en ejecución aplica valores nuevos y modificados a su entorno cuando guarda el archivo, pero una característica que lee sus variables una sola vez al inicio, como monitoreo de OpenTelemetry, mantiene sus valores de inicio hasta que relance. Eliminar una variable del archivo no la desestablece en una sesión en ejecución; la eliminación surte efecto la próxima vez que lance claude.

{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

El archivo que elija controla a quién se aplican las variables:

Consulte Archivos de configuración para saber dónde vive cada archivo y Precedencia de configuración para saber cómo se combinan cuando más de uno establece la misma variable.

Precedencia

Algunos comportamientos tienen tanto una variable de entorno como una clave de configuración dedicada, y cuál lee primero Claude Code difiere según la clave. Para ANTHROPIC_MODEL y CLAUDE_CODE_AUTO_CONNECT_IDE, Claude Code lee primero la variable y utiliza la configuración model o autoConnectIde solo cuando la variable no está establecida. Para el par que está configurando, verifique la fila de la variable a continuación y la entrada de la clave en la referencia de configuración.

Cuando la misma variable se establece tanto en su shell como en un bloque env de archivo de configuración, se aplica el valor del archivo de configuración en la mayoría de las sesiones. Claude Code escribe cada entrada env en el entorno del proceso, reemplazando el valor heredado del shell. Cómo los valores env interactúan con su shell cubre las sesiones que mantienen el valor heredado en su lugar, y la configuración env indica cuándo se aplica. Algunas variables tienen casos especiales; la configuración env enumera las excepciones.

En un archivo de configuración puede establecer una variable pero no puede eliminar una. Para anular una variable que no puede desestablecer, como una CLAUDE_CODE_USE_VERTEX obsoleta exportada por un perfil de shell que no controla, establézcala en una cadena vacía en el bloque env: "CLAUDE_CODE_USE_VERTEX": "". Claude Code trata el valor vacío como no establecido para la selección de proveedor. Los subprocesos aún heredan el valor vacío.

Entre archivos de configuración, los valores env siguen la precedencia de configuración, por lo que una entrada de configuración administrada anula la misma variable en la configuración de usuario o proyecto. La configuración de proyecto y local no puede establecer algunas variables, como CLAUDE_CONFIG_DIR y las variables del exportador de OpenTelemetry. Variables que Claude Code ignora en env las enumera, junto con los valores de desactivación de OpenTelemetry que aún se aplican.

Cómo una variable de entorno interactúa con banderas CLI y comandos en sesión varía según la característica: --model y /model anulan ANTHROPIC_MODEL, mientras que CLAUDE_CODE_EFFORT_LEVEL anula --effort y /effort. Cuando una variable interactúa con otra fuente de configuración, su fila en la lista Variables indica la precedencia o vincula a la página que la documenta.

Claude Code lee las variables de entorno del shell al iniciar, por lo que los cambios en ellas surten efecto la próxima vez que inicia claude. Las variables establecidas bajo la clave env en archivos de configuración se reaplicarán a una sesión en ejecución cuando el archivo cambie, con la excepción de solo inicio descrita en En archivos de configuración.

Variables

Las variables numéricas, como los tiempos de espera, los presupuestos de tokens y los recuentos de reintentos, aceptan notación científica y escrituras con separadores de dígitos además de dígitos simples, excepto cuando la fila de una variable indica que solo acepta dígitos simples. Por ejemplo, Claude Code lee 2e3 como 2000 y 64_000 como 64000. Antes de la v2.1.211, estas escrituras podían establecer silenciosamente un valor mucho menor, como 1e6, que establecía un tiempo de espera de 1.

También se admiten las variables estándar de exportadores de OpenTelemetry (OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS, OTEL_METRIC_EXPORT_INTERVAL, OTEL_RESOURCE_ATTRIBUTES y las variantes específicas de cada señal). Consulta Monitoreo para conocer los detalles de configuración.

Establece CLAUDE_CODE_ENABLE_TELEMETRY y las variables de OpenTelemetry que activan la exportación, eligen su destino o capturan contenido en tu shell, en la configuración de usuario o en la configuración administrada. Claude Code las ignora en la configuración de proyecto y local, salvo los valores de desactivación que describe esa sección. OTEL_RESOURCE_ATTRIBUTES y las variables de intervalo, tiempo de espera y compresión de la exportación, como OTEL_METRIC_EXPORT_INTERVAL, siguen aplicándose desde la configuración de proyecto y local.

Qué elimina la depuración del entorno de los subprocesos

Cuando estableces CLAUDE_CODE_SUBPROCESS_ENV_SCRUB en 1, Claude Code elimina las credenciales de los entornos de los subprocesos que inicia, como los comandos de Bash, los hooks y los servidores MCP stdio. Esto reduce lo que un ataque de inyección de prompts puede leer mediante la expansión del shell. El proceso de Claude Code conserva las credenciales para sus propias llamadas a la API.

La depuración reconoce una credencial por el nombre de su variable o por la forma de su valor, así que úsala como una capa más junto con reglas de permisos acotadas, en lugar de como el único control.

La tabla muestra lo que hace la depuración con algunas variables de ejemplo:

Como la depuración deja intacto GITHUB_TOKEN, asigna a un trabajo de GitHub Actions los permissions más restringidos que necesite. Para eliminar un token de GitHub de los comandos de Bash que se ejecutan en el sandbox, agrega una entrada deny en sandbox.credentials.

No establezcas la depuración si un subproceso necesita alguna de las variables eliminadas.

En Linux, la depuración también ejecuta los subprocesos de Bash en un espacio de nombres PID aislado para que no puedan leer los entornos de los procesos del host a través de /proc. Como efecto secundario, ps, pgrep y kill no pueden ver los procesos del host ni enviarles señales.

Funciones que requieren la obtención de feature flags

Claude Code activa algunas funciones mediante feature flags que obtiene de Anthropic. Claude Code omite esa obtención en estas sesiones:

• Una sesión en la que estableces DISABLE_GROWTHBOOK, DISABLE_TELEMETRY, DO_NOT_TRACK o CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC; la fila de cada variable en la tabla de variables indica qué valores desactivan la obtención
• Una sesión en un proveedor externo, como Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform o Microsoft Foundry, a menos que una plataforma anfitriona que integre Claude Code establezca CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
• Una sesión del gateway de aplicaciones de Claude

Con la obtención desactivada, no puedes:

• Ejecutar /auto-mode-setup para redactar entradas de autoMode.environment
• Usar Remote Control con CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC o DISABLE_GROWTHBOOK establecidas. Para DISABLE_TELEMETRY y DO_NOT_TRACK, consulta los requisitos de Remote Control
• Enviar mensajes a sesiones fuera de esta máquina cuando Remote Control no está disponible. El envío de mensajes entre sesiones en esta máquina funciona con la obtención desactivada
• Ejecutar claude import o el comando /import
• Ejecutar /skill-doctor ni abrir su informe en la pestaña Stats de /plugin
• Sincronizar los skills y plugins habilitados para tu cuenta de claude.ai en tus sesiones de terminal
• Usar la herramienta advisor
• Leer o responder comentarios en un artefacto
• Hacer que Claude lea el artefacto público de otra organización
• Hacer que Claude Code sondee servidores de conectores de claude.ai o servidores stdio para la revisión 2026-07-28 del protocolo MCP, a menos que establezcas MCP_PROTOCOL_NEGOTIATION=auto
• Obtener la herramienta PowerShell de forma predeterminada para cuentas de claude.ai y Console en Windows con Git Bash instalado; Claude Code enruta los comandos de shell a través de Git Bash a menos que establezcas CLAUDE_CODE_USE_POWERSHELL_TOOL=1. En Windows sin Git Bash, la herramienta permanece activada
• Obtener comentarios redactados por Claude, que Claude Code activa mediante un flag obtenido
• Hacer que Claude trate los pegados grandes como texto pegado en lugar de texto escrito; el contenido detrás de un marcador de posición [Pasted text #N] llega a Claude sin marcar
• Hacer que Claude Code excluya las herramientas MCP cuyo esquema de entrada rechazaría la API; envía el esquema de todos modos, y una solicitud que lo incluya falla con un error 400 que nombra la herramienta por su posición

Primera sesión después de una instalación o actualización

En tu primera sesión después de instalar Claude Code, o de actualizar a una versión que añade una función, puede faltar una función controlada por flags. Esa sesión también puede iniciarse en un modo de permisos distinto al de tus sesiones posteriores. Cuando Claude Code obtiene los flags durante esa sesión, los guarda en la máquina, de modo que tu siguiente sesión en esa máquina tiene la función y el modo de permisos inicial habitual.

Después de una instalación nueva, en una sesión no interactiva como claude -p, el Agent SDK o la extensión de VS Code, Claude Code puede obtener los flags antes de elegir el modo de permisos inicial, pero no siempre los espera.

En configuraciones como estas, las sesiones posteriores a la primera también se inician sin flags recién obtenidos:

• Un entorno limpio en cada ejecución: si cada ejecución se inicia en un contenedor de CI, o en cualquier otro entorno sin los flags que guardó una sesión anterior, cada ejecución es una primera sesión
• Un token de gateway sin clave de API: si te autenticas con ANTHROPIC_AUTH_TOKEN y sin clave de API, y ANTHROPIC_BASE_URL apunta a un host distinto al de Anthropic, como un gateway de LLM, Claude Code no tiene ninguna credencial con la que obtener los flags

Para elegir el modo de permisos en el que se inician las sesiones en estas configuraciones, consulta Iniciar en un modo de permisos diferente.

Véase también

• Configuración: todas las configuraciones de settings.json, incluida la clave env
• Referencia de CLI: banderas de tiempo de lanzamiento
• Configuración de red: configuración de proxy y TLS
• Monitoreo: configuración de OpenTelemetry