Claude Code Variables de entorno

Las variables de entorno son una forma importante de controlar el comportamiento de Claude Code, permitiendo ajustar varias configuraciones de manera flexible sin necesidad de editar archivos de configuración. Este capítulo detalla todas las variables de entorno compatibles con Claude Code, sus usos, métodos de configuración y casos de uso comunes.


Descripción general de las variables de entorno

Claude Code utiliza variables de entorno para controlar su comportamiento. Estas variables se pueden configurar de las siguientes maneras:

  • directamente en el shellexport
  • En~/.claude/settings.jsondeenven el campo de configuración
  • a nivel de proyecto.claude/settings.jsonen la configuración
  • mediante la interfaz de configuración del complemento del IDE

La prioridad de las variables de entorno es de mayor a menor: línea de comandos > settings.json a nivel de proyecto > settings.json a nivel de usuario > variables de entorno del shell. Las variables configuradas en settings.json se pasan automáticamente al proceso de Claude.


Variables de autenticación

Nombre de la variable Descripción Valor
ANTHROPIC_API_KEY Clave de la API de Claude (obtenida de claude.ai) Cadena de clave de API
ANTHROPIC_BASE_URL Dirección de destino de las solicitudes a la API (para proxy o puntos finales personalizados) Dirección URL
ANTHROPIC_AUTH_TOKEN Token de autenticación (para escenarios como el complemento de VS Code) Cadena de token

Ejemplo de configuración

Ejemplo

# Configurar en el shell
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

Ejemplo

// Configurar en settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
    "ANTHROPIC_BASE_URL": "https://custom-proxy.com/v1"
  }
}

Variables de configuración del modelo

Nombre de la variable Descripción Valor
ANTHROPIC_MODEL Modelo utilizado por defecto claude-opus-4-5、claude-sonnet-4-5、claude-haiku-3-5esperar
ANTHROPIC_SMALL_FAST_MODEL Modelo utilizado en el modo de respuesta rápida (para tareas sencillas) Nombre del modelo
CLAUDE_CODE_SUBAGENT_MODEL Configurar de manera uniforme el modelo utilizado por todos los subagentes Nombre del modelo
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS Deshabilitar funciones experimentales al usar el formato Anthropic Messages de Bedrock o Vertex 1

Casos de uso

Los subagentes heredan por defecto el modelo de la conversación principal. MedianteCLAUDE_CODE_SUBAGENT_MODELse puede configurar de manera uniforme, asignando tareas sencillas a Haiku y análisis complejos a Sonnet, optimizando así los costos:

Ejemplo

# La conversación principal usa Opus para razonamiento complejo, los subagentes usan Sonnet de manera uniforme
export ANTHROPIC_MODEL="claude-opus-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5"

Variables de herramientas y comandos

Nombre de la variable Descripción Valor
CLAUDE_CODE_DISABLE_SLASH_COMMANDS Deshabilitar todos los comandos de barra 1
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS Deshabilitar los mensajes de sistema integrados relacionados con Git (prioridad mayor que en settings.jsonincludeGitInstructions) 1
CLAUDE_CODE_USE_POWERSHELL_TOOL Habilitar la herramienta PowerShell en Windows (requiere combinarse condefaultShell: "powershell"configuración) 1
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL Omitir la instalación automática de extensiones del IDE (reemplazaautoInstallIdeExtensionconfiguración) 1
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Deshabilitar la función de tareas en segundo plano 1

Variables de permisos y seguridad

Nombre de la variable Descripción Valor
CLAUDE_CODE_PERMISSION_MODE Configurar el modo de permiso predeterminado (consulte el capítulo de subagentes) default、acceptEdits、dontAsk、bypassPermissions、plan
CLAUDE_CODE_ALLOWED_TOOLS Lista blanca de herramientas permitidas para Claude (separadas por comas) Lista de herramientas
CLAUDE_CODE_DISALLOWED_TOOLS Lista negra de herramientas prohibidas para Claude Lista de herramientas

Explicación detallada de los modos de permiso

  • default: Aviso de permisos normal, pregunta antes de cada operación
  • acceptEdits: Aceptar automáticamente la edición de archivos, sin confirmación
  • dontAsk: Rechazar automáticamente operaciones no autorizadas, sin interrumpir la ejecución
  • bypassPermissions: Omitir todas las comprobaciones de permisos (solo en entornos totalmente confiables)
  • plan: Modo de planificación de solo lectura, no ejecuta operaciones de escritura

Ejemplo

# Usar modo de solo lectura en entornos CI
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

Variables de registro y depuración

Nombre de la variable Descripción Valor
CLAUDE_CODE_DEBUG Habilitar salida de depuración 1
CLAUDE_CODE_ENABLE_TELEMETRY Habilitar recopilación de datos de telemetría 1
OTEL_METRICS_EXPORTER Exportador de métricas de OpenTelemetry otlpesperar

Variables de sesión e historial

Nombre de la variable Descripción Valor
CLAUDE_CODE_DISABLE_HISTORY Deshabilitar el guardado del historial de conversación 1
CLAUDE_CODE_SESSION_TIMEOUT Tiempo de espera de sesión (segundos) Número
CLAUDE_CODE_MAX_SESSIONS Número máximo de sesiones guardadas Número

Variables relacionadas con MCP

