Variáveis de ambiente

Configure caminhos, launchers, limites de runtime, diagnósticos, admissão de extensões, transporte de provedores, pool MCP e retenção sem esconder quais valores valem para todo o processo.

Esta referência cobre engine e kernel compartilhados, a TUI local e o instalador portátil. Variáveis de implantação do host Server formam uma superfície separada. As variáveis de ambiente se aplicam ao processo do Clarvis e a todos os kernels de workspace que ele cria. Elas são política do host, não configuração do workspace: um repositório não deve depender de alterá-las por .clarvis/settings.json.

Para variáveis booleanas, a ausência usa o padrão documentado. As strings false, 0, no, off e um valor vazio significam falso, sem diferenciar maiúsculas de minúsculas; qualquer outra string significa verdadeiro. Números e enums inválidos, ou um padrão acima do teto correspondente, interrompem a inicialização com Invalid environment configuration em vez de serem adivinhados.

Caminhos e TUI

Variável	Padrão	Efeito
CLARVIS_HOME	~/.clarvis	Substitui a raiz global de conteúdo e estado. Use o mesmo valor ao fazer backup, limpar ou diagnosticar essa instalação.
CLARVIS_WORKSPACE_ROOT	Diretório atual	Substitui a raiz do workspace para um embedding ou launcher. No uso comum, inicie clarvis no projeto pretendido.
CLARVIS_OWNER	Owner escolhido pelo host	Separa estado por owner quando um host atende mais de um operador lógico.
CLARVIS_DEFAULT_MODEL	Não definido	Último fallback provedor/modelo quando nem settings nem o agente selecionado fornecem um. Prefira /model no uso interativo normal.
CLARVIS_CODE_DEBUG	Desligado	Abre diagnósticos limitados da TUI. Um nível (error, warn, info ou debug) ativa e ajusta; outro valor verdadeiro usa debug.
CLARVIS_CODE_DEBUG_LEVEL	debug	Ajusta diagnósticos ativados por CLARVIS_CODE_DEBUG; --debug=<nível> tem precedência maior.
CLARVIS_TUI_RSS_LIMIT_MB	2048	Fusível de memória do processo interativo em MiB. 0 desativa; valores positivos têm piso de 512 MiB.

Tetos e padrões de execução

Tetos recusam um valor maior vindo de settings ou de um agente. Uma variável CLARVIS_DEFAULT_* fornece fallback somente quando um valor mais próximo no agente ou em settings.json não o substitui.

