Variables de entorno de Claude Code: documentación oficial

En resumen

Define ANTHROPIC_API_KEY en el rc de tu shell o en un archivo .env. Claude Code lee la variable al arrancar:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Para un proxy corporativo o un modelo distinto, usa ANTHROPIC_BASE_URL y ANTHROPIC_MODEL. Los detalles completos están más abajo.

Variables de entorno: principio y fuentes de lectura

Una variable de entorno es un valor con nombre almacenado en tu sesión de shell, accesible por cualquier programa que se ejecute en ella. Imagina notas adhesivas pegadas a cada proceso: al arrancar, Claude Code las lee y adapta su comportamiento en consecuencia.

Claude Code lee las variables de entorno desde cuatro fuentes, en este orden:

1. Entorno del sistema (/etc/environment, /etc/profile.d/): alcance de toda la máquina, definido por los administradores
2. Archivos rc del shell (~/.bashrc, ~/.zshrc, ~/.profile): ajustes persistentes por usuario
3. Archivo .env en la carpeta del proyecto actual: sobrescrituras por proyecto (se carga automáticamente)
4. Parámetro de VS Code claudeCode.environmentVariables: inyección desde el editor (ver sección dedicada)

Los flags de CLI y las claves equivalentes en settings.json tienen prioridad sobre las variables de entorno cuando existe un equivalente directo.

Variables de autenticación

ANTHROPIC_API_KEY

# Persistencia en el archivo rc de tu shell
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"

# Sobrescritura puntual para un solo comando
ANTHROPIC_API_KEY="sk-ant-..." claude --print "hola"

# GitHub Actions: pasarla desde un secreto cifrado
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_AUTH_TOKEN="token-bearer-de-tu-proxy"

Algunas pasarelas de IA corporativas usan su propio formato de token. Usa esta variable cuando tu proxy devuelva 401 Unauthorized a pesar de tener una ANTHROPIC_API_KEY válida.

ANTHROPIC_BASE_URL

# Pasarela de IA corporativa
export ANTHROPIC_BASE_URL="https://pasarela-ia.empresa.com/anthropic"

# Servidor mock local para pruebas
export ANTHROPIC_BASE_URL="http://localhost:8080"

Esta variable sobrescribe el campo customApiUrl de settings.json. Es útil cuando el tráfico de la API pasa por un proxy gestionado por la empresa o por un endpoint regional.

ANTHROPIC_MODEL / CLAUDE_MODEL

# Haiku para velocidad y ahorro
export CLAUDE_MODEL="claude-haiku-4-5"

# Opus para tareas de razonamiento complejo
export CLAUDE_MODEL="claude-opus-4-8"

# Sobrescritura puntual sin tocar el archivo rc
CLAUDE_MODEL="claude-opus-4-8" claude --print "tarea difícil"

ANTHROPIC_MODEL es un alias aceptado de CLAUDE_MODEL. Ambos funcionan de forma idéntica. Usa CLAUDE_MODEL en las configuraciones nuevas para mantener la coherencia con la documentación oficial.

Identificadores de modelo habituales:

• claude-haiku-4-5: rápido y económico, adecuado para automatización
• claude-sonnet-5: equilibrio recomendado entre capacidad y coste
• claude-opus-4-8: el razonamiento más profundo, el coste más alto

CLAUDE_CODE_USE_BEDROCK

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1"
# Autenticación vía AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
# o vía rol IAM en EC2/ECS

Cuando esta variable está definida, Claude Code usa el SDK de AWS para autenticarse. ANTHROPIC_API_KEY se ignora; en su lugar se usan las credenciales de AWS.

CLAUDE_CODE_USE_VERTEX

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-central1"
export ANTHROPIC_VERTEX_PROJECT_ID="tu-proyecto-gcp"
# Autenticarse vía gcloud application-default login

Variables de comportamiento

MAX_THINKING_TOKENS

