# 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=` 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: ```bash 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](/pt-BR/guide/mcp-servers). | 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](/pt-BR/reference/configuration) - [Instalação e downloads](/pt-BR/installation) - [Servidores MCP](/pt-BR/guide/mcp-servers) - [Hooks](/pt-BR/guide/hooks) - [Segurança](/pt-BR/operations/security) --- [HTML canônico](https://clarvis.dev/pt-BR/reference/environment-variables) [Índice da documentação](https://clarvis.dev/pt-BR/llms.txt)