Variável	Padrão	Efeito
CLARVIS_TOKEN_CEILING	200000000	Maior limite de tokens aceito para uma execução.
CLARVIS_ITERATION_CEILING	200	Maior limite de iterações aceito para um agente.
CLARVIS_TIMEOUT_CEILING_MS	600000	Maior timeout de inatividade ou de chamada ao modelo aceito.
CLARVIS_ESCALATION_CEILING	20	Maior número de escalonamentos de orçamento aceito.
CLARVIS_RETRY_CEILING	10	Maior número de tentativas do provedor aceito.
CLARVIS_RETRY_AFTER_CEILING_MS	300000	Maior atraso de nova tentativa solicitado pelo provedor aceito.
CLARVIS_DEFAULT_TOTAL_TOKEN_LIMIT	160000000	Orçamento fallback de tokens de entrada mais saída acumulados em uma execução.
CLARVIS_DEFAULT_TIMEOUT_MS	300000	Timeout fallback de inatividade.
CLARVIS_DEFAULT_ON_EXCEED	escalate	Comportamento fallback no limite: stop ou escalate.
CLARVIS_DEFAULT_MAX_ESCALATIONS	5	Número fallback de escalonamentos de orçamento.
CLARVIS_DEFAULT_ELICIT_WAIT_MS	1800000	Espera máxima por uma resposta interativa.
CLARVIS_DEFAULT_ITERATION_LIMIT	200	Limite fallback de iterações do agente líder.
CLARVIS_DEFAULT_CONTEXT_WINDOW_TOKENS	128000	Janela de contexto fallback quando o catálogo não informa uma.
CLARVIS_DEFAULT_STAGNATION_THRESHOLD	3	Repetições sem progresso que acionam o guard de convergência.
CLARVIS_DEFAULT_STAGNATION_SOFT_THRESHOLD	2	Aviso antes do limite rígido de estagnação; 0 desativa essa camada.
CLARVIS_GUARD_MAX_ESCALATIONS	2	Exceções humanas após o guard rígido de convergência; 0 as desativa.
CLARVIS_DEFAULT_CALL_TIMEOUT_MS	180000	Janela de inatividade no streaming; limite absoluto até haver progresso observável.
CLARVIS_DEFAULT_REASONING_SUMMARY	off	Resumo de raciocínio fallback: off, auto ou detailed.
CLARVIS_DEFAULT_REASONING_EFFORT	Não definido	Esforço fallback: off, minimal, low, medium, high, xhigh ou max.
CLARVIS_DEFAULT_MAX_RETRIES	3	Novas tentativas fallback de uma chamada ao modelo.
CLARVIS_DEFAULT_MAX_RETRY_AFTER_MS	60000	Maior atraso fallback aceito entre tentativas.
CLARVIS_DEFAULT_FORCE_TOOL_ON_NUDGE	Ligado	Exige uma chamada de ferramenta depois que o loop avisa um agente parado.
CLARVIS_DEFAULT_PENDING_TASK_NUDGES	3	Avisos consecutivos sobre tarefas do plano antes de o gate de finalização parar de pedir.
CLARVIS_STREAM	Ligado	Ativa streaming onde o provedor oferece suporte.

Cada padrão associado a um teto precisa permanecer menor ou igual a ele. Por exemplo:

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

Compactação

Variável	Padrão	Efeito
CLARVIS_DEFAULT_COMPACTION_ENABLED	Ligado	Ativa a compactação automática do contexto.
CLARVIS_DEFAULT_COMPACTION_CONTEXT_FRACTION	0.8	Ocupação do contexto que permite compactar. Deve ser maior que 0 e no máximo 1.
CLARVIS_DEFAULT_COMPACTION_TARGET_FRACTION	0.5	Ocupação alvo após compactar. Deve ser maior que 0 e no máximo 1.
CLARVIS_DEFAULT_COMPACTION_MAX_RESULT_CHARS	Não definido	Máximo opcional de caracteres aceitos do resultado da compactação.
CLARVIS_DEFAULT_COMPACTION_PRESERVE_RECENT_TOKENS	Não definido	Cauda opcional de tokens recentes preservada fora do resumo.
CLARVIS_COMPACTION_LLM_TIMEOUT_MS	120000	Limite de tempo da chamada de compactação ao modelo.

Ferramentas, capacidades e concorrência