# Reducir el presupuesto para bajar el coste en tareas rutinarias
export MAX_THINKING_TOKENS=10000

# Presupuesto completo para sesiones de arquitectura o depuración compleja
export MAX_THINKING_TOKENS=31999

# Desactivar de facto el razonamiento profundo (valor mínimo)
export MAX_THINKING_TOKENS=1000

Solo se aplica cuando alwaysThinkingEnabled: true está en settings.json, o cuando Extended Thinking se activa manualmente. Reducir este valor acorta la cadena de pensamiento interna y disminuye el coste en tokens asociado.

BASH_MAX_OUTPUT_LENGTH

# Valor por defecto, adecuado para la mayoría de comandos
export BASH_MAX_OUTPUT_LENGTH=10000

# Aumentarlo para comandos con salida voluminosa (logs de build, suites de test)
export BASH_MAX_OUTPUT_LENGTH=50000

# Reducirlo para proteger la ventana de contexto en modelos costosos
export BASH_MAX_OUTPUT_LENGTH=5000

Cuando un comando produce más caracteres que este límite, Claude Code trunca el resultado y añade una nota. Esto evita que un simple cat archivo-grande.log sature toda la ventana de contexto.

BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS

export BASH_DEFAULT_TIMEOUT_MS=120000   # 2 min por defecto por comando
export BASH_MAX_TIMEOUT_MS=600000       # 10 min de límite (el usuario no puede superarlo)

Aumenta BASH_DEFAULT_TIMEOUT_MS para builds lentos o suites de test largas. BASH_MAX_TIMEOUT_MS es el límite que el usuario no puede superar aunque sobrescriba el timeout manualmente en la conversación.

CLAUDE_CODE_MAX_OUTPUT_TOKENS

# Limitar las respuestas para controlar costes en automatización
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096

# Permitir respuestas largas para generación de código
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

DISABLE_AUTOUPDATER

export DISABLE_AUTOUPDATER=1

Actívala siempre en CI/CD. Una actualización automática durante un pipeline puede cambiar el comportamiento de forma inesperada. Combínala con una instalación en versión fija: npm install -g @anthropic-ai/claude-code@x.y.z.

DISABLE_TELEMETRY

export DISABLE_TELEMETRY=1

DISABLE_ERROR_REPORTING

export DISABLE_ERROR_REPORTING=1

DISABLE_COST_WARNINGS

export DISABLE_COST_WARNINGS=1

Útil en scripts no interactivos donde el aviso ensuciaría el parseo de stdout.

CLAUDE_CONFIG_DIR

# Configuración aislada por proyecto
export CLAUDE_CONFIG_DIR="$(pwd)/.claude-config"

# Configuración compartida en un agente de CI
export CLAUDE_CONFIG_DIR="/opt/claude-code/config"

# Configuración efímera para contenedores desechables
export CLAUDE_CONFIG_DIR="/tmp/claude-ci-$$"

CLAUDE_CODE_DISABLE_TERMINAL_TITLE

export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1

Útil para usuarios de tmux y otros multiplexores de terminal que aprovechan la cadena del título para seguir los paneles.

Variables de red y proxy

HTTP_PROXY / HTTPS_PROXY

# Proxy sin autenticación
export HTTP_PROXY="http://proxy.empresa.com:8080"
export HTTPS_PROXY="http://proxy.empresa.com:8080"

# Proxy con autenticación (codifica los caracteres especiales de la contraseña en la URL)
export HTTPS_PROXY="http://jdoe:c%40ntrasena@proxy.empresa.com:8080"

# Proxy SOCKS5
export HTTPS_PROXY="socks5://proxy.empresa.com:1080"

En redes corporativas, estas son las variables que hay que configurar con más frecuencia. Claude Code las usa para todas las peticiones salientes, incluidas las llamadas a la API hacia api.anthropic.com.

NO_PROXY

