> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Variáveis de Ambiente
> Referência completa de todas as variáveis de ambiente suportadas pelo ChatCLI.
Esta página lista **todas** as variáveis de ambiente que o ChatCLI reconhece. Configure-as no seu arquivo `.env` ou via `export` no shell.
## Geral
| Variável | Descrição | Padrão |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `LLM_PROVIDER` | Provedor ativo: `OPENAI`, `OPENAI_ASSISTANT`, `CLAUDEAI`, `BEDROCK`, `GOOGLEAI`, `XAI`, `ZAI`, `MINIMAX`, `MOONSHOT`, `OPENROUTER`, `STACKSPOT`, `OLLAMA`, `COPILOT`, `GITHUB_MODELS` | Auto-detectado |
| `CHATCLI_DOTENV` | Caminho customizado para o arquivo `.env` | `.env` |
| `CHATCLI_LANG` | Forçar idioma da interface (`pt-BR`, `en`) | Auto-detectado |
| `CHATCLI_IGNORE` | Caminho para arquivo de regras `.chatignore` | Auto-detectado |
| `CHATCLI_THEME` | Tema de cores da interface (chat, cards, markdown, spinners). 11 temas: `dark`, `light` + 9 da comunidade (dracula, nord, tokyo-night, solarized-dark/light, gruvbox, catppuccin-mocha, monokai, one-dark). Troca em runtime via `/config ui theme`. Veja o [Sistema de Tema](/pt/features/ui-theme). | `dark` |
| `LOG_LEVEL` | Nível de log: `debug`, `info`, `warn`, `error` | `info` |
| `LOG_FILE` | Caminho do arquivo de log | `~/.chatcli/app.log` |
| `LOG_MAX_SIZE` | Tamanho máximo do log antes da rotação | `100MB` |
| `CHATCLI_ENV` | Modo de logging: `dev` (console colorido + arquivo), `prod` (só arquivo JSON). Compatível com legado `ENV`. | `prod` |
| `MAX_RETRIES` | Tentativas máximas para chamadas de API | `5` |
| `INITIAL_BACKOFF` | Tempo inicial entre tentativas (segundos) | `3` |
| `HISTORY_FILE` | Caminho para o arquivo de histórico (suporta `~`) | `.chatcli_history` |
| `HISTORY_MAX_SIZE` | Tamanho máximo do histórico antes da rotação | `100MB` |
***
## Provedores LLM
### OpenAI
| Variável | Descrição | Padrão |
| ------------------------ | ------------------------------------ | --------- |
| `OPENAI_API_KEY` | Chave de API | — |
| `OPENAI_MODEL` | Modelo a usar | `gpt-5.4` |
| `OPENAI_ASSISTANT_MODEL` | Modelo para assistente (modo agente) | `gpt-4o` |
| `OPENAI_MAX_TOKENS` | Limite de tokens na resposta | `60000` |
| `OPENAI_USE_RESPONSES` | Usar Responses API (ex: para gpt-5) | `false` |
### Anthropic (Claude)
| Variável | Descrição | Padrão |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `ANTHROPIC_API_KEY` | Chave de API | — |
| `ANTHROPIC_MODEL` | Modelo a usar (ex.: `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-4-6`) | `claude-sonnet-4-6` |
| `ANTHROPIC_MAX_TOKENS` | Limite de tokens na resposta | `20000` |
| `ANTHROPIC_API_VERSION` | Versão da API | `2023-06-01` |
| `ANTHROPIC_SPEED` | Defina `fast` para opt-in no **fast mode do Opus 4.8** (research preview, \~2.5× output tokens/seg com pricing premium). Ignorado silenciosamente em modelos sem a capability `fast_mode` no catálogo — seguro deixar fixo ao trocar de modelo. | — |
| `ANTHROPIC_1MTOKENS_SONNET` | Ativa o beta header de 1M de contexto em requisições OAuth para Sonnet 4.x. Opus 4.7/4.8 já têm 1M nativo e ignoram esta flag. | `false` |
### AWS Bedrock (catálogo completo)
Provedor `BEDROCK` — invoca **todo o catálogo Bedrock** (Anthropic, OpenAI, Llama, Nova, Mistral, Cohere, AI21, DeepSeek, Moonshot Kimi (também disponível diretamente via `MOONSHOT`), MiniMax, Qwen, Z.AI/GLM, Gemma, Nemotron, TwelveLabs e qualquer provider que a AWS adicionar) usando a credentials chain do SDK (env vars, `~/.aws/credentials`, SSO via `~/.aws/config`, IAM role). A ativação exige credenciais reais — a mera existência de `~/.aws/config` com apenas region/output não ativa o Bedrock.
| Variável | Descrição | Padrão |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `BEDROCK_PROVIDER` | Override do schema: `anthropic` / `claude`, `openai` / `gpt`, `converse` / `auto`. Sobrepõe auto-detecção pelo prefixo do model id. | auto-detect |
| `BEDROCK_TEMPERATURE` | Temperature (usada por OpenAI e Converse paths) | — |
| `BEDROCK_TOP_P` | Top-p sampling (usado pelo Converse path) | — |
| `BEDROCK_REGION` | Região AWS (precedência sobre `AWS_REGION`) | — |
| `AWS_REGION` | Região AWS (fallback) | — |
| `AWS_PROFILE` | Profile em `~/.aws/credentials` ou `~/.aws/config` (SSO, assume-role, credential\_process). Pode ser definido no `.env`. | — |
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` | Credenciais estáticas | — |
| `AWS_CA_BUNDLE` | Bundle PEM lido nativamente pelo SDK | — |
| `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` | Override do endpoint Bedrock Runtime (VPC endpoints) | — |
| `AWS_ENDPOINT_URL_BEDROCK` | Override do endpoint Bedrock (control plane) | — |
| `AWS_EC2_METADATA_DISABLED` | `true` desabilita IMDS (169.254.169.254) explicitamente | — |
| `CHATCLI_BEDROCK_ENABLE_IMDS` | `1`/`true` força habilitar o probe IMDS em máquinas não-EC2 | `false` |
| `BEDROCK_MAX_TOKENS` | Limite de tokens na resposta | Do catálogo |
| `BEDROCK_ANTHROPIC_ENDPOINT` | Força o wire dos modelos Claude: `mantle` (endpoint Messages) ou `invoke` (InvokeModel legado). Sem a var, o roteamento é por catálogo — Sonnet 5 vai pro Messages automaticamente. | por catálogo |
| `BEDROCK_MANTLE_BASE_URL` | Override do endpoint Messages (`bedrock-mantle.{região}.api.aws`) pra VPC endpoints/proxies | — |
| `AWS_BEARER_TOKEN_BEDROCK` | Bearer token de curta duração (`aws-bedrock-token-generator`) — enviado no header `x-api-key` do endpoint Messages, sem SigV4 | — |
| `CHATCLI_BEDROCK_CA_BUNDLE` | Bundle PEM específico do Bedrock. Precede `AWS_CA_BUNDLE` e o global `CHATCLI_CA_BUNDLE` (que serve de fallback). Veja [Confiança TLS Global](#confian%C3%A7a-tls-global-proxy-corporativo). | — |
| `CHATCLI_BEDROCK_INSECURE_SKIP_VERIFY` | `true` desabilita verificação TLS (inseguro, só troubleshooting). Precede o global `CHATCLI_TLS_INSECURE_SKIP_VERIFY` (que serve de fallback). | `false` |
Modelos modernos no Bedrock (Claude 3.7+/4.x/4.5/4.6/4.7 e equivalentes em outros providers) exigem **inference profile IDs** (com prefixo `global.`, `us.`, `eu.` ou `apac.`). O `/switch --model` filtra automaticamente IDs base que não suportam `ON_DEMAND`, então só aparecem os IDs invocáveis direto + os profiles. Veja [AWS Bedrock](/pt/features/bedrock) para detalhes.
### Google AI (Gemini)
| Variável | Descrição | Padrão |
| --------------------- | ---------------------------- | ------------------ |
| `GOOGLEAI_API_KEY` | Chave de API | — |
| `GOOGLEAI_MODEL` | Modelo a usar | `gemini-2.5-flash` |
| `GOOGLEAI_MAX_TOKENS` | Limite de tokens na resposta | `50000` |
### xAI (Grok)
| Variável | Descrição | Padrão |
| ---------------- | ---------------------------- | ---------- |
| `XAI_API_KEY` | Chave de API | — |
| `XAI_MODEL` | Modelo a usar | `grok-4-1` |
| `XAI_MAX_TOKENS` | Limite de tokens na resposta | `50000` |
### Ollama (Modelos Locais)
| Variável | Descrição | Padrão |
| ------------------------ | ----------------------------------------------------- | ------------------------ |
| `OLLAMA_ENABLED` | Habilitar API do Ollama (obrigatório) | `false` |
| `OLLAMA_BASE_URL` | URL do servidor Ollama | `http://localhost:11434` |
| `OLLAMA_MODEL` | Modelo a usar | — |
| `OLLAMA_MAX_TOKENS` | Limite de tokens na resposta | `5000` |
| `OLLAMA_FILTER_THINKING` | Filtra raciocínio intermediário de modelos como Qwen3 | `true` |
Para o modo Agente funcionar bem com alguns modelos Ollama que "pensam em voz alta" (Qwen3, Llama3...), mantenha `OLLAMA_FILTER_THINKING=true`.
### ZAI (Zhipu AI)
| Variável | Descrição | Padrão |
| ---------------- | --------------------------------------------------- | ------- |
| `ZAI_API_KEY` | Chave de API (Bearer token ou `id.secret` para JWT) | — |
| `ZAI_MODEL` | Modelo a usar | `glm-5` |
| `ZAI_MAX_TOKENS` | Limite de tokens na resposta | `50000` |
Chaves no formato `id.secret` ativam automaticamente a **rotação de tokens JWT** (HMAC-SHA256). Os tokens são cacheados por 30 minutos com margem de segurança de 5 minutos antes da regeneração. Chaves sem "." continuam funcionando como Bearer tokens tradicionais. Nenhuma configuração adicional é necessária.
### MiniMax
| Variável | Descrição | Padrão |
| -------------------- | ----------------------------------------------------------------------------------- | -------------- |
| `MINIMAX_API_KEY` | Chave de API (Bearer token) | — |
| `MINIMAX_MODEL` | Modelo a usar (case-sensitive!) | `MiniMax-M2.7` |
| `MINIMAX_MAX_TOKENS` | Limite de tokens na resposta | `50000` |
| `MINIMAX_API_COMPAT` | Modo de compatibilidade da API: `anthropic` para usar o endpoint Anthropic Messages | — |
Defina `MINIMAX_API_COMPAT=anthropic` para usar o endpoint compatível com a API Anthropic Messages (`https://api.minimax.io/anthropic/v1/messages`). O header `anthropic-version: 2023-06-01` é adicionado automaticamente. A autenticação Bearer token permanece a mesma. O tool use nativo é desabilitado neste modo (fallback para XML).
### Moonshot (Kimi)
| Variável | Descrição | Padrão |
| --------------------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| `MOONSHOT_API_KEY` | Chave de API (Bearer token) | — |
| `MOONSHOT_MODEL` | Modelo a usar (`kimi-k2.6`, `kimi-k2.5`, `kimi-latest`, `moonshot-v1-*`) | `kimi-k2.6` |
| `MOONSHOT_MAX_TOKENS` | Limite de tokens na resposta | catálogo (131072 para K2.6) |
| `MOONSHOT_THINKING` | Modo de raciocínio: `enabled`, `disabled`, `auto` | `auto` |
| `MOONSHOT_API_URL` | Endpoint customizado | `https://api.moonshot.ai/v1/chat/completions` |
`MOONSHOT_THINKING=disabled` força o modo **Instant** (resposta direta, mais barata) mesmo em modelos com capability `thinking`. `enabled` força o reasoning explícito. `auto` (padrão) deixa o modelo escolher. Modelos sem capability `thinking` ignoram a flag — não há cobrança extra acidental.
### OpenRouter
| Variável | Descrição | Padrão |
| ---------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------- |
| `OPENROUTER_API_KEY` | Chave de API do OpenRouter (obrigatória) | — |
| `OPENROUTER_API_URL` | URL customizada da API | `https://openrouter.ai/api/v1/chat/completions` |
| `OPENROUTER_MAX_TOKENS` | Limite de tokens na resposta | — |
| `OPENROUTER_FALLBACK_MODELS` | Lista de modelos de fallback separados por vírgula (roteamento nativo do OpenRouter) | — |
| `OPENROUTER_PROVIDER_ORDER` | Ordem de preferência de provedores separados por vírgula (ex: `Anthropic,Google`) | — |
| `OPENROUTER_TRANSFORMS` | Transformações de mensagem (ex: `middle-out` para overflow de contexto) | — |
| `OPENROUTER_HTTP_REFERER` | Header de atribuição HTTP Referer | — |
| `OPENROUTER_APP_TITLE` | Header de atribuição com o título da aplicação | — |
| `OPENROUTER_TOOLS` | Array JSON de ferramentas para injeção | — |
O OpenRouter é um **gateway multi-provedor** que dá acesso a 200+ modelos com uma única API key. Os modelos usam o formato `provedor/nome-do-modelo` (ex: `openai/gpt-4o`, `anthropic/claude-sonnet-4`). Configure `OPENROUTER_FALLBACK_MODELS` para aproveitar o roteamento de fallback nativo do OpenRouter, complementar ao sistema de fallback do ChatCLI.
### GitHub Copilot
| Variável | Descrição | Padrão |
| --------------------------- | ---------------------------- | ------ |
| `GITHUB_COPILOT_TOKEN` | Token de autenticação | — |
| `COPILOT_MODEL` | Modelo a usar | — |
| `COPILOT_MAX_TOKENS` | Limite de tokens na resposta | — |
| `COPILOT_API_BASE_URL` | URL base da API | — |
| `CHATCLI_COPILOT_CLIENT_ID` | Client ID customizado | — |
### StackSpot
| Variável | Descrição | Padrão |
| -------------------- | ------------ | ------ |
| `CLIENT_ID` | Client ID | — |
| `CLIENT_KEY` | Client Key | — |
| `STACKSPOT_REALM` | Realm/Tenant | — |
| `STACKSPOT_AGENT_ID` | Agent ID | — |
A API de agente da StackSpot decide o limite de output **server-side** (ignora `max_tokens` no payload). O catálogo do ChatCLI assume **128K** de janela de contexto para agentes StackSpot — antes, o fallback genérico de 50K fazia o auto-compact disparar em quase todo turno. Se o modelo de fundação do seu agente tiver janela diferente, ajuste com [`CHATCLI_CONTEXT_WINDOW`](#compacta%C3%A7%C3%A3o-de-hist%C3%B3rico-e-recupera%C3%A7%C3%A3o-de-payload).
***
## Modo Agente
| Variável | Descrição | Padrão |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `CHATCLI_AGENT_CMD_TIMEOUT` | Timeout por comando executado (duração Go: `30s`, `2m`, `10m`) | `10m` |
| `CHATCLI_AGENT_DENYLIST` | Regex extras para bloquear comandos (separados por `;`) | — |
| `CHATCLI_AGENT_ALLOW_SUDO` | Permitir `sudo` sem bloqueio automático | `false` |
| `CHATCLI_AGENT_INLINE_CODE_STRICT` | Em chamadas `python -c` / `node -e` / `perl -e` / `ruby -e` / `php -r` / `lua -e`, eleva qualquer código inline **não comprovadamente seguro** a perigoso (modo conservador). Default: classifier deixa passar one-liners read-only (`print(1)`, `import sys; print(sys.version)`) e bloqueia apenas padrões com `os.system`, `subprocess`, `socket`, `eval`, `exec`, file writes, network. | `false` |
| `CHATCLI_AGENT_PLUGIN_MAX_TURNS` | Máximo de turnos do agente | `50` |
| `CHATCLI_AGENT_PLUGIN_TIMEOUT` | Timeout total do plugin do agente | `15m` |
***
## Multi-Agent (Orquestração Paralela)
| Variável | Descrição | Padrão |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `CHATCLI_AGENT_PARALLEL_MODE` | Ativar orquestração paralela multi-agent | `true` |
| `CHATCLI_AGENT_MAX_WORKERS` | Máximo de workers (goroutines) simultâneos | `4` |
| `CHATCLI_AGENT_WORKER_MAX_TURNS` | Máximo de turnos por worker | `10` |
| `CHATCLI_AGENT_WORKER_TIMEOUT` | Timeout por worker individual | `5m` |
| `CHATCLI_AGENT_PARALLEL_TOOLS` | Ativa execução paralela de tools concurrency-safe **dentro de um único agente** (read-only operations como `@websearch`, `@webfetch`, `@coder read/search/tree` em um mesmo turn). Distinto de `CHATCLI_AGENT_PARALLEL_MODE`, que controla múltiplos agentes em paralelo. Off por default enquanto o feature está em rollout. | `false` |
| `CHATCLI_AGENT_MAX_TOOL_CONCURRENCY` | Cap de fan-out simultâneo para o batch paralelo de tools dentro de um agente. Operadores que processam muitos `@webfetch` em paralelo podem subir; conservadores podem reduzir. | `10` |
***
## Mixture-of-Agents (MoA)
Ensemble onde **vários modelos propõem** uma resposta em paralelo e um **agregador** sintetiza a melhor. É distinto da orquestração paralela acima (que despacha *agents* especialistas): aqui o eixo é a **diversidade de modelos/provedores**. Acionado pelo comando `/moa`. Cada participante — proponentes e agregador — recebe o mesmo briefing de um turno de chat (contextos anexados, memória do workspace, skills) e tools read-only: knowledge, recall de CCR e recall da memória de longo prazo. Ver [Mixture-of-Agents](/pt/features/mixture-of-agents).
| Variável | Descrição | Padrão |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `CHATCLI_MOA_MODELS` | Propositores do ensemble, em CSV `provider:model` (ex.: `openai:gpt-5,claudeai:claude-opus-4-8,googleai:gemini-2.5-pro`). Opcional: sem isto, `/moa` e `@moa` usam os provedores configurados (cap 4). | — |
| `CHATCLI_MOA_AGGREGATOR` | Modelo que sintetiza as propostas, no formato `provider:model`. Se omitido, usa o provedor/modelo ativo da sessão. | Provedor ativo |
***
## Eficiência de Tokens
Controles para as otimizações de consumo de tokens (prompt caching estruturado, detector de estagnação, smart routing, auto-save de webfetch, microcompactação). Ver [Eficiência de Tokens](/pt/features/token-efficiency) para detalhes.
### Detector de estagnação (early-exit)
| Variável | Descrição | Padrão |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------- |
| `CHATCLI_AGENT_EARLY_EXIT` | Liga/desliga o detector de `tool_calls` repetidas no loop ReAct. Aceita `0`/`false`/`off`/`no` para desativar. | `1` (on) |
| `CHATCLI_AGENT_EARLY_EXIT_TURNS` | Quantos turnos consecutivos com a mesma batch de `tool_calls` acionam o break. Clamp \[2, 10]. | `3` |
### Guarda de falhas de tool (toolguard)
Guarda **advisory** (não aborta) que detecta uma mesma ferramenta falhando repetidamente dentro do loop do agente e injeta um aviso para o modelo mudar de abordagem em vez de insistir no mesmo erro.
| Variável | Descrição | Padrão |
| ------------------------- | ------------------------------------------------------------------------------------- | -------- |
| `CHATCLI_AGENT_TOOLGUARD` | Liga/desliga o guarda de falhas repetidas de tool. Aceita `0`/`false` para desativar. | `1` (on) |
### Smart routing chat ↔ agent
| Variável | Descrição | Padrão |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `CHATCLI_AGENT_SMART_ROUTE` | Modo do classificador de queries triviais. `off` (desliga), `hint` (só avisa — default), `auto` (auto-redireciona trivial → chat mode). Sinônimos aceitos: `0`/`false`, `1`/`on`/`true`, `redirect`/`2`. | `hint` |
### WebFetch auto-save
| Variável | Descrição | Padrão |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| `CHATCLI_WEBFETCH_AUTOSAVE_BYTES` | Threshold em bytes. Bodies de `@webfetch` maiores que isso SEM filtro/range são auto-salvos no scratch dir e retornam apenas um preview. | `10000` |
| `CHATCLI_WEBFETCH_RENDER` | Renderização headless de páginas JS no `@webfetch`: `auto` (heurística detecta shell de SPA), `always`, `never`. Ver [Web Tools](/pt/features/web-tools#renderizacao-de-paginas-javascript-spa). | `auto` |
| `CHATCLI_WEBFETCH_RENDER_TIMEOUT` | Timeout do render headless, em segundos. | `25` |
| `CHATCLI_WEBFETCH_RENDER_BROWSER` | Caminho **absoluto** para um binário Chromium-based específico (Chrome/Chromium/Edge/Brave são auto-detectados sem isso). | *(auto-detect)* |
| `CHATCLI_WEBFETCH_RENDER_AUTOPROVISION` | Permite o download único de um Chromium pinado (\~150 MB) quando nenhum browser é encontrado. | `false` |
### Microcompactação de tool results
Aplicada ao histórico da sessão para comprimir resultados antigos de ferramentas. Ver também [Tool Result Management](/pt/features/tool-result-management).
| Variável | Descrição | Padrão |
| -------------------------------------- | -------------------------------------------------------------------- | ------ |
| `CHATCLI_MICROCOMPACT_TRUNCATE_TURNS` | Após quantos turnos os tool results antigos viram head+tail preview. | `2` |
| `CHATCLI_MICROCOMPACT_SUMMARIZE_TURNS` | Após quantos turnos os tool results viram uma linha de resumo. | `4` |
| `CHATCLI_MICROCOMPACT_HEAD_CHARS` | Tamanho do head mantido na truncagem. | `2000` |
| `CHATCLI_MICROCOMPACT_TAIL_CHARS` | Tamanho da cauda mantida na truncagem. | `500` |
| `CHATCLI_MICROCOMPACT_MIN_CONTENT` | Tamanho mínimo de tool result para virar candidato à compactação. | `3000` |
Para sessões de chat/lookup onde economia de tokens importa mais que recall de longo prazo, aperte os knobs:
```bash theme={"system"}
export CHATCLI_MICROCOMPACT_TRUNCATE_TURNS=1
export CHATCLI_MICROCOMPACT_SUMMARIZE_TURNS=3
export CHATCLI_MICROCOMPACT_HEAD_CHARS=1200
export CHATCLI_MICROCOMPACT_TAIL_CHARS=300
export CHATCLI_MICROCOMPACT_MIN_CONTENT=2000
```
### Compressão de contexto (CCR)
Compressão content-aware e reversível de saída de tools, logs, diffs, JSON e prosa. Ver [Compressão de Contexto](/pt/features/context-compression).
| Variável | Descrição | Padrão |
| -------------------------------- | ------------------------------------------------------------------------ | ---------------- |
| `CHATCLI_COMPRESSION` | Modo: `off`, `lossless`, `lossy-with-ccr`. | `lossy-with-ccr` |
| `CHATCLI_COMPRESSION_PROFILE` | Agressividade dos compressores: `conservative`, `default`, `aggressive`. | `default` |
| `CHATCLI_COMPRESSION_THRESHOLD` | Bytes abaixo dos quais a saída é byte-idêntica (passthrough). | `4000` |
| `CHATCLI_COMPRESSION_CCR_DIR` | Diretório do store CCR (originais recuperáveis via `@recall`). | `~/.chatcli/ccr` |
| `CHATCLI_COMPRESSION_CCR_MAX_MB` | Cap de tamanho do store em MiB (`0` = sem cap). | `256` |
| `CHATCLI_COMPRESSION_CCR_TTL` | TTL das entradas (duração Go; `0` = sem TTL). | `168h` |
### Redução de tokens de saída
| Variável | Descrição | Padrão |
| ------------------------------- | ----------------------------------------------------------------------------------- | --------- |
| `CHATCLI_OUTPUT_VERBOSITY` | Verbosity steering: `full`, `concise`, `minimal`. | `concise` |
| `CHATCLI_OUTPUT_EFFORT_ROUTING` | Roteamento de esforço por complexidade (baixa esforço em prompts triviais; opt-in). | `off` |
***
## Harness/Pipeline de Qualidade (7 Padrões)
Variáveis do harness/pipeline de qualidade que implementa os sete padrões de agente LLM. Ver [overview completo](/pt/features/quality/overview) e [configuração detalhada](/pt/features/quality/configuration).
### Master switch
| Variável | Descrição | Padrão |
| ------------------------- | ---------------------------------------------------------------------------------------- | ------ |
| `CHATCLI_QUALITY_ENABLED` | Master switch do pipeline. `false` desativa tudo (fall-back para `agent.Execute` direto) | `true` |
### Self-Refine (#5)
| Variável | Descrição | Padrão |
| ----------------------------------- | -------------------------------------------------------- | --------------------------------- |
| `CHATCLI_QUALITY_REFINE_ENABLED` | Ativar RefineHook após cada worker | `false` |
| `CHATCLI_QUALITY_REFINE_MAX_PASSES` | Máximo de passes de critique-rewrite | `1` |
| `CHATCLI_QUALITY_REFINE_MIN_BYTES` | Não refina outputs menores que N bytes | `200` |
| `CHATCLI_QUALITY_REFINE_EPSILON` | Threshold de convergência do fallback char em caracteres | `50` |
| `CHATCLI_QUALITY_REFINE_EXCLUDE` | CSV de agents que não são refinados | `formatter,deps,refiner,verifier` |
#### Cascade de convergência semântica (char → Jaccard → embedding)
| Variável | Descrição | Padrão |
| ------------------------------------------------------ | -------------------------------------------------------- | ------- |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_ENABLED` | Liga o cascade; `false` = só heurístico char-level | `true` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_EMBEDDING` | Inclui embedding scorer (exige `CHATCLI_EMBED_PROVIDER`) | `false` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_STRICT` | Strict mode: recusa convergência sem embedding | `false` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_CHAR_HIGH` | Sim char ≥ X → short-circuit CONVERGIU | `0.99` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_CHAR_LOW` | Sim char \< X → short-circuit DIVERGIU | `0.3` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_JACCARD_HIGH` | Sim Jaccard ≥ X + alta confiança → CONVERGIU | `0.95` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_EMBEDDING_SIM` | Threshold final do embedding cosine | `0.92` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_CACHE_SIZE` | Entries do LRU cache de embeddings | `256` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_CACHE_TTL_MIN` | TTL do cache (minutos) | `5` |
| `CHATCLI_QUALITY_REFINE_CONVERGENCE_BREAKER_THRESHOLD` | Falhas consecutivas do embedder antes do breaker abrir | `3` |
### Chain-of-Verification (#6)
| Variável | Descrição | Padrão |
| -------------------------------------- | -------------------------------------------- | --------------------------------------- |
| `CHATCLI_QUALITY_VERIFY_ENABLED` | Ativar VerifyHook após cada worker | `false` |
| `CHATCLI_QUALITY_VERIFY_NUM_QUESTIONS` | Número de perguntas de verificação | `3` |
| `CHATCLI_QUALITY_VERIFY_REWRITE` | Reescrever output quando houver discrepância | `true` |
| `CHATCLI_QUALITY_VERIFY_EXCLUDE` | CSV de agents que não são verificados | `formatter,deps,shell,refiner,verifier` |
### Reflexion (#3)
| Variável | Descrição | Padrão |
| -------------------------------------------- | ---------------------------------------- | ------- |
| `CHATCLI_QUALITY_REFLEXION_ENABLED` | Master switch do ReflexionHook | `true` |
| `CHATCLI_QUALITY_REFLEXION_ON_ERROR` | Disparar em erro de worker | `true` |
| `CHATCLI_QUALITY_REFLEXION_ON_HALLUCINATION` | Disparar quando CoVe flagga discrepância | `true` |
| `CHATCLI_QUALITY_REFLEXION_ON_LOW_QUALITY` | Disparar quando refine dá nota baixa | `false` |
| `CHATCLI_QUALITY_REFLEXION_PERSIST` | Persistir lessons em memory.Fact | `true` |
#### Fila durável (WAL + worker pool + DLQ)
Quando ligada, triggers de reflexion passam por uma fila persistente — lições sobrevivem a crash via WAL replay no próximo boot.
| Variável | Descrição | Padrão |
| ----------------------------------------------- | ------------------------------------------------------------------------ | ------- |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_ENABLED` | Master switch da fila; `false` volta ao modo legado (detached goroutine) | `true` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_WORKERS` | Tamanho do worker pool | `2` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_CAPACITY` | Profundidade máxima in-memory antes de overflow | `1000` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_DROP_OLDEST` | Overflow: `true` drop oldest; `false` block | `false` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_BLOCK_TIMEOUT` | Quanto Enqueue espera com fila cheia (duração Go) | `5s` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_MAX_ATTEMPTS` | Retries totais antes de mover pra DLQ | `5` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_INITIAL_DELAY` | Primeiro delay de retry | `1s` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_MAX_DELAY` | Cap no retry exponencial | `5m` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_JITTER` | Jitter fracionário (\[0, 0.5]) | `0.2` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_JOB_TIMEOUT` | Timeout por chamada ao processor (LLM + persist) | `2m` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_STALE_AFTER` | Records mais velhos são descartados no replay | `168h` |
| `CHATCLI_QUALITY_REFLEXION_QUEUE_BASE_DIR` | Raiz de `wal/` e `dlq/` (override do default em `.chatcli/reflexion`) | — |
### Plan-and-Solve / ReWOO (#2)
| Variável | Descrição | Padrão |
| -------------------------------------- | ------------------------------------------------ | ------ |
| `CHATCLI_QUALITY_PLAN_FIRST_MODE` | `off\|auto\|always` — quando disparar Plan-First | `auto` |
| `CHATCLI_QUALITY_PLAN_FIRST_THRESHOLD` | Score mínimo (0-10) para `auto` disparar | `6` |
### RAG + HyDE (#4)
| Variável | Descrição | Padrão |
| ----------------------------------- | ---------------------------------------------------- | ------- |
| `CHATCLI_QUALITY_HYDE_ENABLED` | Ativar phase 3a (hypothesis-based keyword expansion) | `false` |
| `CHATCLI_QUALITY_HYDE_USE_VECTORS` | Ativar phase 3b (busca vetorial por cosseno) | `false` |
| `CHATCLI_QUALITY_HYDE_NUM_KEYWORDS` | Cap de keywords extraídas da hipótese | `5` |
### Embedding Providers (usado por HyDE 3b)
| Variável | Descrição | Padrão |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `CHATCLI_EMBED_PROVIDER` | `voyage` / `openai` / `bedrock` / `null` | `null` |
| `CHATCLI_EMBED_MODEL` | Modelo de embedding. Defaults por provider: Voyage `voyage-3`; OpenAI `text-embedding-3-small`; Bedrock `amazon.titan-embed-text-v2:0`. | provider default |
| `CHATCLI_EMBED_DIMENSIONS` | OpenAI: trunca via Matryoshka. Bedrock Titan v2: aceita 256 / 512 / 1024 (rejeita outros). Bedrock Titan v1 / Cohere v3: dimensão fixa, ignorada. | nativa do modelo |
| `VOYAGE_API_KEY` | Necessária para `provider=voyage` | — |
| `OPENAI_API_KEY` | Necessária para `provider=openai` (compartilhada com o chat) | — |
| `BEDROCK_REGION` / `AWS_REGION` / `AWS_PROFILE` / credenciais AWS | Necessárias para `provider=bedrock` — reusa a mesma cadeia do chat. | conforme chat Bedrock |
**Bedrock embeddings** suportam `amazon.titan-embed-text-v2:0` (default), `amazon.titan-embed-text-v1`, `cohere.embed-english-v3` e `cohere.embed-multilingual-v3`. Titan paraleliza batches com pool de 8 workers (a API só aceita 1 texto por chamada); Cohere v3 envia o batch inteiro numa só call. A dispatch é auto pelo prefixo do model id. Veja [RAG + HyDE](/pt/features/quality/rag-hyde) e [AWS Bedrock](/pt/features/bedrock).
### Reasoning Backbone (#7)
| Variável | Descrição | Padrão |
| --------------------------------------- | ------------------------------------------------------------------ | ------------------------------------ |
| `CHATCLI_QUALITY_REASONING_MODE` | `off\|auto\|on` — política de auto-attach de thinking/reasoning | `auto` |
| `CHATCLI_QUALITY_REASONING_BUDGET` | Tokens de thinking (Anthropic); mapeado para tier na OpenAI | `8000` |
| `CHATCLI_QUALITY_REASONING_AUTO_AGENTS` | CSV de agents que recebem effort hint automaticamente em mode=auto | `planner,refiner,verifier,reflexion` |
### Per-Agent Overrides (inclui refiner / verifier)
| Variável | Descrição |
| ------------------------------- | ---------------------------------------- |
| `CHATCLI_AGENT_REFINER_MODEL` | Modelo específico para o `RefinerAgent` |
| `CHATCLI_AGENT_REFINER_EFFORT` | Effort tier (`low\|medium\|high\|max`) |
| `CHATCLI_AGENT_VERIFIER_MODEL` | Modelo específico para o `VerifierAgent` |
| `CHATCLI_AGENT_VERIFIER_EFFORT` | Effort tier |
Presets recomendados (cheap dev, rigorous review, docs, incident, autopilot) em [Configuração do Pipeline](/pt/features/quality/configuration#presets-recomendados).
***
## Workspace de Sessão e Subagent
Variáveis que controlam o [Workspace de Sessão](/pt/features/session-workspace) (scratch dir + overflow de tool results) e a [Delegação para Subagent](/pt/features/subagent-delegation).
| Variável | Descrição | Padrão |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `CHATCLI_AGENT_TMPDIR` | **Apenas leitura** — exportada automaticamente pelo ChatCLI no startup com o caminho do scratch dir da sessão. Disponível em todo subprocesso lançado pelo `exec` do agente. | (definido no startup) |
| `CHATCLI_AGENT_KEEP_TMPDIR` | Se `true`, pula o cleanup do scratch dir no encerramento da sessão. Útil para inspecionar scripts temporários e arquivos de overflow após o exit. | `false` |
| `CHATCLI_BLOCK_TMP_WRITES` | Se `true`, **bloqueia** a extensão automática do allowlist para `os.TempDir()` e `/tmp`. Só o scratch dir isolado da sessão fica acessível. Use em multi-user / CI estrito. Veja [Session Workspace](/pt/features/session-workspace#seguran%C3%A7a). | `false` (permite) |
| `CHATCLI_AGENT_SUBAGENT_MAX_DEPTH` | Profundidade máxima de delegações aninhadas via `delegate_subagent`. Protege contra recursão patológica. | `2` |
| `CHATCLI_AGENT_SUBAGENT_MAX_TURNS` | Iterações máximas do loop ReAct interno de cada subagente. | `15` |
| `CHATCLI_TOOL_RESULT_BUDGET_CHARS` | Orçamento agregado de tool results por turno. Acima disso, os maiores resultados são salvos em `tool-results/` da sessão e substituídos por preview. | `200000` |
| `CHATCLI_TOOL_RESULT_MAX_CHARS` | Tamanho máximo de um único tool result inline. | `20000` |
***
## Confiança TLS Global (Proxy Corporativo)
Para ambientes atrás de proxy/gateway corporativo com **inspeção TLS** via CA privada (Zscaler, Netskope, CrowdStrike Falcon etc.). As duas variáveis valem para **todas as conexões HTTPS de saída** do processo: todos os providers LLM, TTS/STT, embeddings, web tools (`@webfetch`/`@websearch`/`@osv`), canais do gateway, transports MCP, registries de skills e o version check. É o equivalente process-wide do `NODE_EXTRA_CA_CERTS` / `NODE_TLS_REJECT_UNAUTHORIZED` em ferramentas Node.js como o Claude Code.
| Variável | Descrição | Padrão |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `CHATCLI_CA_BUNDLE` | Caminho para um bundle PEM com a CA corporativa. Mesclado no pool de certificados do sistema e usado como `RootCAs` em todas as conexões de saída (equivalente ao `NODE_EXTRA_CA_CERTS`). Bundle ilegível ou sem certificados válidos **falha aberto** para a verificação default, com warning no log — nunca enfraquece a verificação silenciosamente. | *(trust store do sistema)* |
| `CHATCLI_TLS_INSECURE_SKIP_VERIFY` | `true` desabilita a verificação TLS **por completo**, em todas as conexões (equivalente ao `NODE_TLS_REJECT_UNAUTHORIZED=0`). Emite warning alto no log. **Inseguro** — use somente para confirmar que o problema é de confiança TLS; depois configure o `CHATCLI_CA_BUNDLE`. | `false` |
O Go — e portanto o ChatCLI — **já confia no trust store do sistema operacional por default** (Keychain no macOS, cert store no Windows, `/etc/ssl` no Linux). Se a CA corporativa já está instalada na máquina, nenhuma configuração é necessária. O `CHATCLI_CA_BUNDLE` cobre o caso em que a CA **não pode** ser instalada system-wide.
Com `CHATCLI_TLS_INSECURE_SKIP_VERIFY=true` o ChatCLI aceita **qualquer** certificado — inválido, expirado, forjado — e fica exposto a man-in-the-middle (captura de API keys, código e credenciais). Nunca use em produção.
As variáveis específicas do Bedrock (`CHATCLI_BEDROCK_CA_BUNDLE` / `CHATCLI_BEDROCK_INSECURE_SKIP_VERIFY`, na seção [AWS Bedrock](#aws-bedrock-cat%C3%A1logo-completo)) têm **precedência** sobre as globais; na ausência delas, o Bedrock herda as globais como fallback, já que o AWS SDK monta o próprio HTTP client.
Diagnóstico rápido: inspeção TLS mal-resolvida gera erro **x509** (`certificate signed by unknown authority`) — isso o `CHATCLI_CA_BUNDLE` resolve. Um **403** vem de camada acima (WAF/política do proxy: User-Agent, fingerprint, autenticação) e não se resolve com trust TLS — para isso veja as variáveis de proxy web (`HTTPS_PROXY`, `CHATCLI_PROXY_AUTH`) em `/config resilience`.
***
## Compactação de Histórico e Recuperação de Payload
Controla o comportamento do `HistoryCompactor` (pipeline de 3 níveis: trim → summarize → emergency) e a detecção reativa de limites de proxy/gateway corporativo. Veja [Recuperação de Contexto](/pt/features/context-recovery).
| Variável | Descrição | Padrão |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `CHATCLI_CONTEXT_WINDOW` | **Override global da janela de contexto** (em tokens), válido para qualquer provider/modelo. Tem precedência sobre o catálogo de modelos e os fallbacks por provider. É o escape hatch para gateways/agentes cuja janela real difere do catálogo — ex.: um agente StackSpot apoiado num modelo de fundação maior ou menor. Como o orçamento de compactação deriva da janela de contexto, esta env controla diretamente quando o auto-compact dispara. Aceita apenas inteiro positivo; valores inválidos são ignorados silenciosamente. | *(auto via catálogo)* |
| `CHATCLI_MAX_PAYLOAD` | **Teto human-friendly** de body size para o POST HTTP. Aceita `5MB`, `512KB`, `2.5MB`, `5` (= 5 MB). Quando setado, o compactor respeita esse limite como adicional à janela de contexto do modelo, e o pre-flight força compactação agressiva ao cruzar 85% do cap. **Essencial em ambientes atrás de proxy corporativo** (Cloudflare, Akamai, WAF) que capa body size em 1-5 MB independentemente do contexto do modelo. | *(não setado — sem cap)* |
| `CHATCLI_MAX_RECOVERY_ATTEMPTS` | Tentativas máximas de recuperação de context overflow por sessão. | `3` |
| `CHATCLI_MAX_TOKEN_ESCALATIONS` | Escalações máximas de `max_tokens` por sessão. | `2` |
| `CHATCLI_EMERGENCY_KEEP_MESSAGES` | Mensagens mantidas no truncamento de emergência (Level 2 recovery). | `10` |
| `CHATCLI_MICROCOMPACT_TRUNCATE_TURNS` | Idade (em turnos) em que tool results antigos começam a ser truncados para head+tail preview, sem chamada LLM. Essa é a primeira linha de defesa, antes do `NeedsCompaction` disparar. | `2` |
| `CHATCLI_MICROCOMPACT_SUMMARIZE_TURNS` | Idade (em turnos) em que tool results antigos são substituídos por uma linha-summary (`[Old tool result cleared — N lines, N chars, type]`). | `4` |
Se você está atrás de proxy corporativo e não sabe o limite exato, comece com `CHATCLI_MAX_PAYLOAD=4MB`. Se tomar 413 mesmo assim, reduza para `3MB`. Se funcionar fluido, pode subir para `5MB` ou `10MB` (dependendo do proxy). O ChatCLI já deixa 30% de headroom para JSON overhead + system prompt + tool definitions.
Se um 413/WAF/EOF acontecer sem `CHATCLI_MAX_PAYLOAD` setado, o ChatCLI assume automaticamente **4 MB** para o resto da sessão (auto-cap reativo) e injeta um hint no histórico para a IA preferir leituras line-ranged. Isso evita loop de falha quando o usuário ainda não descobriu o limite do próprio proxy.
***
## UI dos modos `/coder` e `/agent`
| Variável | Descrição | Padrão |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `CHATCLI_CODER_UI` | Estilo da timeline: `full` · `compact` · `minimal`. **Afeta `/coder` E `/agent`** (cross-mode desde v1.119). | `full` |
| `CHATCLI_AGENT_TOOL_CATALOG` | Catálogo de tools no prompt do agente: `deferred` (tools core completas + índice de 1 linha para o resto, expandível via `@tools describe` — \~70% menos tokens de definições) ou `full` (todas inline, legado). Runtime: `/config agent catalog`. | `deferred` |
| `CHATCLI_CODER_BANNER` | Mostrar cheat sheet de comandos na entrada do `/coder` | `true` |
**Estilos disponíveis:**
* **`full`** (padrão) — cards completos com borda fechada `╭── ICON TITLE ─────╮ ... ╰─╯`. Cada chamada de ferramenta é uma "ação" destacada. Ideal para `/agent` (fluxo plan-and-execute supervisionado).
* **`compact`** — linhas inline `↻ Read(main.go)` / `✓ Read(main.go) 0.3s`. Sessões longas com dezenas de tools ficam scannáveis. Ideal para `/coder`.
* **`minimal`** — meio termo: cards menores com conteúdo truncado.
A variável mantém o nome legado `CHATCLI_CODER_UI` por compatibilidade, mas a partir da v1.119 ela controla os DOIS modos. Se você tinha `CHATCLI_CODER_UI=compact` setado, o `/agent` também passa a renderizar em compacto.
**Mudança visual também em v1.119:** falhas de ferramenta (`✗`, `❌ FALHA NA EXECUÇÃO`) agora renderizam em **vermelho real** em vez de roxo. Antes ficavam na mesma cor do header (`ColorPurple`), o que confundia. Se o seu terminal mapeia ANSI 31 (red) para uma cor não-vermelha via theme, ajuste a paleta do terminal.
***
## Efeito de Escrita (Typewriter Adaptativo)
A resposta final da IA é pintada com um efeito de "máquina de escrever" — runa por runa, com um pequeno delay entre cada caractere — para dar a sensação de uma conversa viva em vez de um paste único. A partir da v1.120 o ChatCLI usa **pacing adaptativo**: respostas curtas mantêm a cadência original (a animação se percebe como animação), respostas longas têm o delay automaticamente escalonado para caber em um orçamento total (\~800ms por padrão), e respostas muito longas (acima de 8 000 runas visíveis, ex.: blocos de código gigantes) pulam a animação inteiramente. O comportamento se aplica de forma consistente nos modos `/chat`, `/coder` e `/agent` — todas as superfícies que tipam saída do modelo convergem no mesmo helper interno (`agent.PaceText`).
| Variável | Descrição | Padrão |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `CHATCLI_NO_TYPEWRITER` | Desliga o efeito de máquina de escrever **inteiramente**. A resposta é pintada de uma vez só (instantâneo). Aceita `1`, `true`, `yes`, `on` (case-insensitive). Útil em terminais lentos, sessões `tmux` espelhadas, ou se você simplesmente não curte o efeito e quer a resposta na tela imediatamente. | — (efeito ativo) |
| `CHATCLI_TYPEWRITER_BUDGET_MS` | Orçamento total da animação em milissegundos. Para respostas longas, o delay por runa é dividido por (runas visíveis), de modo que o efeito inteiro complete dentro deste orçamento. Setar `0` desliga o orçamento (cada runa usa o delay solicitado integralmente — o comportamento antigo da v1.119, em que respostas longas levavam vários segundos). Valores típicos: `400` (rápido), `800` (default), `1500` (animação mais perceptível). | `800` |
| `CHATCLI_TYPEWRITER_DELAY_MS` | Delay por runa em milissegundos, sobrescrevendo o que o call site interno solicitou. Útil para casar com sua percepção visual: `0` força o mínimo possível (\~200μs por runa = animação quase imperceptível mas presente), `5` ou `10` dá uma cadência mais "datilografada". A variável tem precedência sobre o delay programático, mas ainda passa pelo orçamento (`CHATCLI_TYPEWRITER_BUDGET_MS`), então respostas longas continuam respeitando o teto. | `2` |
**Como as três variáveis interagem:**
1. Se `CHATCLI_NO_TYPEWRITER` está ligado, **nada mais importa** — a resposta é instantânea.
2. Senão, o ChatCLI lê o delay solicitado (do call site) ou `CHATCLI_TYPEWRITER_DELAY_MS` se setado.
3. Conta as runas visíveis (sequências ANSI de cor não contam — elas são emitidas instantaneamente para que transições de cor não pausem o olho).
4. Se runas visíveis ≥ 8 000, pula a animação (limite "hardSkip" embutido para evitar dumps de código congelarem o terminal por 16+ segundos).
5. Senão, calcula `delay_efetivo = min(delay_solicitado, CHATCLI_TYPEWRITER_BUDGET_MS / runas_visíveis)`, com piso de 200μs.
Resumo: o orçamento puxa o delay **para baixo** quando a resposta é longa, mas nunca o aumenta. Respostas curtas continuam usando o delay solicitado original.
**Granularidade do sistema:** `time.Sleep` em Linux/macOS tem granularidade mínima \~1ms, então valores muito pequenos de `CHATCLI_TYPEWRITER_DELAY_MS` (ex.: `0`) na prática rodam em \~200μs–1ms efetivos. Não é precisão de microcontrolador — é "rápido o suficiente para parecer instantâneo num shell humano".
**Exemplos práticos:**
```bash theme={"system"}
# Desabilita totalmente o efeito (paste único)
export CHATCLI_NO_TYPEWRITER=1
# Animação mais rápida: orçamento 300ms, qualquer resposta completa em ≤300ms
export CHATCLI_TYPEWRITER_BUDGET_MS=300
# Datilografia mais lenta (4ms por runa) MAS ainda respeitando o budget
export CHATCLI_TYPEWRITER_DELAY_MS=4
# Volta ao comportamento pré-v1.120 (sem orçamento, sempre 2ms por runa)
export CHATCLI_TYPEWRITER_BUDGET_MS=0
export CHATCLI_TYPEWRITER_DELAY_MS=2
```
***
## Fallback de Provedores
| Variável | Descrição | Padrão |
| ----------------------------------- | ----------------------------------------- | ------ |
| `CHATCLI_FALLBACK_PROVIDERS` | Lista de provedores separados por vírgula | — |
| `CHATCLI_FALLBACK_MODEL_` | Modelo específico por provedor na cadeia | — |
| `CHATCLI_FALLBACK_MAX_RETRIES` | Tentativas por provedor antes de avançar | `2` |
| `CHATCLI_FALLBACK_COOLDOWN_BASE` | Cooldown base após falha | `30s` |
| `CHATCLI_FALLBACK_COOLDOWN_MAX` | Cooldown máximo (backoff exponencial) | `5m` |
***
## MCP (Model Context Protocol)
| Variável | Descrição | Padrão |
| --------------------- | --------------------------------------- | ----------------------------- |
| `CHATCLI_MCP_ENABLED` | Ativar o gerenciador MCP | `false` |
| `CHATCLI_MCP_CONFIG` | Caminho para o JSON de configuração MCP | `~/.chatcli/mcp_servers.json` |
O subsistema MCP gerencia automaticamente o diretório `~/.chatcli/mcp/` para state durável: `channels.jsonl` (ring persistente de push notifications, com rotação) e `triggers.json` (rules opt-in do trigger engine). Não há variáveis de ambiente para esses paths — eles são fixos. Detalhes: [MCP Channels](/pt/features/mcp-channels) e [MCP Config](/pt/reference/mcp-config).
***
## Bootstrap e Memória
| Variável | Descrição | Padrão |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `CHATCLI_BOOTSTRAP_ENABLED` | Ativar carregamento de arquivos bootstrap | `true` |
| `CHATCLI_BOOTSTRAP_DIR` | Diretório dos arquivos bootstrap | — |
| `CHATCLI_MEMORY_ENABLED` | Ativar sistema de memória persistente | `true` |
| `CHATCLI_MEMORY_MAX_SIZE` | Tamanho máximo do MEMORY.md renderizado (bytes) | `32768` |
| `CHATCLI_MEMORY_RETENTION_DAYS` | Dias para reter notas diárias antes da limpeza | `30` |
| `CHATCLI_MEMORY_MAX_FACTS` | Número máximo de fatos no índice de memória | `500` |
| `CHATCLI_MEMORY_RETRIEVAL_BUDGET` | Caracteres máximos de memória no system prompt | `4000` |
| `CHATCLI_MEMORY_FALLBACK_PROVIDERS` | Cadeia de providers de fallback para a **extração de memória** (ex.: `OPENAI,GOOGLEAI`). Vazio → usa `CHATCLI_FALLBACK_PROVIDERS`. Segmentos que falham em todos vão para a fila em disco e são reprocessados. | — |
| `CHATCLI_SELFEVOLVE_MODE` | Auto-evolução de skills, que pega carona na mesma passada de extração de memória. `auto` cria/evolui skills sozinho (edit-safe, reversível via `@skill restore`); `suggest` só sugere; `off` desativa. Veja `/config selfevolve`. | `auto` |
| `CHATCLI_GRAPH_INDEX` | Injeta o *index card* (map-of-content) do grafo de conhecimento no prompt do agent/coder por turno. Determinístico/cache-friendly. O pull via `@memory neighbors`/`map` continua disponível independente deste flag. | `on` |
***
## Scheduler
Veja [Scheduler (Chronos)](/pt/features/scheduler) para o design completo. Todas as variáveis aceitam sufixo `enabled` / `disabled` / `true` / `false` / `1` / `0` quando aplicável.
### Núcleo
| Variável | Descrição | Padrão |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `CHATCLI_SCHEDULER_ENABLED` | Master switch do scheduler | `true` |
| `CHATCLI_SCHEDULER_DATA_DIR` | Diretório com WAL + snapshot + audit log | `~/.chatcli/scheduler` |
| `CHATCLI_SCHEDULER_MAX_JOBS` | Número máximo de jobs não-terminais simultâneos | `256` |
| `CHATCLI_SCHEDULER_WORKER_COUNT` | Goroutines do worker pool que executam handleJob | `4` |
| `CHATCLI_SCHEDULER_WAIT_WORKER_COUNT` | Goroutines dedicadas ao loop de wait (reservado, mesmo pool por enquanto) | `8` |
| `CHATCLI_SCHEDULER_ALLOW_AGENTS` | Permitir que agents criem jobs via `@scheduler` | `true` |
| `CHATCLI_SCHEDULER_ACTION_ALLOWLIST` | CSV de action types permitidos | `slash_cmd,llm_prompt,agent_task,worker_dispatch,hook,noop,webhook,shell,agent_resume,park_poll` |
| `CHATCLI_SCHEDULER_HISTORY_LIMIT` | Máximo de `ExecutionResult`s mantidos por job (ring buffer) | `16` |
| `CHATCLI_PARK_DIR` | Override do diretório de snapshots do `@park` — útil para testes e ambientes isolados. Veja [Agent Park & Resume](/pt/features/agent-park) | `$XDG_CONFIG_HOME/chatcli/parked` |
### Budget padrão (por-job se não sobrescrito)
| Variável | Descrição | Padrão |
| ------------------------------------------- | --------------------------------------------------- | ------ |
| `CHATCLI_SCHEDULER_DEFAULT_ACTION_TIMEOUT` | Timeout da ação em cada fire | `5m` |
| `CHATCLI_SCHEDULER_DEFAULT_POLL_INTERVAL` | Intervalo entre polls de wait-condition | `5s` |
| `CHATCLI_SCHEDULER_DEFAULT_WAIT_TIMEOUT` | Timeout máximo do loop de wait | `30m` |
| `CHATCLI_SCHEDULER_DEFAULT_MAX_POLLS` | Máximo de polls antes de desistir (`0` = ilimitado) | `0` |
| `CHATCLI_SCHEDULER_DEFAULT_BACKOFF_INITIAL` | Backoff inicial entre retries | `1s` |
| `CHATCLI_SCHEDULER_DEFAULT_BACKOFF_MAX` | Cap do exponential backoff | `5m` |
| `CHATCLI_SCHEDULER_DEFAULT_BACKOFF_MULT` | Fator multiplicativo do backoff | `2.0` |
| `CHATCLI_SCHEDULER_DEFAULT_BACKOFF_JITTER` | Fração de jitter (`0.0`–`0.5`) | `0.2` |
| `CHATCLI_SCHEDULER_DEFAULT_MAX_RETRIES` | Retries após falha transiente | `3` |
| `CHATCLI_SCHEDULER_DEFAULT_TTL` | TTL de registros terminais em disco | `24h` |
### Segurança
| Variável | Descrição | Padrão |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `CHATCLI_SCHEDULER_RATE_LIMIT_GLOBAL_RPS` | Token bucket global (req/s) | `5.0` |
| `CHATCLI_SCHEDULER_RATE_LIMIT_GLOBAL_BURST` | Burst do bucket global | `20` |
| `CHATCLI_SCHEDULER_RATE_LIMIT_OWNER_RPS` | Token bucket por-owner | `1.0` |
| `CHATCLI_SCHEDULER_RATE_LIMIT_OWNER_BURST` | Burst do bucket por-owner | `10` |
| `CHATCLI_SCHEDULER_BREAKER_FAILURE_THRESHOLD` | Falhas consecutivas para abrir breaker | `5` |
| `CHATCLI_SCHEDULER_BREAKER_WINDOW` | Janela de contagem do breaker | `60s` |
| `CHATCLI_SCHEDULER_BREAKER_COOLDOWN` | Cooldown antes da probe half-open | `30s` |
| `CHATCLI_SCHEDULER_SHELL_ALLOW_BYPASS` | Quando `true`, jobs podem setar `bypass_safety=true` no payload da action para pular o preflight **e** o re-check no fire. Sem esta variável, `bypass_safety=true` é rejeitado. Shell actions normalmente passam pelo preflight CoderMode (`ClassifyShellCommand`) no enqueue **e** re-check no `RunShell` no fire — esta env é o escape hatch para trusted CI. | `false` |
### Audit log
| Variável | Descrição | Padrão |
| -------------------------------------- | ---------------------------------------- | ------ |
| `CHATCLI_SCHEDULER_AUDIT_ENABLED` | Escrever `/audit.log` em JSONL | `true` |
| `CHATCLI_SCHEDULER_AUDIT_MAX_SIZE_MB` | Rotação por tamanho (lumberjack) | `10` |
| `CHATCLI_SCHEDULER_AUDIT_MAX_BACKUPS` | Backups retidos | `7` |
| `CHATCLI_SCHEDULER_AUDIT_MAX_AGE_DAYS` | Idade máxima em dias | `30` |
### Daemon
| Variável | Descrição | Padrão |
| --------------------------------------- | ------------------------------------------ | ----------------------------- |
| `CHATCLI_SCHEDULER_DAEMON_SOCKET` | Path do UNIX socket do daemon | `/tmp/chatcli-scheduler.sock` |
| `CHATCLI_SCHEDULER_DAEMON_AUTO_CONNECT` | CLI auto-detecta daemon e vira thin client | `true` |
| `CHATCLI_SCHEDULER_SNAPSHOT_INTERVAL` | Periodicidade do snapshot | `5m` |
| `CHATCLI_SCHEDULER_WAL_GC_INTERVAL` | Periodicidade do GC de terminais expirados | `1h` |
***
## Métricas e Observabilidade
| Variável | Descrição | Padrão |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
| `CHATCLI_METRICS_PORT` | Porta HTTP para exportar métricas Prometheus (`0` = desabilitado) | `9090` |
| `PROMETHEUS_URL` | URL do Prometheus para coleta de métricas durante análise de incidentes AIOps. Quando definido, o operator consulta CPU/memória/latência/error rate trends correlacionados ao incidente. Exemplo: `http://prometheus-server.monitoring.svc:9090` | *(vazio = desabilitado)* |
***
## Segurança
| Variável | Descrição | Padrão |
| ------------------------------- | ---------------------------------------------------------- | ---------- |
| `CHATCLI_SAFETY_ENABLED` | Ativar regras de segurança configuráveis | `false` |
| `CHATCLI_GRPC_REFLECTION` | Habilitar gRPC reflection no servidor (usar apenas em dev) | `false` |
| `CHATCLI_DISABLE_VERSION_CHECK` | Desabilitar verificação automática de versão | `false` |
| `CHATCLI_LATEST_VERSION_URL` | URL customizada para verificação de versão | GitHub API |
### Threat scan de contexto e memória
Sanitiza conteúdo **injetado** no prompt — contextos anexados via `/context attach` e a memória de longo prazo — contra prompt-injection antes de enviá-lo ao modelo.
| Variável | Descrição | Padrão |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------- |
| `CHATCLI_THREATSCAN` | Liga/desliga o threat scan de contexto e memória. Ligado por padrão; aceita `false`/`0`/`off`/`no` para desativar. | `true` (on) |
### Segurança do Servidor
| Variável | Descrição | Padrão |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `CHATCLI_JWT_SECRET` | Segredo JWT para assinatura (HS256) ou caminho da chave RSA (RS256) | `""` |
| `CHATCLI_JWT_ISSUER` | Claim `issuer` esperado no JWT | `""` |
| `CHATCLI_JWT_AUDIENCE` | Claim `audience` esperado no JWT | `""` |
| `CHATCLI_RATE_LIMIT_RPS` | Rate limit: requisições por segundo (sustentado) | `10` |
| `CHATCLI_RATE_LIMIT_BURST` | Rate limit: capacidade de burst | `20` |
| `CHATCLI_MAX_RECV_MSG_SIZE` | Tamanho máximo de mensagem gRPC recebida (bytes) | `4194304` |
| `CHATCLI_MAX_SEND_MSG_SIZE` | Tamanho máximo de mensagem gRPC enviada (bytes) | `4194304` |
| `CHATCLI_MAX_CONCURRENT_STREAMS` | Máximo de streams gRPC simultâneos por conexão | `100` |
| `CHATCLI_BIND_ADDRESS` | Interface de rede para bind do servidor. Padrão `127.0.0.1` (local); auto-detecta `0.0.0.0` em Kubernetes via `KUBERNETES_SERVICE_HOST`. | `127.0.0.1` / `0.0.0.0` (K8s) |
| `CHATCLI_AUDIT_LOG_PATH` | Caminho do arquivo de audit log estruturado. Deve ser **absoluto** — valores relativos são rejeitados com erro no log. | `""` |
| `CHATCLI_LOG_FILE` | Caminho do arquivo de log da aplicação | `~/.chatcli/app.log` |
| `CHATCLI_LOG_MAX_SIZE_MB` | Tamanho máximo do log antes da rotação (MB) | `100` |
| `CHATCLI_LOG_MAX_BACKUPS` | Número de arquivos de log rotacionados a manter | `3` |
| `CHATCLI_LOG_MAX_AGE_DAYS` | Idade máxima dos arquivos de log rotacionados (dias) | `30` |
| `CHATCLI_DEBUG` | Habilitar modo debug com logging verboso | `false` |
| `CHATCLI_ALLOW_HTTP_PROVIDERS` | Permitir conexões HTTP (sem TLS) para provedores LLM | `false` |
### Segurança do Agente
| Variável | Descrição | Padrão |
| ----------------------------------- | ------------------------------------------------------------------ | ------------ |
| `CHATCLI_AGENT_SECURITY_MODE` | Modo de segurança: `strict` (allowlist) ou `permissive` (denylist) | `permissive` |
| `CHATCLI_AGENT_ALLOWLIST` | Comandos extras permitidos no modo strict (separados por `;`) | `""` |
| `CHATCLI_AGENT_WORKSPACE_STRICT` | Restringir acesso a arquivos apenas ao diretório do workspace | `false` |
| `CHATCLI_AGENT_ALLOW_KUBECONFIG` | Permitir acesso ao kubeconfig em comandos do agente | `false` |
| `CHATCLI_AGENT_EXTRA_READ_PATHS` | Caminhos de leitura adicionais permitidos (separados por `;`) | `""` |
| `CHATCLI_AGENT_SOURCE_SHELL_CONFIG` | Carregar config do shell (`~/.bashrc`, etc.) em comandos do agente | `false` |
| `CHATCLI_MAX_COMMAND_OUTPUT` | Tamanho máximo da saída de comandos (bytes) | `65536` |
### Segurança de Plugins e Autenticação
| Variável | Descrição | Padrão |
| -------------------------------- | ----------------------------------------------------------- | ----------- |
| `CHATCLI_ALLOW_UNSIGNED_PLUGINS` | Permitir execução de plugins não assinados | `false` |
| `CHATCLI_ALLOW_INSECURE` | Permitir conexões inseguras (sem TLS) | `false` |
| `CHATCLI_TLS_CLIENT_CERT` | Certificado TLS do cliente para mTLS | `""` |
| `CHATCLI_TLS_CLIENT_KEY` | Chave TLS do cliente para mTLS | `""` |
| `CHATCLI_ENCRYPTION_KEY` | Chave de criptografia customizada para dados de sessão | Auto-gerado |
| `CHATCLI_KEYCHAIN_BACKEND` | Backend do keychain: `auto`, `file`, `keychain` | `auto` |
| `CHATCLI_DISABLE_HISTORY` | Desabilitar gravação do histórico de conversas | `false` |
| `CHATCLI_SESSION_TTL` | Tempo de vida da sessão antes da expiração | `24h` |
| `CHATCLI_ENV_REDACT_MODE` | Redação de variáveis de ambiente: `full`, `partial`, `none` | `full` |
| `CHATCLI_REDACT_PATTERNS` | Padrões customizados de redação (regex separados por `;`) | `""` |
### Segurança do Operator
A autenticação da REST API do operator carrega API keys com hot-reload a cada 30s na seguinte ordem de prioridade:
**Secret** `chatcli-operator-secrets` → **ConfigMap** `chatcli-operator-config` → rejeitar (ou aceitar em dev-mode se `CHATCLI_OPERATOR_DEV_MODE=true`).
| Variável | Descrição | Padrão |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `CHATCLI_OPERATOR_DEV_MODE` | Habilitar modo dev do operator (segurança relaxada) | `false` |
| `CHATCLI_AIOPS_TLS_CERT` | Certificado TLS da REST API AIOps | `""` |
| `CHATCLI_AIOPS_TLS_KEY` | Chave TLS da REST API AIOps | `""` |
| `CHATCLI_GRPC_TLS_CERT` | Certificado TLS do gRPC | `""` |
| `CHATCLI_GRPC_TLS_KEY` | Chave TLS do gRPC | `""` |
| `CHATCLI_GRPC_TLS_CA` | Certificado CA do gRPC para verificação mTLS. Deve ser caminho **absoluto** (valores relativos retornam erro). No operator é apenas fallback — quando se usa Instance CR, o WatcherBridge lê `ca.crt` do Secret referenciado por `spec.server.tls.secretName` automaticamente (ver [cookbook §2.1](/pt/cookbook/aiops-production-setup#2-1-criar-o-secret-chatcli-tls-corretamente-sans-ca)). | `""` |
| `CHATCLI_ALLOWED_RESOURCE_TYPES` | Tipos de recursos Kubernetes permitidos pelo `ApplyManifest` (comma-separated) | `Deployment,StatefulSet,DaemonSet,…` |
| `CHATCLI_ALLOWED_DIAGNOSTIC_COMMANDS` | Comandos adicionais aceitos por `ExecDiagnostic` (comma-separated, estende o allowlist default de \~90 entradas — ver [k8s-operator#execdiagnostic-allowlist](/pt/features/k8s-operator#execdiagnostic-allowlist)) | `""` (só defaults) |
| `CHATCLI_OPERATOR_APP_VERSION` | Injetado pelo Helm chart a partir de `.Chart.AppVersion`. O operator usa para resolver a tag da imagem do servidor quando `Instance.spec.image.tag` é omitido — permite que `helm upgrade` do operator role também as Instances. Não definir manualmente. | Setado pelo chart |
| `CHATCLI_LOG_SCRUB_PATTERNS` | Padrões para limpar dos logs (regex separados por `;`) | Padrões internos |
***
## OAuth
| Variável | Descrição | Padrão |
| -------------------------- | ----------------------------------------- | ------ |
| `CHATCLI_OPENAI_CLIENT_ID` | Sobrescrever client ID do OAuth da OpenAI | — |
***
## Servidor Remoto
| Variável | Descrição | Padrão |
| ------------------------- | -------------------------- | ------- |
| `CHATCLI_SERVER_PORT` | Porta do servidor gRPC | `50051` |
| `CHATCLI_SERVER_TOKEN` | Token de autenticação | — |
| `CHATCLI_SERVER_TLS_CERT` | Caminho do certificado TLS | — |
| `CHATCLI_SERVER_TLS_KEY` | Caminho da chave TLS | — |
***
## Cliente Remoto
| Variável | Descrição | Padrão |
| ------------------------ | --------------------------------- | ------ |
| `CHATCLI_REMOTE_ADDR` | Endereço do servidor remoto | — |
| `CHATCLI_REMOTE_TOKEN` | Token de autenticação | — |
| `CHATCLI_CLIENT_API_KEY` | Sua API key (enviada ao servidor) | — |
***
## Chat Gateway (Telegram / Slack / Discord / WhatsApp / Webhook)
Ponte que expõe o ChatCLI como bot/serviço em plataformas de mensagem. Acionada por `/gateway start`. Cada adaptador **só liga quando suas variáveis obrigatórias estão presentes** — defina apenas os canais que quiser. Ver [Chat Gateway](/pt/features/chat-gateway).
### Telegram
| Variável | Descrição | Padrão |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------- |
| `CHATCLI_TELEGRAM_BOT_TOKEN` | Token do bot (BotFather). **Obrigatório** para ativar o adaptador Telegram (long-polling via `getUpdates`). | — |
| `CHATCLI_TELEGRAM_ALLOWED_USERS` | Lista de user IDs autorizados, separados por vírgula/espaço/`;`. Vazio = qualquer usuário. | — (todos) |
### Slack
| Variável | Descrição | Padrão |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | --------------- |
| `CHATCLI_SLACK_BOT_TOKEN` | Bot token (`xoxb-…`) usado para responder. **Obrigatório**. | — |
| `CHATCLI_SLACK_ADDR` | Endereço de bind do servidor HTTP de eventos (ex.: `:8081`). **Obrigatório** — o adaptador só liga quando definido. | — |
| `CHATCLI_SLACK_SIGNING_SECRET` | Signing secret para verificar a assinatura HMAC dos eventos (Events API). | — |
| `CHATCLI_SLACK_PATH` | Path do endpoint de eventos. | `/slack/events` |
### Discord
| Variável | Descrição | Padrão |
| --------------------------- | ----------------------------------------------------------------------------------- | ------ |
| `CHATCLI_DISCORD_BOT_TOKEN` | Bot token. **Obrigatório** para ativar o adaptador Discord (Gateway WebSocket v10). | — |
### WhatsApp (Cloud API)
| Variável | Descrição | Padrão |
| ------------------------------- | ------------------------------------------------------------------------ | ------------------- |
| `CHATCLI_WHATSAPP_ACCESS_TOKEN` | Access token da WhatsApp Cloud API. **Obrigatório**. | — |
| `CHATCLI_WHATSAPP_PHONE_ID` | Phone number ID usado para enviar respostas. **Obrigatório**. | — |
| `CHATCLI_WHATSAPP_ADDR` | Endereço de bind do servidor de webhook (ex.: `:8082`). **Obrigatório**. | — |
| `CHATCLI_WHATSAPP_VERIFY_TOKEN` | Token de verificação do webhook (handshake GET da Meta). | — |
| `CHATCLI_WHATSAPP_PATH` | Path do webhook. | `/whatsapp/webhook` |
### Webhook genérico
| Variável | Descrição | Padrão |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ---------- |
| `CHATCLI_WEBHOOK_ADDR` | Endereço de bind do servidor de webhook genérico (ex.: `:8083`). **Obrigatório** — o adaptador só liga quando definido. | — |
| `CHATCLI_WEBHOOK_PATH` | Path que recebe os POSTs de entrada. | `/inbound` |
| `CHATCLI_WEBHOOK_SECRET` | Segredo compartilhado, validado em **tempo constante**. Vazio = sem verificação. | — |
| `CHATCLI_WEBHOOK_CALLBACK_URL` | URL para onde a resposta é enviada de volta via POST. Vazio = resposta síncrona na própria requisição. | — |
### Voz / transcrição (áudio nos canais)
Transcreve notas de voz para texto antes do pipeline. Seleção **local-first**: comando → URL self-hosted → whisper CLI no PATH (auto, baixa o modelo) → Groq → OpenAI → desabilitado. Ver [Chat Gateway → Mensagens de voz](/pt/features/chat-gateway).
| Variável | Descrição | Padrão |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `CHATCLI_TRANSCRIPTION_PROVIDER` | Fixa o backend STT: `embedded`, `command`, `url`, `groq`, `openai` (ou `auto`). No `auto`, sem nada configurado, cai no [Whisper embarcado](/pt/features/chat-gateway) (download único no startup do daemon). | `auto` |
| `CHATCLI_TRANSCRIPTION_CMD` | Comando STT local (placeholders `{input}`/`{output_dir}`/`{lang}`); lê o transcript do stdout ou do `.txt` gerado. | — |
| `CHATCLI_TRANSCRIPTION_URL` | Endpoint OpenAI-compatível self-hosted (`/v1`). Keyless. | — |
| `CHATCLI_TRANSCRIPTION_KEY` | Chave opcional para o endpoint self-hosted. | — |
| `CHATCLI_TRANSCRIPTION_MODEL` | Modelo (embarcado: `tiny`/`base`/`small`/`medium`/`large-v3`; cloud: ex. `whisper-1`; whisper local: `base`/`small`). | `whisper-1` (cloud) / `base` (embarcado) |
| `CHATCLI_TRANSCRIPTION_LANG` | Idioma forçado; vazio = auto-detecta o idioma falado. | `(auto)` |
| `CHATCLI_TRANSCRIPTION_CACHE_DIR` | Realoca o cache do motor embarcado (path absoluto; default `~/.cache/chatcli/stt/`). | (os cache dir) |
| `CHATCLI_GATEWAY_MAX_AUDIO_BYTES` | Tamanho máximo do áudio baixado. | `20971520` (20MB) |
Notas de voz são OGG/**Opus**; o whisper.cpp local e o motor embarcado precisam de **ffmpeg** para decodificá-las (backends cloud/self-hosted decodificam no servidor). Sem nada configurado, o gateway usa o **Whisper embarcado** automaticamente — só plataformas sem engine prebuilt recebem a dica de configuração.
### Mensagens proativas (@send)
Canais padrão para o tool [`@send`](/pt/features/proactive-messaging) quando o destino é só a plataforma.
| Variável | Descrição | Padrão |
| ------------------------------- | ------------------------- | ------ |
| `CHATCLI_TELEGRAM_HOME_CHANNEL` | Canal padrão do Telegram. | — |
| `CHATCLI_WHATSAPP_HOME_CHANNEL` | Canal padrão do WhatsApp. | — |
| `CHATCLI_DISCORD_HOME_CHANNEL` | Canal padrão do Discord. | — |
| `CHATCLI_SLACK_HOME_CHANNEL` | Canal padrão do Slack. | — |
| `CHATCLI_WEBHOOK_HOME_CHANNEL` | Alvo padrão do webhook. | — |
### Resposta em voz / TTS
Sintetiza a resposta em áudio. Seleção **local-first**: comando → URL self-hosted → **embarcado (se provisionado)** → `say`/`espeak` no PATH → OpenAI → Groq → Gemini → desabilitado. Ver [Text-to-Speech](/pt/features/text-to-speech) e [Respostas em Voz](/pt/features/voice-replies).
| Variável | Descrição | Padrão |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `CHATCLI_GATEWAY_VOICE_REPLY` | Modo de resposta em voz do gateway: `auto` (voz responde voz), `always`, `never`. Booleanos legados valem (`true`→always, `false`→never). | `auto` |
| `CHATCLI_GATEWAY_IMAGE_REPLY` | Anexa imagem **gerada/editada** pelo agent na resposta do gateway: `auto` (anexa quando produz uma), `never`. | `auto` |
| `CHATCLI_GATEWAY_MAX_IMAGE_BYTES` | Limite de download de imagem **recebida** nos canais (bytes). | `20971520` (20 MB) |
| `CHATCLI_TTS_PROVIDER` | Fixa o backend: `embedded` (ou `kokoro`)/`command`/`url`/`openai`/`groq`/`google` (ou `auto`). | `auto` |
| `CHATCLI_TTS_CMD` | Comando TTS local (placeholders `{text}`/`{output}`). Keyless. | — |
| `CHATCLI_TTS_CMD_EXT` | Extensão de saída do `CHATCLI_TTS_CMD`. | `wav` |
| `CHATCLI_TTS_URL` | Endpoint OpenAI-compatível (`/audio/speech`). | — |
| `CHATCLI_TTS_KEY` | Chave opcional do endpoint self-hosted. | — |
| `CHATCLI_TTS_MODEL` | Modelo TTS. | `tts-1` |
| `CHATCLI_TTS_VOICE` | Voz (depende do backend). No embarcado: voz para inglês. | `alloy` (embarcado: `bm_george`) |
| `CHATCLI_TTS_VOICE_PT` | Voz do motor embarcado para respostas em **português**. | `pm_alex` |
| `CHATCLI_TTS_CACHE_DIR` | Realoca o cache do motor embarcado (engine + modelo). Caminho **absoluto**. | cache do SO |
| `CHATCLI_TTS_VOICE_FORMAT` | Formato pedido na resposta do gateway (`ogg` = voice note no Telegram). | `ogg` |
### Geração de imagem (@image)
Gera imagens a partir de texto. **Local-first**: SD WebUI → URL OpenAI-compatível → OpenAI → Google Imagen → xAI grok-image → Bedrock. Ver [Geração de Imagem](/pt/features/image-generation).
| Variável | Descrição | Padrão |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
| `CHATCLI_IMAGE_PROVIDER` | Fixa o backend: `sdwebui`/`url`/`openai`/`responses`/`google`/`xai`/`bedrock` (ou `auto`). | `auto` |
| `CHATCLI_IMAGE_API` | No OpenAI: `images` (gpt-image-\*) ou `responses` (modelo de chat como `gpt-5.5` gera via tool `image_generation`). | `images` |
| `CHATCLI_IMAGE_URL` | SD WebUI (`http://localhost:7860`) ou endpoint OpenAI-compatível. | — |
| `CHATCLI_IMAGE_KEY` | Chave opcional do endpoint self-hosted. | — |
| `CHATCLI_IMAGE_MODEL` | Modelo (ex.: `gpt-image-1`, `gpt-5.5`, `grok-2-image`, `imagen-3.0-generate-002`, `amazon.nova-canvas-v1:0`). Vale para **gerar e editar** (herdado pelos dois). | `gpt-image-1` |
| `CHATCLI_IMAGE_STEPS` | Passos de sampling (SD WebUI). | `25` |
| `CHATCLI_IMAGE_EDIT_PROVIDER` | Fallback de **edição** quando o provider ativo não edita (xAI/Z.AI/MiniMax). Fixa um backend edit-capable: `sdwebui`/`openai`/`google`/`bedrock`/`url`. Vazio = herda o ativo e, se não editar, roteia automático. | (herda) |
| `CHATCLI_IMAGE_EDIT_MODEL` | Modelo do fallback de edição (quando aplicável). | (default do backend) |
### Renderização de diagramas (@diagram)
Renderiza Graphviz DOT em PNG/SVG/JPG com texto nítido e correto. O Graphviz é **embedado** (WASM, sem instalação); se houver um `dot` do sistema no PATH, o backend `auto` o usa para saída mais polida. Ver [Diagramas (@diagram)](/pt/features/diagram).
| Variável | Descrição | Padrão |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `CHATCLI_DIAGRAM_BACKEND` | Engine de renderização: `auto` (usa o `dot` do sistema se instalado, senão o embedado), `system` (força o `dot` nativo — erro se faltar) ou `embedded` (força o WASM embarcado). Sobreposto pelo arg `backend` por chamada. | `auto` |
### Grafo interativo (@graphview)
Renderiza um grafo interativo estilo Obsidian (force-directed, arrastável) em um HTML autocontido aberto no navegador. Ver [Grafo interativo (@graphview)](/pt/features/graphview).
| Variável | Descrição | Padrão |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `CHATCLI_GRAPHVIEW_THEME` | Tema padrão do grafo: `dark` ou `light`. Sobreposto pelo arg `theme` por chamada. | `dark` |
| `CHATCLI_GRAPHVIEW_OPEN` | Abre o HTML no navegador após renderizar (`true`/`false`). Sobreposto pelo arg `open`; a abertura é gated por TTY. | `true` |
| `CHATCLI_CHAT_GRAPHVIEW` | Habilita a exceção do `@graphview` no chat (o chat é tool-less por design). Alternável com `/config chat graphview on\|off`. | `true` |
| `CHATCLI_CHAT_MEMORY` | Habilita a exceção de memória/perfil no chat: o modelo persiste fatos duráveis e atualizações de perfil no mesmo turno via `@memory`. Alternável com `/config chat memory on\|off`. | `true` |
### Visão / entrada de imagem
Permite que o modelo **veja** imagens anexadas (`@file foto.png`) em chat/coder/agent e no gateway. Estratégia **híbrida**: providers com `vision` no catálogo recebem a imagem nativa; sem visão, um modelo de visão descreve a imagem e o texto entra no prompt (describe-fallback). Ver [Entrada de Imagem (Visão)](/pt/features/vision-input).
| Variável | Descrição | Padrão |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `CHATCLI_VISION_INPUT` | Modo da entrada de imagem: `auto` (catálogo → heurística de id → describe), `native` (força bloco nativo — útil para modelo com visão **fora do catálogo**), `describe` (sempre legenda), `off` (ignora imagens). | `auto` |
| `CHATCLI_VISION_PROVIDER` | Override do provider do describe-fallback (legendar imagem para modelos sem visão). Vazio = escolhe sozinho (provider atual → qualquer disponível com visão). | (auto) |
| `CHATCLI_VISION_MODEL` | Override do modelo do describe-fallback (ex.: `gpt-4o-mini` como legendador barato). | (auto) |
| `CHATCLI_VISION_COMPRESS` | Comprime imagens antes do envio (downscale + re-encode JPEG, puro-Go). `on`/`off`. Ver [Compressão de Contexto](/pt/features/context-compression). | `on` |
| `CHATCLI_VISION_MAX_EDGE` | Cap da maior aresta em px (downscale token-equivalente ao server-side). | `1568` |
| `CHATCLI_VISION_JPEG_QUALITY` | Qualidade JPEG do re-encode (1–100). | `82` |
xAI (imagem) e Groq (voz) usam suas chaves padrão (`XAI_API_KEY`, `GROQ_API_KEY`); Google usa `GOOGLEAI_API_KEY`/`GEMINI_API_KEY`; **Bedrock** usa a mesma cadeia AWS do provider de chat (`BEDROCK_REGION`/`AWS_REGION`, `BEDROCK_PROFILE`/`AWS_PROFILE`). Os tools `@osv`, `@session` e `@skill` não exigem variáveis. Use `@image models` ou `/config image` para ver/trocar backend e modelo em runtime.
***
## Conversation Hub (Continuidade Cross-Channel)
Faz a conversa atravessar canais: um assunto começado no Telegram/Slack/WhatsApp continua no chatcli do notebook (e vice-versa), até `/newsession`. É uma **ponte do momento** com banco limitado — não é memória de longo prazo (isso fica em `/memory` e `/session`). Ver [Conversation Hub](/pt/features/conversation-hub).
Todas as opções abaixo também podem ser ajustadas em runtime por comando (`/config hub set `), com **precedência: setting (no `hub.db`) > variável de ambiente > default**. O valor definido por comando persiste no banco e é lido ao vivo pelo daemon do gateway.
| Variável | Descrição | Padrão |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `CHATCLI_HUB_PRINCIPAL` | Identidade compartilhada da conversa (modo single-user). Sem ela, usa `default` — o CLI local e os remetentes não-vinculados do gateway colapsam nesse principal, então tudo funciona **sem configurar nada**. | `default` |
| `CHATCLI_HUB_ENABLED` | Liga o hub. `false` desativa (CLI local "começa limpo" e gateway sem continuidade). | `true` |
| `CHATCLI_HUB_ISOLATE` | Bot multi-usuário/público: `true` mantém cada identidade de canal em sua própria conversa (um usuário não vê o thread de outro). Off no padrão single-user. | `false` |
| `CHATCLI_HUB_TTL_HOURS` | Horas até uma conversa ociosa ser podada (`PurgeIdle` roda ao abrir CLI/gateway). `0` desativa a purga. | `24` |
| `CHATCLI_HUB_BINDINGS` | Vínculos explícitos `plataforma:user_id=principal`, separados por `;`/`,` (ex.: `telegram:123=alice;slack:U1=alice`). Tem precedência sobre o colapso single-user. | — |
| `CHATCLI_HUB_DB` | Caminho do banco SQLite (WAL) do hub. | `~/.chatcli/hub.db` |
| `CHATCLI_HUB_TAIL_BUFFER` | Tamanho do buffer de fan-out (live tail) por subscriber no servidor gRPC. | `256` |
| `CHATCLI_GATEWAY_IN_SERVER` | `true` roda o gateway **dentro do processo do servidor** (`chatcli server`), compartilhando o mesmo broker em memória — habilita push em tempo real para um CLI conectado (cross-process só sincroniza ao conectar/no próximo turno). | `false` |
Para "rodar o chatcli + o gateway na mesma máquina e compartilharem contexto": basta o `CHATCLI_HUB_PRINCIPAL` (ou o default) — nenhum binding é necessário. Para bot multi-usuário, ligue `CHATCLI_HUB_ISOLATE=true` e use `CHATCLI_HUB_BINDINGS` para mapear quem é quem.
***
## LSP (Language Server Protocol — diagnósticos)
Diagnósticos de código (erros/avisos do compilador/linter) para um arquivo, via servidores LSP. Acionado manualmente pelo comando `/lsp `. Cada variável sobrescreve o **comando** usado para iniciar o language server da linguagem; quando omitida, o ChatCLI usa o preset padrão (se o binário estiver no `PATH`). Ver [Diagnósticos LSP](/pt/features/lsp-diagnostics).
| Variável | Descrição | Padrão (preset) |
| ------------------------ | ---------------------------------------------------- | ------------------------------------ |
| `CHATCLI_LSP_GO_CMD` | Comando do language server de Go. | `gopls` |
| `CHATCLI_LSP_PYTHON_CMD` | Comando do language server de Python. | `pyright-langserver --stdio` |
| `CHATCLI_LSP_TS_CMD` | Comando do language server de TypeScript/JavaScript. | `typescript-language-server --stdio` |
| `CHATCLI_LSP_RUST_CMD` | Comando do language server de Rust. | `rust-analyzer` |
| `CHATCLI_LSP_C_CMD` | Comando do language server de C. | `clangd` |
| `CHATCLI_LSP_CPP_CMD` | Comando do language server de C++. | `clangd` |
| `CHATCLI_LSP_JAVA_CMD` | Comando do language server de Java. | `jdtls` |
| `CHATCLI_LSP_RUBY_CMD` | Comando do language server de Ruby. | `solargraph stdio` |
***
## Busca Web (WebSearch)
| Variável | Descrição | Padrão |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `CHATCLI_WEBSEARCH_PROVIDER` | Força o backend preferido para `@websearch` / `/websearch`: `searxng`, `duckduckgo`, `brave`, `mojeek` ou `auto`. | `auto` |
| `SEARXNG_URL` | URL raiz da instância SearxNG self-hosted (ex.: `https://searx.internal.corp`). Quando setada, SearxNG entra na cadeia de fallback. | — |
Os backends são **keyless** por design: DuckDuckGo (scraping HTML, default) + SearxNG (self-hosted via `SEARXNG_URL`). Veja [Web Tools](/pt/features/web-tools) para a cadeia de fallback.
***
## K8s Watcher
| Variável | Descrição | Padrão |
| ----------------------------- | ------------------------------------- | -------------- |
| `CHATCLI_WATCH_DEPLOYMENT` | Deployment único (legado) | — |
| `CHATCLI_WATCH_NAMESPACE` | Namespace do deployment | `default` |
| `CHATCLI_WATCH_INTERVAL` | Intervalo de coleta | `30s` |
| `CHATCLI_WATCH_WINDOW` | Janela de observação | `2h` |
| `CHATCLI_WATCH_MAX_LOG_LINES` | Máximo de linhas de log por pod | `100` |
| `CHATCLI_WATCH_CONFIG` | Caminho para config YAML multi-target | — |
| `CHATCLI_KUBECONFIG` | Caminho do kubeconfig | Auto-detectado |
***
## Exemplo completo de `.env`
```env theme={"system"}
# Geral
LOG_LEVEL=info
CHATCLI_LANG=pt-BR
ENV=prod
LLM_PROVIDER=CLAUDEAI
# Provedor principal
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_MODEL=claude-sonnet-4-6
ANTHROPIC_MAX_TOKENS=20000
# Fallback
CHATCLI_FALLBACK_PROVIDERS=CLAUDEAI,OPENAI,GOOGLEAI
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
GOOGLEAI_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxxxxxx
# ZAI (Zhipu AI) — opcional
# ZAI_API_KEY=xxx
# ZAI_MODEL=glm-5
# MiniMax — opcional
# MINIMAX_API_KEY=xxx
# MINIMAX_MODEL=MiniMax-M2.7
# MINIMAX_API_COMPAT=anthropic # usar endpoint Anthropic-compatível
# Moonshot (Kimi) — opcional
# MOONSHOT_API_KEY=sk-xxx
# MOONSHOT_MODEL=kimi-k2.6
# MOONSHOT_THINKING=auto # auto | enabled | disabled
# OpenRouter — opcional (gateway multi-provedor, 200+ modelos)
# OPENROUTER_API_KEY=sk-or-xxx
# OPENROUTER_FALLBACK_MODELS=anthropic/claude-sonnet-4,google/gemini-2.5-flash
# Agente
CHATCLI_AGENT_CMD_TIMEOUT=2m
CHATCLI_AGENT_ALLOW_SUDO=false
# Multi-Agent
CHATCLI_AGENT_PARALLEL_MODE=true
CHATCLI_AGENT_MAX_WORKERS=4
# Bootstrap e Memória
CHATCLI_BOOTSTRAP_ENABLED=true
CHATCLI_MEMORY_ENABLED=true
# Efeito de escrita (typewriter adaptativo) — descomente para ajustar
# CHATCLI_NO_TYPEWRITER=1 # desliga inteiramente (resposta instantânea)
# CHATCLI_TYPEWRITER_BUDGET_MS=400 # orçamento total da animação em ms (default 800)
# CHATCLI_TYPEWRITER_DELAY_MS=4 # delay por runa em ms (default 2)
# Proxy corporativo — descomente e ajuste se seu ambiente capa body size
# CHATCLI_MAX_PAYLOAD=5MB
# CHATCLI_BLOCK_TMP_WRITES=true # sandbox estrito, bloqueia /tmp no allowlist
# Inspeção TLS corporativa (CA privada) — global, vale pra todos os providers e tools
# CHATCLI_CA_BUNDLE=/etc/ssl/corp-ca-bundle.pem
# CHATCLI_TLS_INSECURE_SKIP_VERIFY=true # INSEGURO — só pra diagnóstico, nunca produção
# Janela de contexto — descomente se a janela real do seu gateway/agente difere do catálogo
# CHATCLI_CONTEXT_WINDOW=128000
# Busca web — descomente se quiser SearxNG self-hosted como preferido
# SEARXNG_URL=https://searx.internal.corp
# CHATCLI_WEBSEARCH_PROVIDER=searxng # opcional, default é "auto" (DDG primeiro)
# Mixture-of-Agents (/moa) — descomente para habilitar o ensemble
# CHATCLI_MOA_MODELS=openai:gpt-5,claudeai:claude-opus-4-8,googleai:gemini-2.5-pro
# CHATCLI_MOA_AGGREGATOR=claudeai:claude-opus-4-8
# Chat Gateway (/gateway start) — descomente apenas os canais que usar
# CHATCLI_TELEGRAM_BOT_TOKEN=123:abc
# CHATCLI_TELEGRAM_ALLOWED_USERS=111111111,222222222
# CHATCLI_SLACK_BOT_TOKEN=xoxb-xxx
# CHATCLI_SLACK_ADDR=:8081
# CHATCLI_SLACK_SIGNING_SECRET=xxxx
# CHATCLI_DISCORD_BOT_TOKEN=xxxx
# CHATCLI_WHATSAPP_ACCESS_TOKEN=xxxx
# CHATCLI_WHATSAPP_PHONE_ID=123456
# CHATCLI_WHATSAPP_ADDR=:8082
# CHATCLI_WHATSAPP_VERIFY_TOKEN=meu-verify
# CHATCLI_WEBHOOK_ADDR=:8083
# CHATCLI_WEBHOOK_SECRET=supersegredo
# CHATCLI_WEBHOOK_CALLBACK_URL=https://meuapp.example/callback
# Conversation Hub (continuidade cross-channel) — ligado por padrão
# CHATCLI_HUB_PRINCIPAL=edilson # identidade compartilhada (default: "default")
# CHATCLI_HUB_ISOLATE=true # bot multi-usuário: isola cada canal
# CHATCLI_HUB_TTL_HOURS=24 # poda conversas ociosas (0 desativa)
# CHATCLI_HUB_BINDINGS=telegram:123=edilson;slack:U1=edilson
# CHATCLI_GATEWAY_IN_SERVER=true # gateway no processo do server (push tempo real)
# CHATCLI_HUB_ENABLED=false # desliga o hub por completo
# LSP (/lsp) — descomente só se precisar sobrescrever o comando default
# CHATCLI_LSP_GO_CMD=gopls -rpc.trace
# CHATCLI_LSP_PYTHON_CMD=pyright-langserver --stdio
# Segurança de contexto/memória e guarda de tool — on por default
# CHATCLI_THREATSCAN=false # desliga o scan de prompt-injection em contexto/memória
# CHATCLI_AGENT_TOOLGUARD=false # desliga o aviso de falhas repetidas de tool
```