Variável	Padrão	Efeito
CLARVIS_AGENT_TOOLS_ENABLED	Ligado	Registra ferramentas de gerenciamento de agentes.
CLARVIS_AGENT_TOOLS_CONFINE	Ligado	Confina essas ferramentas à execução e à política do workspace atuais.
CLARVIS_AGENT_TOOLS_MAX_GRANT	edit	Teto do schema do host: none, read, edit ou exec. A TUI interativa usa exec antes de criar o kernel quando a variável não foi definida.
CLARVIS_SKILLS_ENABLED	Ligado	Registra descoberta de skills e load_skill.
CLARVIS_HOOKS_ENABLED	Ligado	Registra hooks de ciclo de vida.
CLARVIS_MEMORY_TOOL_CALL_LIMIT	12	Orçamento por execução para ferramentas de leitura da memória; escritas não entram nessa contagem.
CLARVIS_MEMORY_LOCK_WARN_MS	5000	Emite aviso quando o lock da árvore de memória permanece retido além deste tempo.
CLARVIS_CAPABILITY_SETUP_TIMEOUT_MS	5000	Limite por capacidade para ativação e seed; máximo rígido de 60 segundos.
CLARVIS_CAPABILITY_RUN_END_TIMEOUT_MS	2000	Limite por capacidade para finalizar depois que a resposta foi decidida.
CLARVIS_MAX_CONCURRENT_EXTENSION_CALLS	32	Teto do host para chamadas de extensão em primeiro plano.
CLARVIS_MAX_CONCURRENT_EXTENSION_RUN_END_CALLS	8	Teto do host para chamadas de extensão no fim da execução.
CLARVIS_MAX_CONCURRENT_EXTENSION_CALLS_PER_OPERATION	4	Máximo de chamadas de extensão concorrentes pertencentes a uma operação.
CLARVIS_MAX_PARALLEL_SUBAGENTS	4	Máximo de subagentes admitidos em paralelo.
CLARVIS_MAX_CONCURRENT_MODEL_CALLS	4	Teto do host para chamadas físicas concorrentes a modelos.
CLARVIS_MAX_QUEUED_MODEL_CALLS	8	Máximo de chamadas a modelos aguardando atrás desse teto.
CLARVIS_RUN_ABORT_SETTLE_MS	2000	Tolerância para uma execução cancelada ou expirada encerrar.
CLARVIS_MODEL_ABORT_SETTLE_MS	250	Tolerância menor para colocar em quarentena um transporte físico do provedor.

Saturação pula ou recusa novo trabalho limitado conforme a capacidade proprietária. Aumentar um número não altera grants de ferramentas, confiança do workspace nem política de sandbox.

Logs e transporte de provedores

Variável	Padrão	Efeito
CLARVIS_LOG_LEVEL	info	Piso global dos logs estruturados: debug, info, warn, error ou silent.
CLARVIS_LOG	Não definido	Overrides por componente separados por vírgula, como paths.lease=debug,mcp=debug,llm=warn. Componentes desconhecidos não têm efeito.
CLARVIS_LOG_AUDIT	Ligado	Mantém registros de autenticação e decisões do guard independentes do piso comum de logs.
CLARVIS_STREAM_DEBUG	Não definido	Caminho de arquivo JSONL para contadores de streaming de baixo nível. Deixe ausente fora de diagnósticos focados.
CLARVIS_PROVIDER_RETRY_BASE_MS	1000	Backoff inicial de nova tentativa do provedor.
CLARVIS_PROVIDER_RETRY_MAX_MS	30000	Backoff máximo de nova tentativa do provedor.
CLARVIS_PROVIDER_MAX_RESPONSE_BYTES	33554432	Maior resposta completa do provedor, 32 MiB.
CLARVIS_PROVIDER_MAX_SSE_EVENT_BYTES	4194304	Maior evento SSE do provedor, 4 MiB.

Use --debug ou /debug no fluxo normal de diagnósticos limitados. Variáveis de log são para operadores do host e não substituem redação nem o canal de auditoria.

Limites MCP do host

Campos por servidor, como startup_timeout_sec, tool_timeout_sec, env_vars, bearer_token_env_var e listas de ferramentas permitidas ou negadas, pertencem a mcpServers, não a esta tabela. Consulte Servidores MCP.