export NO_PROXY="localhost,127.0.0.1,::1,*.corp.ejemplo.com"

# Combinar con HTTPS_PROXY
export HTTPS_PROXY="http://proxy.empresa.com:8080"
export NO_PROXY="localhost,127.0.0.1,*.intranet.empresa.com"

Variables MCP

MCP_TIMEOUT / MCP_TOOL_TIMEOUT

export MCP_TIMEOUT=30000         # 30 s para servidores MCP lentos al arrancar
export MCP_TOOL_TIMEOUT=120000   # 2 min para llamadas a herramientas de larga duración

MAX_MCP_OUTPUT_TOKENS

export MAX_MCP_OUTPUT_TOKENS=50000

claudeCode.environmentVariables en VS Code

La extensión oficial de Claude Code para VS Code expone el parámetro claudeCode.environmentVariables, un objeto JSON que se inyecta en cada proceso de Claude Code lanzado desde el editor. Es la forma más limpia de configurar valores por workspace sin tocar los archivos de shell globales.

Abre settings.json (a nivel de User o Workspace) y añade:

{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "https://pasarela-ia.empresa.com/anthropic",
    "CLAUDE_MODEL": "claude-sonnet-5",
    "DISABLE_AUTOUPDATER": "1",
    "BASH_MAX_OUTPUT_LENGTH": "30000",
    "NO_PROXY": "localhost,127.0.0.1,*.intranet"
  }
}

El nombre del parámetro se escribe en camelCase: claudeCode.environmentVariables. Las claves internas distinguen mayúsculas de minúsculas: ANTHROPIC_API_KEY no equivale a anthropic_api_key.

Persistir las variables según el entorno

Archivos rc del shell (desarrollo local)

# Añadir en ~/.bashrc o ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export CLAUDE_MODEL="claude-sonnet-5"
export DISABLE_TELEMETRY=1

Ejecuta source ~/.zshrc (o abre un terminal nuevo) tras modificarlo.

Servicio systemd de usuario

Si ejecutas Claude Code mediante un servicio systemd:

# ~/.config/systemd/user/claude-code.service
[Service]
Environment=ANTHROPIC_API_KEY=sk-ant-api03-...
Environment=CLAUDE_MODEL=claude-sonnet-5
Environment=DISABLE_AUTOUPDATER=1

O usa EnvironmentFile=/etc/claude-code/env para cargar desde un archivo separado y no almacenar secretos en la unidad de servicio.

Docker

# Pasar en tiempo de build (solo configuración no secreta)
ARG CLAUDE_MODEL=claude-sonnet-5
ENV CLAUDE_MODEL=$CLAUDE_MODEL
ENV DISABLE_AUTOUPDATER=1
ENV BASH_MAX_OUTPUT_LENGTH=30000

# Pasar los secretos en tiempo de ejecución: nunca los incluyas en la imagen
docker run \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -e CLAUDE_MODEL=claude-haiku-4-5 \
  mi-imagen-claude

Gestores de secretos

Para pipelines de producción, evita almacenar las claves API en bruto en archivos de shell. Recupéralas en tiempo de ejecución:

# AWS Secrets Manager
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id prod/anthropic-api-key \
  --query SecretString \
  --output text)

# HashiCorp Vault
export ANTHROPIC_API_KEY=$(vault kv get -field=value secret/anthropic)

Seguridad

• Añade .env a .gitignore y a tu .gitignore_global para prevenir commits accidentales.
• Nunca escribas ANTHROPIC_API_KEY directamente en un Dockerfile, un archivo YAML de CI o cualquier archivo versionado.
• Usa los secretos del repositorio (GitHub Secrets, variables de GitLab CI) para los pipelines de CI/CD.
• Rota tu clave API al menos cada 90 días. Rotación inmediata si sospechas de una exposición.
• Audita quién tiene acceso de lectura a los archivos que contienen la clave (~/.bashrc, /etc/environment).

