Variables de entorno

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

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=<level> 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

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:

CLARVIS_TOKEN_CEILING=400000000 \
CLARVIS_DEFAULT_TOTAL_TOKEN_LIMIT=180000000 \
CLARVIS_ITERATION_CEILING=400 \
clarvis

Compactación

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

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

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

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.

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

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

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

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

• Configuración
• Instalación y descargas
• Servidores MCP
• Hooks
• Seguridad