Variável	Padrão	Efeito
CLARVIS_MCP_SERVER_STDERR	log	Trata stderr do servidor stdio como off, log estruturado ou inherit bruto. Evite inherit na TUI.
CLARVIS_MCP_SERVER_STDERR_MAX_BYTES	65536	Teto de stderr encaminhado por conexão.
CLARVIS_MCP_CONNECT_TIMEOUT_MS	10000	Timeout padrão de conexão e inicialização.
CLARVIS_MCP_TOOL_CALL_TIMEOUT_MS	600000	Timeout padrão de chamada de ferramenta MCP.
CLARVIS_MCP_POOL_IDLE_TTL_MS	60000	Tempo ocioso antes de fechar uma conexão do pool.
CLARVIS_MCP_STDIO_MAX_FRAME_BYTES	16777216	Maior frame do protocolo stdio, 16 MiB.
CLARVIS_MCP_HTTP_MAX_RESPONSE_BYTES	16777216	Maior resposta remota, 16 MiB.
CLARVIS_MCP_HTTP_MAX_SSE_EVENT_BYTES	4194304	Maior evento SSE remoto, 4 MiB.
CLARVIS_MCP_MAX_SERVERS_PER_RUN	16	Teto de servidores por execução; não pode superar CLARVIS_MCP_MAX_CONNECTIONS.
CLARVIS_MCP_MAX_CONNECTIONS	32	Teto de conexões abertas no host.
CLARVIS_MCP_MAX_PARALLEL_CONNECTS	4	Teto de tentativas de conexão simultâneas.
CLARVIS_MCP_MAX_IDLE_CONNECTIONS	8	Conexões ociosas mantidas no pool.
CLARVIS_MCP_TIMEOUT_STREAK_THRESHOLD	3	Timeouts consecutivos antes de considerar uma conexão não saudável.
CLARVIS_MCP_HEALTH_PING_INTERVAL_MS	30000	Intervalo de health ping; 0 desativa os pings periódicos.
CLARVIS_MCP_RESOURCES	Ligado	Suporte global a ferramentas de resources. Um servidor ainda pode usar resources: false.
CLARVIS_MCP_POOL_SHARING	owner	Isolamento do pool: owner ou workspace.

Retenção de traces

Variável	Padrão	Efeito
CLARVIS_TRACE_TTL_DAYS	30	Idade em que traces se tornam elegíveis para limpeza; 0 desabilita a limpeza de traces.
CLARVIS_TRACE_CLEANUP_INTERVAL_MS	3600000	Frequência da limpeza em segundo plano.
CLARVIS_TRACE_CLEANUP_BATCH_SIZE	1000	Máximo de registros processados em um lote de limpeza.

Variáveis do instalador portátil

Estas variáveis configuram uma instalação gerenciada. Reutilize os mesmos overrides de caminho ao desinstalar.

Variável	Plataforma	Padrão	Efeito
CLARVIS_INSTALL_ROOT	Todas	POSIX: ${XDG_DATA_HOME:-$HOME/.local/share}/clarvis; Windows: %LOCALAPPDATA%\Clarvis	Versões gerenciadas, marcador de ativação e metadados. O launcher gerado carrega a raiz escolhida.
CLARVIS_BIN_DIR	POSIX	${XDG_BIN_HOME:-$HOME/.local/bin}	Diretório que contém o launcher gerenciado clarvis.
CLARVIS_SKIP_PATH	Windows	Desligado	Use 1 para impedir o instalador ou desinstalador de alterar o PATH do usuário.

O instalador na árvore de código também contém overrides de engenharia de release para smokes com artefatos locais. Eles não são configuração comum de usuário e foram omitidos intencionalmente; use o instalador imutável da tag publicada exata.

Variáveis entregues a hooks e plugins

Variáveis de hook são saídas do Clarvis, não configuração de inicialização. Cada hook recebe CLARVIS_HOOK_PROTOCOL, CLARVIS_HOOK_EVENT, CLARVIS_HOOK_GATE e CLARVIS_HOOK_TIMEOUT_MS; eventos de ferramenta também recebem CLARVIS_HOOK_TOOL e, para uma ferramenta MCP com namespace, CLARVIS_HOOK_TOOL_FULL_NAME. Um hook de plugin recebe ainda PLUGIN_ROOT e PLUGIN_DATA, além dos aliases de compatibilidade CODEX_PLUGIN_ROOT e CODEX_PLUGIN_DATA.

Esses caminhos não carregam credenciais. O Clarvis ainda filtra credenciais de provedores e variáveis com aparência de segredo antes de iniciar um hook, mas um hook é um processo comum do host, não um sandbox.

Veja também

• Configuração
• Instalação e downloads
• Servidores MCP
• Hooks
• Segurança