# Entradas mínimas de .gitignore
.env
.env.local
.env.*.local
*.key

Orden de prioridad

Cuando el mismo ajuste está presente en varias fuentes, Claude Code las resuelve en este orden. Las fuentes más tardías ganan:

Los flags de CLI siempre ganan. Los valores de settings.json tienen prioridad sobre las variables de entorno cuando existe una clave equivalente directa.

Solución de problemas

Comprobar qué variables ve Claude Code

# Listar todas las variables que contengan "claude" o "anthropic" (sin distinguir mayúsculas)
env | grep -iE "claude|anthropic|proxy"

# Comprobar el formato de la clave (debe empezar por sk-ant-)
echo $ANTHROPIC_API_KEY | cut -c1-12

Confirmar que una variable está definida en un shell nuevo

# Abrir un shell nuevo y probar
bash -c 'echo $ANTHROPIC_API_KEY'

Si el resultado está vacío aunque tu sesión actual tenga el valor, falta el export en tu archivo rc (la variable puede estar definida sin export).

Depurar problemas al arrancar

# Mostrar la versión (confirma que la instalación funciona)
claude --version

# Probar que la clave API llega a Anthropic
claude --print "hola" 2>&1 | head -20

Variable definida pero ignorada

Causas posibles:

• La variable está definida pero no exportada (VAR=valor en lugar de export VAR=valor)
• Una clave de settings.json con prioridad más alta la sobrescribe
• Un error tipográfico en el nombre de la variable (usa env | grep para comprobarlo)
• En VS Code, el settings.json de Workspace sobrescribe el settings.json de User con un valor en conflicto

# Comprobar que la variable está exportada, no solo definida
export -p | grep ANTHROPIC

ANTHROPIC_BASE_URL se ignora

Comprueba que HTTPS_PROXY no esté interceptando y redirigiendo la petición. Añade el nombre de host de la base URL a NO_PROXY:

export ANTHROPIC_BASE_URL="https://pasarela-ia.empresa.com/anthropic"
export HTTPS_PROXY="http://proxy.empresa.com:8080"
export NO_PROXY="pasarela-ia.empresa.com,localhost,127.0.0.1"

Tabla de referencia completa

*Salvo que hayas iniciado sesión con claude login (cuenta Claude.ai Max)

Ejemplos de configuración

Desarrollo local

# ~/.zshrc o ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export CLAUDE_MODEL="claude-sonnet-5"
export MAX_THINKING_TOKENS=10000
export DISABLE_TELEMETRY=1

CI/CD (GitHub Actions)

# .github/workflows/claude.yml
jobs:
  claude-task:
    runs-on: ubuntu-latest
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      CLAUDE_MODEL: claude-haiku-4-5
      DISABLE_AUTOUPDATER: "1"
      DISABLE_COST_WARNINGS: "1"
      CLAUDE_CODE_MAX_OUTPUT_TOKENS: "4096"
      BASH_MAX_OUTPUT_LENGTH: "20000"
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code@latest
      - run: claude --print --max-turns 5 "Revisa la calidad del código"

Red corporativa con proxy

# /etc/environment o perfil del sistema
ANTHROPIC_API_KEY="sk-ant-..."
ANTHROPIC_BASE_URL="https://pasarela-ia.empresa.com"
HTTPS_PROXY="http://proxy-web.empresa.com:8080"
NO_PROXY="localhost,127.0.0.1,pasarela-ia.empresa.com,*.interna.empresa.com"
DISABLE_AUTOUPDATER=1
CLAUDE_CONFIG_DIR="/opt/claude-code/config"

Preguntas frecuentes

Próximos pasos

• settings.json: guía completa: todas las claves de configuración y su prioridad frente a las variables de entorno
• CLI: referencia completa: todos los flags del comando claude
• Hoja de referencia: referencia rápida de comandos slash y atajos de teclado