Guía completa de variables de entorno de Claude Code: solucione el error de compatibilidad de AWS Bedrock con solo 1 ajuste

Nota del autor: Explicación detallada de la función y configuración de las más de 60 variables de entorno de Claude Code, con especial énfasis en cómo CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS resuelve el error de cabecera anthropic-beta en plataformas de terceros.

Al usar Claude Code para conectarse a AWS Bedrock, Google Vertex AI u otras pasarelas de LLM de terceros, es muy probable que te hayas topado con este error: "Unexpected value(s) for the anthropic-beta header". La raíz de este problema es que Claude Code envía por defecto cabeceras beta experimentales específicas de la API de Anthropic, las cuales no son reconocidas por plataformas de terceros como AWS Bedrock.

La solución requiere solo una línea de configuración: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Sin embargo, las variables de entorno de Claude Code van mucho más allá de esta: la documentación oficial enumera más de 60 variables de entorno que cubren la configuración de autenticación, selección de modelo, ajuste de rendimiento, interruptores de funciones y más. En este artículo, organizaremos sistemáticamente estas variables para ayudarte a localizar y resolver rápidamente cualquier problema de configuración en Claude Code.

Valor principal: Al terminar de leer, dominarás el sistema completo de variables de entorno de Claude Code, podrás resolver problemas de compatibilidad con AWS Bedrock/Vertex AI y aprenderás a optimizar tu experiencia de uso y costes mediante estas configuraciones.

Puntos clave de las variables de entorno de Claude Code

Las más de 60 variables de entorno de Claude Code se pueden dividir en 6 categorías principales. Aquí tienes las variables fundamentales a las que debes prestar atención:

Dos formas de configurar las variables de entorno de Claude Code

Método 1: Variables de entorno de Shell (Efecto temporal)

Se configuran en la terminal antes de iniciar Claude Code, solo son válidas para la sesión actual:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_API_KEY="tu-clave-api"
claude

Método 2: Configuración en settings.json (Efecto permanente)

Configura el campo env en ~/.claude/settings.json, se cargará automáticamente en cada inicio:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_API_KEY": "tu-clave-api"
  }
}

🎯 Recomendación: Para configuraciones que deban ser permanentes (como la clave API o correcciones de compatibilidad de plataforma), se sugiere usar el método settings.json para evitar tener que hacer export manualmente cada vez. Si tu clave API proviene de una plataforma de terceros como APIYI (apiyi.com), configúrala también aquí.

Claves de las variables de entorno de Claude Code: Solucionando la compatibilidad con AWS Bedrock

Análisis detallado de CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS

Esta es la protagonista de este artículo. Cuando utilizas Claude Code a través de gateways de terceros como AWS Bedrock, Google Vertex AI o LiteLLM, Claude Code añade automáticamente encabezados de identificación Beta experimentales de Anthropic en las solicitudes, por ejemplo:

anthropic-beta: prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20

Estos identificadores Beta son características propias de la API directa de Anthropic. Las plataformas de terceros como AWS Bedrock no pueden reconocerlos, lo que provoca el siguiente error:

Error: Unexpected value(s) for the anthropic-beta header

Solución:

# Opción 1: Comando en la Shell
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# Opción 2: settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Al establecerlo en 1, Claude Code dejará de enviar estos encabezados Beta experimentales, garantizando la compatibilidad con todas las plataformas de terceros.

Problemas conocidos y soluciones temporales

Según los registros de Issues en GitHub, algunas versiones de Claude Code (posteriores a la 2.1.18) presentan un problema donde esta variable de entorno no surte efecto por completo; incluso con CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, algunos encabezados Beta nuevos (como advanced-tool-use-2025-11-20) se siguen enviando.

Si continúas experimentando problemas, puedes intentar estas medidas adicionales:

• Degradar la versión de Claude Code: Regresa a una versión estable conocida como la 2.1.68.
• Usar el gateway LiteLLM: LiteLLM ofrece el archivo de configuración anthropic_beta_headers_config.json, que permite un control granular sobre qué encabezados Beta se reenvían.
• Configurar simultáneamente DISABLE_PROMPT_CACHING: Desactivar el almacenamiento en caché de indicaciones puede evitar los encabezados Beta relacionados con prompt-caching-scope.

# Configuración de compatibilidad total
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

Guía rápida de clasificación de variables de entorno de Claude Code

Categoría 1: Autenticación y configuración de API

Esta es la categoría más básica y utilizada, que controla cómo se conecta Claude Code al servicio de API:

🎯 Nota para usuarios de plataformas de terceros: Al usar plataformas de API de terceros como APIYI (apiyi.com), es necesario configurar tanto ANTHROPIC_API_KEY como ANTHROPIC_BASE_URL. Claude Code priorizará la clave API de las variables de entorno, incluso si ya has iniciado sesión con una cuenta de suscripción de Anthropic.

