# Variables de entorno {#environment-variables} > Consulta las variables de entorno, sus valores predeterminados y dónde se aplica cada una. Estas variables afectan al proceso de Clarvis, incluida la interfaz local y todos los proyectos que abre. Defínelas en el entorno que inicia Clarvis, no en `.clarvis/settings.json`. Esta página también cubre el instalador portable; no incluye opciones de despliegue de servidores remotos. En las variables booleanas, no definir un valor conserva el predeterminado. Las cadenas `false`, `0`, `no`, `off` y el valor vacío significan falso, sin distinguir mayúsculas; cualquier otra cadena significa verdadero. Los números o valores de enumeración no válidos, o un valor predeterminado superior a su límite, detienen el inicio con el error `Invalid environment configuration`. ## Rutas y TUI {#paths-and-the-tui} | Variable | Valor predeterminado | Efecto | | -------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CLARVIS_HOME` | `~/.clarvis` | Sustituye la raíz global de configuración y estado. Usa el mismo valor al hacer copias de seguridad, limpiar o diagnosticar esa instalación. | | `CLARVIS_WORKSPACE_ROOT` | Directorio actual | Sustituye la raíz del espacio de trabajo para una integración o un lanzador. En el uso habitual, inicia `clarvis` desde el proyecto que quieras abrir. | | `CLARVIS_OWNER` | Propietario elegido por el host | Separa el estado de cada operador cuando un host atiende a varios operadores. | | `CLARVIS_DEFAULT_MODEL` | Sin definir | Última opción de `provider/model` si ni la configuración ni el agente seleccionado indican uno. Para el uso interactivo habitual, usa `/model`. | | `CLARVIS_CODE_DEBUG` | Desactivado | Abre los diagnósticos acotados de la TUI. Un nivel (`error`, `warn`, `info` o `debug`) los activa y ajusta; otro valor verdadero usa `debug`. | | `CLARVIS_CODE_DEBUG_LEVEL` | `debug` | Ajusta los diagnósticos activados con `CLARVIS_CODE_DEBUG`; `--debug=` tiene prioridad. | | `CLARVIS_TUI_RSS_LIMIT_MB` | `2048` | Límite de protección de memoria del proceso interactivo, en MiB. `0` lo desactiva; los valores positivos tienen un mínimo de 512 MiB. | ## Límites máximos y valores predeterminados de ejecución {#run-ceilings-and-defaults} Un límite máximo es el mayor valor admitido. Se rechazan los agentes o ajustes que lo superen. Una variable `CLARVIS_DEFAULT_*` solo aporta un valor predeterminado si el agente o `settings.json` no define otro. | Variable | Valor predeterminado | Efecto | | ------------------------------------------- | -------------------: | ----------------------------------------------------------------------------------------------------- | | `CLARVIS_TOKEN_CEILING` | `200000000` | Límite máximo de tokens admitido por ejecución. | | `CLARVIS_ITERATION_CEILING` | `200` | Límite máximo de iteraciones del agente. | | `CLARVIS_TIMEOUT_CEILING_MS` | `600000` | Tiempo máximo de inactividad o de espera de una llamada al modelo. | | `CLARVIS_ESCALATION_CEILING` | `20` | Número máximo de ampliaciones de presupuesto. | | `CLARVIS_RETRY_CEILING` | `10` | Número máximo de reintentos del proveedor. | | `CLARVIS_RETRY_AFTER_CEILING_MS` | `300000` | Demora máxima de reintento solicitada por el proveedor. | | `CLARVIS_DEFAULT_TOTAL_TOKEN_LIMIT` | `160000000` | Presupuesto acumulado de tokens de entrada y salida por ejecución, si no se define otro. | | `CLARVIS_DEFAULT_TIMEOUT_MS` | `300000` | Tiempo de inactividad predeterminado. | | `CLARVIS_DEFAULT_ON_EXCEED` | `escalate` | Comportamiento al alcanzar un límite: `stop` o `escalate`. | | `CLARVIS_DEFAULT_MAX_ESCALATIONS` | `5` | Ampliaciones de presupuesto permitidas por defecto. | | `CLARVIS_DEFAULT_ELICIT_WAIT_MS` | `1800000` | Espera máxima de una respuesta interactiva. | | `CLARVIS_DEFAULT_ITERATION_LIMIT` | `200` | Límite de iteraciones del agente principal, si no se define otro. | | `CLARVIS_DEFAULT_CONTEXT_WINDOW_TOKENS` | `128000` | Ventana de contexto usada cuando el catálogo de modelos no aporta un valor. | | `CLARVIS_DEFAULT_STAGNATION_THRESHOLD` | `3` | Repeticiones sin progreso que activan la protección contra el estancamiento. | | `CLARVIS_DEFAULT_STAGNATION_SOFT_THRESHOLD` | `2` | Umbral de aviso previo al límite de estancamiento; `0` desactiva los avisos. | | `CLARVIS_GUARD_MAX_ESCALATIONS` | `2` | Excepciones humanas permitidas tras activar la protección contra el estancamiento; `0` las desactiva. | | `CLARVIS_DEFAULT_CALL_TIMEOUT_MS` | `180000` | Ventana de inactividad del streaming; límite absoluto hasta que haya progreso observable. | | `CLARVIS_DEFAULT_REASONING_SUMMARY` | `off` | Resumen de razonamiento predeterminado: `off`, `auto` o `detailed`. | | `CLARVIS_DEFAULT_REASONING_EFFORT` | Sin definir | Esfuerzo predeterminado: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` o `max`. | | `CLARVIS_DEFAULT_MAX_RETRIES` | `3` | Reintentos predeterminados de una llamada al modelo. | | `CLARVIS_DEFAULT_MAX_RETRY_AFTER_MS` | `60000` | Demora máxima de reintento aceptada por defecto. | | `CLARVIS_DEFAULT_FORCE_TOOL_ON_NUDGE` | Activado | Exige una llamada a herramienta después de que el bucle pida avanzar a un agente estancado. | | `CLARVIS_DEFAULT_PENDING_TASK_NUDGES` | `3` | Avisos consecutivos sobre tareas del plan antes de dejar de pedir su finalización. | | `CLARVIS_STREAM` | Activado | Activa el streaming del modelo cuando el proveedor lo admite. | Todo valor predeterminado asociado a un límite máximo debe ser igual o inferior a él. Por ejemplo: ```bash CLARVIS_TOKEN_CEILING=400000000 \ CLARVIS_DEFAULT_TOTAL_TOKEN_LIMIT=180000000 \ CLARVIS_ITERATION_CEILING=400 \ clarvis ``` ## Compactación {#compaction} | Variable | Valor predeterminado | Efecto | | --------------------------------------------------- | -------------------: | ---------------------------------------------------------------------------------------------------- | | `CLARVIS_DEFAULT_COMPACTION_ENABLED` | Activado | Activa la compactación automática del contexto. | | `CLARVIS_DEFAULT_COMPACTION_CONTEXT_FRACTION` | `0.8` | Ocupación del contexto a partir de la cual se puede compactar. Debe ser mayor que 0 y como máximo 1. | | `CLARVIS_DEFAULT_COMPACTION_TARGET_FRACTION` | `0.5` | Ocupación deseada tras compactar. Debe ser mayor que 0 y como máximo 1. | | `CLARVIS_DEFAULT_COMPACTION_MAX_RESULT_CHARS` | Sin definir | Máximo opcional de caracteres aceptados en el resultado de la compactación. | | `CLARVIS_DEFAULT_COMPACTION_PRESERVE_RECENT_TOKENS` | Sin definir | Cantidad opcional de tokens recientes que se conservan fuera del resumen. | | `CLARVIS_COMPACTION_LLM_TIMEOUT_MS` | `120000` | Duración máxima de la llamada al modelo de compactación. | ## Herramientas, capacidades y concurrencia {#tools-capabilities-and-concurrency} | Variable | Valor predeterminado | Efecto | | ------------------------------------------------------ | -------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLARVIS_AGENT_TOOLS_ENABLED` | Activado | Registra las herramientas de gestión de agentes. | | `CLARVIS_AGENT_TOOLS_CONFINE` | Activado | Limita esas herramientas a la ejecución actual y a la política del espacio de trabajo. | | `CLARVIS_AGENT_TOOLS_MAX_GRANT` | `edit` | Permiso máximo del esquema del host: `none`, `read`, `edit` o `exec`. La TUI interactiva usa `exec` antes de crear el núcleo, salvo que se defina otro valor. | | `CLARVIS_SKILLS_ENABLED` | Activado | Registra la búsqueda de skills y `load_skill`. | | `CLARVIS_HOOKS_ENABLED` | Activado | Registra los hooks del ciclo de vida. | | `CLARVIS_MEMORY_TOOL_CALL_LIMIT` | `12` | Presupuesto por ejecución de herramientas de lectura de memoria; no cuenta las escrituras. | | `CLARVIS_MEMORY_LOCK_WARN_MS` | `5000` | Avisa si un bloqueo del árbol de memoria dura más de este tiempo. | | `CLARVIS_CAPABILITY_SETUP_TIMEOUT_MS` | `5000` | Duración máxima de activación e inicialización por capacidad; máximo absoluto de 60 segundos. | | `CLARVIS_CAPABILITY_RUN_END_TIMEOUT_MS` | `2000` | Duración máxima de finalización por capacidad una vez decidida la respuesta. | | `CLARVIS_MAX_CONCURRENT_EXTENSION_CALLS` | `32` | Máximo de llamadas a extensiones en primer plano para todo el host. | | `CLARVIS_MAX_CONCURRENT_EXTENSION_RUN_END_CALLS` | `8` | Máximo de llamadas a extensiones al terminar ejecuciones para todo el host. | | `CLARVIS_MAX_CONCURRENT_EXTENSION_CALLS_PER_OPERATION` | `4` | Máximo de llamadas simultáneas a extensiones de una operación. | | `CLARVIS_MAX_PARALLEL_SUBAGENTS` | `4` | Máximo de subagentes admitidos en paralelo. | | `CLARVIS_MAX_CONCURRENT_MODEL_CALLS` | `4` | Máximo de llamadas físicas simultáneas a modelos para todo el host. | | `CLARVIS_MAX_QUEUED_MODEL_CALLS` | `8` | Máximo de llamadas a modelos en espera al alcanzar ese límite. | | `CLARVIS_RUN_ABORT_SETTLE_MS` | `2000` | Plazo para que termine de cerrarse una ejecución cancelada o agotada. | | `CLARVIS_MODEL_ABORT_SETTLE_MS` | `250` | Plazo de cierre más corto para un transporte físico del proveedor. | Al alcanzar un límite de concurrencia, las operaciones nuevas pueden omitirse o rechazarse, según la función. Aumentar un límite no cambia los permisos de herramientas, la confianza del espacio de trabajo ni las reglas del sandbox. ## Registros y transporte del proveedor {#logging-and-provider-transport} | Variable | Valor predeterminado | Efecto | | -------------------------------------- | -------------------: | ----------------------------------------------------------------------------------------------------------------------------------- | | `CLARVIS_LOG_LEVEL` | `info` | Nivel mínimo global de los registros estructurados: `debug`, `info`, `warn`, `error` o `silent`. | | `CLARVIS_LOG` | Sin definir | Ajustes por componente separados por comas, como `paths.lease=debug,mcp=debug,llm=warn`. Los nombres desconocidos no tienen efecto. | | `CLARVIS_LOG_AUDIT` | Activado | Conserva los registros de auditoría de autenticación y protección de comandos, independientemente del nivel habitual de registro. | | `CLARVIS_STREAM_DEBUG` | Sin definir | Ruta de un archivo JSONL con contadores de streaming de bajo nivel. Déjala sin definir salvo para diagnósticos concretos. | | `CLARVIS_PROVIDER_RETRY_BASE_MS` | `1000` | Demora inicial entre reintentos del proveedor. | | `CLARVIS_PROVIDER_RETRY_MAX_MS` | `30000` | Demora máxima entre reintentos del proveedor. | | `CLARVIS_PROVIDER_MAX_RESPONSE_BYTES` | `33554432` | Tamaño máximo de una respuesta completa del proveedor (32 MiB). | | `CLARVIS_PROVIDER_MAX_SSE_EVENT_BYTES` | `4194304` | Tamaño máximo de un evento SSE del proveedor (4 MiB). | Usa `--debug` o `/debug` para el diagnóstico habitual y acotado. Las variables de registro están dirigidas a operadores del host; no sustituyen la ocultación de secretos ni el canal de auditoría. ## Límites MCP del host {#mcp-host-limits} Los campos de cada servidor, como `startup_timeout_sec`, `tool_timeout_sec`, `env_vars`, `bearer_token_env_var` y las listas de herramientas permitidas o bloqueadas, van en `mcpServers`, no en esta tabla. Consulta [Servidores MCP](/es-ES/guide/mcp-servers). | Variable | Valor predeterminado | Efecto | | -------------------------------------- | -------------------: | -------------------------------------------------------------------------------------------------------------------- | | `CLARVIS_MCP_SERVER_STDERR` | `log` | Trata stderr de servidores stdio como `off`, `log` estructurado o `inherit` sin procesar. Evita `inherit` en la TUI. | | `CLARVIS_MCP_SERVER_STDERR_MAX_BYTES` | `65536` | Máximo de bytes de stderr reenviados por conexión. | | `CLARVIS_MCP_CONNECT_TIMEOUT_MS` | `10000` | Tiempo predeterminado de conexión o inicio. | | `CLARVIS_MCP_TOOL_CALL_TIMEOUT_MS` | `600000` | Tiempo predeterminado de espera de una llamada a herramienta MCP. | | `CLARVIS_MCP_POOL_IDLE_TTL_MS` | `60000` | Tiempo de inactividad antes de cerrar una conexión del grupo. | | `CLARVIS_MCP_STDIO_MAX_FRAME_BYTES` | `16777216` | Tamaño máximo de una trama del protocolo stdio (16 MiB). | | `CLARVIS_MCP_HTTP_MAX_RESPONSE_BYTES` | `16777216` | Tamaño máximo de una respuesta remota (16 MiB). | | `CLARVIS_MCP_HTTP_MAX_SSE_EVENT_BYTES` | `4194304` | Tamaño máximo de un evento SSE remoto (4 MiB). | | `CLARVIS_MCP_MAX_SERVERS_PER_RUN` | `16` | Máximo de servidores por ejecución; no debe superar `CLARVIS_MCP_MAX_CONNECTIONS`. | | `CLARVIS_MCP_MAX_CONNECTIONS` | `32` | Máximo de conexiones abiertas para todo el host. | | `CLARVIS_MCP_MAX_PARALLEL_CONNECTS` | `4` | Máximo de intentos de conexión simultáneos. | | `CLARVIS_MCP_MAX_IDLE_CONNECTIONS` | `8` | Conexiones inactivas que se conservan en el grupo. | | `CLARVIS_MCP_TIMEOUT_STREAK_THRESHOLD` | `3` | Tiempos de espera agotados consecutivos antes de considerar una conexión defectuosa. | | `CLARVIS_MCP_HEALTH_PING_INTERVAL_MS` | `30000` | Intervalo de comprobación de conexión; `0` desactiva las comprobaciones periódicas. | | `CLARVIS_MCP_RESOURCES` | Activado | Activa las herramientas de recursos para todo el host. Cada servidor puede desactivarlas con `resources: false`. | | `CLARVIS_MCP_POOL_SHARING` | `owner` | Aislamiento del grupo de conexiones: `owner` o `workspace`. | ## Conservación de trazas {#trace-retention} | Variable | Valor predeterminado | Efecto | | ----------------------------------- | -------------------: | -------------------------------------------------------------------------------------- | | `CLARVIS_TRACE_TTL_DAYS` | `30` | Antigüedad a partir de la cual las trazas pueden limpiarse; `0` desactiva la limpieza. | | `CLARVIS_TRACE_CLEANUP_INTERVAL_MS` | `3600000` | Intervalo de limpieza en segundo plano. | | `CLARVIS_TRACE_CLEANUP_BATCH_SIZE` | `1000` | Máximo de registros procesados por lote de limpieza. | ## Variables del instalador portable {#portable-installer-variables} Estas variables configuran una instalación gestionada. Usa las mismas rutas al desinstalar. | Variable | Plataforma | Valor predeterminado | Efecto | | ---------------------- | ---------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `CLARVIS_INSTALL_ROOT` | Todas | POSIX: `${XDG_DATA_HOME:-$HOME/.local/share}/clarvis`; Windows: `%LOCALAPPDATA%\Clarvis` | Versiones gestionadas, marcador de activación y metadatos de instalación. El lanzador generado incluye la raíz elegida. | | `CLARVIS_BIN_DIR` | POSIX | `${XDG_BIN_HOME:-$HOME/.local/bin}` | Directorio que contiene el lanzador gestionado `clarvis`. | | `CLARVIS_SKIP_PATH` | Windows | Desactivado | Usa `1` para impedir que el instalador o desinstalador cambie el `PATH` del usuario. | El instalador del código fuente también permite probar artefactos locales al preparar una versión. Esas opciones no son necesarias para instalar una versión publicada y no se detallan aquí. Usa el instalador de la versión que hayas elegido. ## Variables que reciben los hooks y plugins {#variables-passed-to-hooks-and-plugins} Las variables de hooks las proporciona Clarvis; no son ajustes de inicio. Todos los hooks reciben `CLARVIS_HOOK_PROTOCOL`, `CLARVIS_HOOK_EVENT`, `CLARVIS_HOOK_GATE` y `CLARVIS_HOOK_TIMEOUT_MS`. Los eventos de herramientas también reciben `CLARVIS_HOOK_TOOL` y, para una herramienta MCP con espacio de nombres, `CLARVIS_HOOK_TOOL_FULL_NAME`. Los hooks de plugins reciben además `PLUGIN_ROOT` y `PLUGIN_DATA`, junto con los alias compatibles `CODEX_PLUGIN_ROOT` y `CODEX_PLUGIN_DATA`. Esas rutas no contienen credenciales. Clarvis sigue filtrando las credenciales de proveedores y las variables que parecen secretos antes de iniciar un hook, pero un hook es un proceso normal del host, no un sandbox. ## Véase también {#see-also} - [Configuración](/es-ES/reference/configuration) - [Instalación y descargas](/es-ES/installation) - [Servidores MCP](/es-ES/guide/mcp-servers) - [Hooks](/es-ES/guide/hooks) - [Seguridad](/es-ES/operations/security) --- [HTML canónico](https://clarvis.dev/es-ES/reference/environment-variables) [Índice de documentación](https://clarvis.dev/es-ES/llms.txt)