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 shell
export - 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
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
Ejemplo
{
"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
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ónacceptEdits: Aceptar automáticamente la edición de archivos, sin confirmacióndontAsk: Rechazar automáticamente operaciones no autorizadas, sin interrumpir la ejecuciónbypassPermissions: 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
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
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
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
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
$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):
- Línea de comandos
exportConfiguración - Nivel de proyecto
.claude/settings.json - Nivel de usuario
~/.claude/settings.json - Valores predeterminados de Claude Code
En
settings.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 lectura
plan - Depuración en producción: habilitar
CLAUDE_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.