Categoría 2: Selección y configuración del modelo

Controla qué modelo utiliza Claude Code y los parámetros de comportamiento del mismo:

Categoría 3: Compatibilidad de plataforma y configuración de gateway

Estas variables están diseñadas específicamente para resolver problemas de compatibilidad entre Claude Code y diferentes plataformas en la nube o gateways de LLM:

Categoría 4: Interruptores de funciones (Feature Flags)

Desactiva funciones específicas mediante variables con el prefijo DISABLE_ o CLAUDE_CODE_DISABLE_:

Categoría 5: Gestión de contexto y rendimiento

Controla cómo gestiona Claude Code la ventana de contexto y el uso de recursos:

🎯 Sugerencia de optimización de rendimiento: Si notas que Claude Code comprime el contexto con demasiada frecuencia en conversaciones largas, puedes establecer CLAUDE_AUTOCOMPACT_PCT_OVERRIDE en un valor más bajo (como 50) para que la compresión se active antes, reduciendo la pérdida de información. Estas configuraciones de variables de entorno también son compatibles cuando realizas la invocación del modelo a través de APIYI (apiyi.com).

Guía rápida de variables de entorno para Claude Code

Ejemplo minimalista: Configurar Claude Code para conectar con plataformas de API de terceros

# Inicia Claude Code tras configurar las variables de entorno en la terminal
export ANTHROPIC_API_KEY="sk-your-api-key"
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com/v1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": []
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1",
    "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION": "us-east-1"
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_BASE_URL": "https://my-resource.services.ai.azure.com/anthropic",
    "ANTHROPIC_FOUNDRY_API_KEY": "your-foundry-key",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Sugerencia: Si no quieres complicarte con las configuraciones complejas de AWS Bedrock o Azure, puedes usar toda la serie de modelos Claude directamente a través de APIYI (apiyi.com). Solo necesitas configurar dos variables, la clave API y la Base URL, sin tener que lidiar con la autenticación de plataformas en la nube ni problemas de compatibilidad.

Preguntas frecuentes

Resumen

Puntos clave sobre las variables de entorno de Claude Code:

1. Solución al error de AWS Bedrock: Configura CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 para desactivar los encabezados Beta experimentales. Esta configuración de una sola línea resuelve el error "Unexpected value(s) for the anthropic-beta header".
2. Más de 60 variables en 6 categorías: Autenticación, selección de modelo, compatibilidad de plataforma, interruptores de funciones, gestión de contexto y otros ajustes.
3. Dos métodos de configuración: Shell export (temporal) y settings.json (permanente). Se recomienda la configuración permanente dentro de settings.json.
4. Solución simplificada con plataformas de terceros: Al usar plataformas de API unificadas como APIYI (apiyi.com), solo necesitas configurar dos variables: ANTHROPIC_API_KEY y ANTHROPIC_BASE_URL. Esto elimina la necesidad de lidiar con la compleja autenticación de nubes públicas y los problemas de compatibilidad de los encabezados Beta.

Te recomendamos probar Claude Code a través de APIYI (apiyi.com) para una experiencia rápida. La plataforma ofrece cuotas gratuitas y una interfaz unificada, evitando los típicos dolores de cabeza de configuración en AWS Bedrock o Vertex AI.

📚 Referencias

1. Documentación oficial de Claude Code – Variables de entorno: Lista completa de variables y sus descripciones.

   • Enlace: code.claude.com/docs/en/env-vars
   • Nota: Referencia oficial de las más de 60 variables disponibles.

2. Documentación oficial de Claude Code – Configuración: Ámbitos de configuración y especificaciones del settings.json.

   • Enlace: code.claude.com/docs/en/settings
   • Nota: Para entender el sistema de jerarquía de cuatro niveles (Managed/User/Project/Local).

3. Documentación oficial de Claude Code – Amazon Bedrock: Guía de integración con AWS Bedrock.

   • Enlace: code.claude.com/docs/en/amazon-bedrock
   • Nota: Configuraciones específicas para Bedrock y resolución de problemas comunes.

4. GitHub Issue #22893 – DISABLE_EXPERIMENTAL_BETAS no funciona completamente: Informe de errores de la comunidad.

   • Enlace: github.com/anthropics/claude-code/issues/22893
   • Nota: Información sobre limitaciones conocidas y soluciones temporales para esta variable.

5. LiteLLM – Gestión de encabezados Beta en Claude Code: Solución de filtrado de encabezados Beta a nivel de gateway.

   • Enlace: docs.litellm.ai/docs/tutorials/claude_code_beta_headers
   • Nota: Control detallado de encabezados Beta al usar el gateway de LiteLLM.

Autor: Equipo técnico de APIYI
Comunidad: Te invitamos a compartir tu experiencia configurando Claude Code en la sección de comentarios. Para más tutoriales, visita nuestro centro de documentación en docs.apiyi.com.