Cuando Claude Code ejecuta herramientas MCP, se establecen las siguientes variables de entorno:

Nombre de la variable Descripción Valor
CLAUDE_CODE_MCP_SERVER_NAME Nombre del servidor MCP Cadena
CLAUDE_CODE_MCP_TOOL_NAME Nombre de la herramienta MCP que se está invocando Cadena
CLAUDE_CODE_MCP_TOOL_ARGS Parámetros pasados a la herramienta MCP Cadena JSON

Variables relacionadas con flujos de trabajo

Nombre de la variable Descripción Valor
CLAUDE_CODE_WORKTREE_CLEANUP_PERIOD_DAYS Período de limpieza automática de worktrees huérfanos Días
CLAUDE_CODE_DISABLE_WORKTREE_AUTO_CLEANUP Deshabilitar la limpieza automática de worktrees 1

Variables específicas de GitHub Actions

Nombre de la variable Descripción Valor
ANTHROPIC_VERTEX_PROJECT_ID ID del proyecto Vertex AI (establecido por el paso de autenticación al usar Vertex) ID del proyecto GCP
CLOUD_ML_REGION Región de Vertex AI Código de región (comous-east5)

Método de configuración de settings.json

Todas las variables de entorno se pueden configurar ensettings.jsonEsta forma es más declarativa y portable:

Ejemplo

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-3-5",
    "CLAUDE_CODE_PERMISSION_MODE": "plan",
    "CLAUDE_CODE_ALLOWED_TOOLS": "Read,Grep,Glob,Bash",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

Configuración del complemento VS Code

Al usar el complemento Claude Code en VS Code, se puede configurar medianteenvironmentVariablesconfiguración:

Ejemplo

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://custom-proxy.com/api"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "your-token-here"
    },
    {
      "name": "ANTHROPIC_MODEL",
      "value": "claude-sonnet-4-5"
    }
  ]
}

Casos de uso comunes

Escenario 1: Uso de un proxy o punto final de API personalizado

Ejemplo

# Acceder a la API de Claude a través de un proxy interno de la empresa
export ANTHROPIC_BASE_URL="https://proxy.company.com/anthropic/v1"
export ANTHROPIC_API_KEY="your-api-key"

Escenario 2: Optimización de la configuración de costos

Ejemplo

# La conversación principal usa Sonnet, los subagentes usan Haiku de manera uniforme
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-3-5"

Escenario 3: Configuración segura en entornos CI/CD

Ejemplo

# Usar modo de solo lectura en entornos CI
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_DISABLE_HISTORY="1"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

Escenario 4: Entorno de Windows PowerShell

Ejemplo

# Habilitar PowerShell en Windows
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"
# Establecer defaultShell en settings.json

Prioridad y anulación

Prioridad de las variables de entorno (de mayor a menor):

  1. Línea de comandosexportConfiguración
  2. Nivel de proyecto.claude/settings.json
  3. Nivel de usuario~/.claude/settings.json
  4. Valores predeterminados de Claude Code

Ensettings.jsonLas variables configuradas en el archivo anulan las variables de entorno del shell con el mismo nombre. Esto se debe a que settings.json se lee explícitamente al iniciar el proceso de Claude Code, por lo que tiene mayor prioridad.


Ver la configuración actual

Usando/configel comando permite ver la configuración completa actual:

/config

Esto mostrará todos los ajustes actualmente activos, incluidas las variables de entorno y la configuración en settings.json.


Mejores prácticas

1. Manejo de información sensible

  • No codifiques directamente (hardcodear) información sensible como claves API en settings.json
  • Usa variables de entorno o archivos de configuración del shell (~/.bashrc、~/.zshrc)
  • Asegúrate de que los archivos que contengan información sensible no estén en el control de versiones de git

2. Configuración por entorno

  • Desarrollo local: usar un modo de permisos más permisivo
  • CI/CD: usar modo de solo lecturaplan
  • Depuración en producción: habilitarCLAUDE_CODE_DEBUG

3. Gestión centralizada

  • La configuración general se coloca en~/.claude/settings.json
  • La configuración específica del proyecto se coloca en el directorio del proyecto.claude/settings.json
  • La configuración sensible se proporciona mediante variables de entorno del shell o CI Secrets

Preguntas frecuentes

P: ¿Cuál tiene prioridad, las variables de entorno o settings.json?

Las variables configuradas en settings.json tienen mayor prioridad y sobrescriben las variables de entorno del shell con el mismo nombre.

P: ¿Cómo hacer que Claude Code use un endpoint de API diferente?

ConfiguraANTHROPIC_BASE_URLla variable de entorno para que apunte a tu proxy o endpoint personalizado.

P: ¿Cómo controlan los subagentes el modelo que usan?

Se puedeCLAUDE_CODE_SUBAGENT_MODELconfigurar el modelo de todos los subagentes de forma unificada, o especificarlo individualmente en el frontmatter de cada subagente.

P: ¿Cómo habilitar PowerShell en Windows?

Configura la variable de entornoCLAUDE_CODE_USE_POWERSHELL_TOOL=1, y además configura en settings.jsondefaultShell: "powershell"。

P: ¿Cómo desactivar todos los comandos de barra?

ConfiguraCLAUDE_CODE_DISABLE_SLASH_COMMANDS=1la variable de entorno.

Otras extensiones