Referência de Configuração (.env)

O ChatCLI é amplamente configurável através de variáveis de ambiente. Crie um arquivo .env na raiz do projeto ou no HOME.

Ordem de Prioridade

Flags de linha de comando

Ex: --provider, --model (maior prioridade)

Variáveis de Ambiente do Sistema

export LLM_PROVIDER=OPENAI

Variáveis no arquivo .env

LLM_PROVIDER=OPENAI

Valores Padrão

Valores internos do ChatCLI (menor prioridade)

Configuração Geral

Variável	Descrição	Padrão
`CHATCLI_ENV`	Modo de logging: `dev` (console colorido + arquivo), `prod` (somente arquivo JSON). Compatível com o legado `ENV`.	`prod`
`LLM_PROVIDER`	Define o provedor de IA padrão a ser usado. Valores válidos: `OPENAI`, `OPENAI_ASSISTANT`, `CLAUDEAI`, `BEDROCK`, `GOOGLEAI`, `XAI`, `ZAI`, `MINIMAX`, `MOONSHOT`, `OPENROUTER`, `STACKSPOT`, `OLLAMA`, `COPILOT`, `GITHUB_MODELS`.	`"OPENAI"`
`CHATCLI_LANG`	Define o idioma da interface. Valores: `pt-BR`, `en-US`. Se não definida, tentará detectar o idioma do sistema.	`en-US`
`LOG_LEVEL`	Nível dos logs. Opções: `debug`, `info`, `warn`, `error`.	`"info"`
`LOG_FILE`	Caminho para o arquivo de log. Padrão: `$HOME/.chatcli/app.log`	`"$HOME/.chatcli/app.log"`
`LOG_MAX_SIZE`	Tamanho máximo do arquivo de log antes da rotação. Aceita `100MB`, `50KB`, etc.	`"100MB"`
`HISTORY_MAX_SIZE`	Tamanho máximo do arquivo de histórico (`.chatcli_history`) antes da rotação.	`"100MB"`
`HISTORY_FILE`	Caminho personalizado para o arquivo de histórico (suporta `~`, hoje ele cria o histórico onde executou o chatcli).	`".chatcli_history"`
`CHATCLI_DOTENV`	Caminho personalizado para o seu arquivo `.env`.	`".env"`
`CHATCLI_IGNORE`	Caminho para arquivo de ignore (ex.: `.chatignore`). Quando definido, ele tem prioridade sobre o ignore do projeto/global.	`""`
`CHATCLI_CODER_UI`	Estilo da timeline dos modos `/coder` e `/agent` (cross-mode desde v1.119): `full` · `compact` · `minimal`. Veja a seção UI Styles.	`"full"`
`CHATCLI_CODER_BANNER`	Exibe o cheat sheet rápido do `/coder` na entrada da sessão (`true`/`false`).	`"true"`
`CHATCLI_THEME`	Tema de cores da interface inteira (chat, cards, markdown, spinners). 11 temas: `dark`, `light` + 9 da comunidade. Troca em runtime via `/config ui theme`. Veja a seção Tema de Cores.	`"dark"`

Tema de Cores

A variável CHATCLI_THEME escolhe a paleta de cores que reskina toda a interface — chat, cards do /coder e /agent, bordas, markdown, code blocks e spinners. Diferente do CHATCLI_CODER_UI, o tema é estado global do processo, então a troca vale na próxima renderização, sem reiniciar. São 11 temas: dark e light (variantes calibradas do ChatCLI) + nove paletas da comunidade — dracula, nord, tokyo-night, solarized-dark, solarized-light, gruvbox, catppuccin-mocha, monokai, one-dark. Previews em cores reais de cada um estão no Sistema de Tema.

/config ui                     # mostra o tema ativo + perfil de cor detectado
/config ui theme dark          # troca para o tema escuro
/config ui theme dracula       # troca por nome (qualquer um dos 11)
/config theme tokyo-night      # atalho equivalente

Autocomplete: /config ui theme <TAB> (ou /config theme <TAB>) oferece os 11 temas.

A troca vale só no processo atual. Para persistir, adicione CHATCLI_THEME=light ao seu .env — o mutator emite essa dica após cada troca e nunca reescreve seu .env sozinho. Em pipes, CI ou terminais sem cor (NO_COLOR, dumb), a saída degrada para texto limpo. Detalhes completos no Sistema de Tema.

UI Styles

A variável CHATCLI_CODER_UI controla como os modos /coder e /agent desenham tool calls, raciocínio e resultados na timeline. Antes da v1.119 ela só afetava /coder; a partir dessa versão vale também para /agent — quem já tinha CHATCLI_CODER_UI=compact setado vai ver o /agent ficar compacto também.

Valor	Aparência	Quando usar
`full` (padrão)	Cards completos com borda fechada `╭── ICON TITLE ─────╮ … ╰─────╯`. Cada ação é um bloco visível.	`/agent` supervisionado — plano-e-aprova.
`compact`	Linhas inline `↻ Read(main.go)` / `✓ Read(main.go) 0.3s`. Mensagens curtas, sem cards.	`/coder` com sessões longas (20+ tool calls).
`minimal`	Cards menores com conteúdo truncado. Meio termo.	Sessões mistas em terminais estreitos.

Trocar a UI em runtime

A partir da v1.119 dá pra trocar o estilo sem reiniciar o ChatCLI, direto no prompt:

/config agent ui              # mostra o estilo atual + opções
/config agent ui compact      # troca para compact (vale na próxima chamada /coder ou /agent)
/config agent ui full         # volta para o padrão
/config agent ui minimal      # meio termo

Autocomplete completo — digite /config agent <TAB> e depois /config agent ui <TAB> que aparecem full | compact | minimal.

A mudança vale só para o processo atual. Para persistir entre sessões, adicione CHATCLI_CODER_UI=compact (ou outro valor) no seu .env — o mutator emite essa dica logo após cada troca.

Mudanças visuais paralelas (v1.119)

Footer dos cards agora termina no tamanho do conteúdo (╰────╯), não estica até a borda do terminal.
Erros em vermelho real (✗, ❌ FALHA NA EXECUÇÃO) em vez de roxo. Se seu terminal mapeia ANSI 31 para outra cor via theme, ajuste a paleta.
Banner unificado para /coder e /agent: mesmo card de entrada com Objetivo/Tarefa, Workspace e Política.
Menu do /agent reorganizado em 3 colunas (Execução · Edição & Contexto · Visualização) — antes era lista vertical de 12 linhas.
Prompt prefix agrupa todos os badges ([🌐 ⏵ ▶2⏳1 🅿1]) em vez de listar [remote] [watch] [jobs:…] [🅿️ resume:…] separadamente.
Header de turno do chat: nova moldura ╭─ model ─── 1.4s · 312↑ 1800↓ ─╮ … ╰─╯ no modo conversa, com latência e tokens estimados.

Compressão de Contexto e Saída

Controle em runtime da Compressão de Contexto (CCR) e da redução de tokens de saída. As mudanças valem imediatamente; defina as variáveis no .env para um padrão permanente.

# Compressão de entrada (saída de tools, logs, diffs, JSON, prosa)
/config compression            # painel: modo, threshold, store CCR, economia
/config compression lossy      # redução total, reversível via @recall (padrão)
/config compression lossless   # apenas reduções lossless (sem descartar linhas)
/config compression off        # desativa
/config compression stats      # resumo de economia por estratégia

# Redução de tokens de saída
/config output                 # painel: verbosidade + effort routing
/config output concise         # corta cerimônia, mantém substância (padrão)
/config output minimal         # menos tokens corretos possível
/config output full            # sem steering
/config output effort on|off   # roteamento de esforço por complexidade (opt-in)

As tools @compress/@recall expõem a compressão sob demanda ao modelo. Veja a página Compressão de Contexto para detalhes, variáveis de ambiente e garantias de não-degradação.

Autenticação OAuth

Além das chaves de API tradicionais, o ChatCLI suporta autenticação via OAuth para OpenAI, Anthropic e GitHub Copilot. Com o OAuth, você pode usar seu plano existente (ChatGPT Plus, Codex, Claude Pro, GitHub Copilot) sem gerar API keys.

Variável	Descrição	Padrão
`CHATCLI_AUTH_DIR`	Diretório onde as credenciais OAuth são armazenadas.	`~/.chatcli/`
`CHATCLI_OPENAI_CLIENT_ID`	Permite sobrescrever o client ID do OAuth da OpenAI.	(interno)
`CHATCLI_COPILOT_CLIENT_ID`	Permite sobrescrever o client ID do OAuth do GitHub Copilot.	(interno)

As credenciais são armazenadas com criptografia AES-256-GCM em ~/.chatcli/auth-profiles.json. A chave de criptografia é gerada automaticamente e salva em ~/.chatcli/.auth-key (permissão 0600).

Use /auth login openai-codex, /auth login anthropic ou /auth login github-copilot no modo interativo para iniciar o fluxo OAuth. Consulte a documentação completa de OAuth para mais detalhes.

Configuração de Provedores

OpenAI

Variável	Descrição	Obrigatório?
`OPENAI_API_KEY`	Sua chave de API secreta da OpenAI. Alternativa: use `/auth login openai-codex` para OAuth.	Sim*
`OPENAI_MODEL`	O modelo a ser usado. Ex: `gpt-5.6-sol`, `gpt-5.6-luna`, `gpt-5.4`, `gpt-4o`.	Não
`OPENAI_ASSISTANT_MODEL`	O modelo a ser usado específicamente para a API de Assistentes.	Não
`OPENAI_USE_RESPONSES`	Define `true` para forçar a API `v1/responses` em todos os modelos. Definir `false` não força `v1/chat/completions`: sessões OAuth e modelos cuja entrada no catálogo prefere a Responses API (ex.: `gpt-5.4`) continuam usando-a.	Não
`OPENAI_API_URL`	Endpoint customizado de Chat Completions. Deve ser a URL completa terminando em `/chat/completions`; a URL de listagem `/models` é derivada dela. Com host customizado a listagem de modelos não é filtrada por família, e `OPENAI_API_KEY` continua sendo enviada como Bearer token (configure-a com a key do gateway).	Não
`OPENAI_RESPONSES_API_URL`	Endpoint customizado da Responses API. Configure as duas URLs ao redirecionar o provider para um endpoint compatível com OpenAI.	Não
`OPENAI_MAX_TOKENS`	Define o máximo de tokens a ser utilizados na sessão (depende do modelo)	Não

Anthropic (Claude)

Variável	Descrição	Obrigatório?
`ANTHROPIC_API_KEY`	Sua chave de API secreta da Anthropic. Alternativa: use `/auth login anthropic` para OAuth.	Sim*
`ANTHROPIC_MODEL`	O modelo a ser usado. Ex: `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-4-6`.	Não
`ANTHROPIC_API_VERSION`	A versão da API da Anthropic a ser usada nos cabeçalhos.	Não
`ANTHROPIC_MAX_TOKENS`	Define o máximo de tokens a ser utilizados na sessão (depende do modelo)	Não
`ANTHROPIC_SPEED`	Defina `fast` para opt-in no fast mode do Opus 4.8 (research preview, pricing premium).	Não

Google (Gemini)

Variável	Descrição	Obrigatório?
`GOOGLEAI_API_KEY`	Sua chave de API do Google AI Studio.	Sim
`GOOGLEAI_MODEL`	O modelo a ser usado. Ex: `gemini-2.5-pro`, `gemini-2.5-flash`.	Não
`GOOGLEAI_MAX_TOKENS`	Define o máximo de tokens a ser utilizados na sessão (depende do modelo)	Não

xAI (Grok)

Variável	Descrição	Obrigatório?
`XAI_API_KEY`	Sua chave de API secreta da xAI.	Sim
`XAI_MODEL`	O modelo a ser usado. Ex: `grok-4-1`, `grok-4-fast`, `grok-3`.	Não
`XAI_MAX_TOKENS`	Define o máximo de tokens a ser utilizados na sessão (depende do modelo)	Não

Ollama (Local)

Variável	Descrição	Obrigatório?
`OLLAMA_ENABLED`	Defina como `true` para habilitar o provedor Ollama.	Sim
`OLLAMA_BASE_URL`	URL base do seu servidor Ollama local.	Não
`OLLAMA_MODEL`	O nome do modelo local a ser usado (ex: `llama3`, `codellama`).	Não
`OLLAMA_FILTER_THINKING`	Filtra raciocínio intermediário em respostas (ex.: para `Qwen3`, `llama3` padrão `true`…).	Não
`OLLAMA_MAX_TOKENS`	Define o máximo de tokens para o provedor Ollama.	Não

StackSpot

Variável	Descrição	Obrigatório?
`CLIENT_ID`	Credencial de ID de cliente da StackSpot.	Sim
`CLIENT_KEY`	Credencial de chave de cliente da StackSpot.	Sim
`STACKSPOT_REALM`	O `realm` (tenant) da sua organização na StackSpot.	Sim
`STACKSPOT_AGENT_ID`	O ID do agente específico a ser utilizado.	Sim

ZAI (Zhipu AI)

Variável	Descrição	Obrigatório?
`ZAI_API_KEY`	Sua chave de API da Zhipu AI (z.ai). Aceita Bearer token simples ou formato `id.secret` para JWT automático.	Sim
`ZAI_MODEL`	O modelo a ser usado. Ex: `glm-5.2`, `glm-5`, `glm-4.7`, `codegeex-4`.	Não
`ZAI_MAX_TOKENS`	Define o máximo de tokens para a resposta.	Não

Rotação automática de JWT: Chaves no formato id.secret ativam automaticamente a geração de tokens JWT (HMAC-SHA256) com header customizado {"alg": "HS256", "sign_type": "SIGN"}. Os tokens são cacheados por 30 minutos e regenerados com 5 minutos de margem. Chaves sem ”.” continuam funcionando como Bearer tokens tradicionais. Totalmente automático, sem configuração adicional.

MiniMax

Variável	Descrição	Obrigatório?
`MINIMAX_API_KEY`	Sua chave de API da MiniMax. Enviada como Bearer token.	Sim
`MINIMAX_MODEL`	O modelo a ser usado. Ex: `MiniMax-M2.7`, `MiniMax-M2.5`. Case-sensitive!	Não
`MINIMAX_MAX_TOKENS`	Define o máximo de tokens para a resposta.	Não
`MINIMAX_API_COMPAT`	Modo de compatibilidade: `anthropic` para usar o endpoint Anthropic Messages da MiniMax.	Não

Endpoint Anthropic-compatível: Defina MINIMAX_API_COMPAT=anthropic para usar https://api.minimax.io/anthropic/v1/messages com formato Anthropic Messages (system como campo top-level, content blocks). O header anthropic-version: 2023-06-01 é adicionado automaticamente. A mesma autenticação Bearer é usada. O tool use nativo é desabilitado neste modo (fallback para XML). Disponível também via Helm (secrets.minimaxApiCompat: "anthropic") ou Docker (MINIMAX_API_COMPAT=anthropic).

Abordagem alternativa (recomendada pela MiniMax): Conforme a documentação oficial da MiniMax, você pode usar modelos MiniMax diretamente pelo provider CLAUDEAI sem precisar do MINIMAX_API_COMPAT. Basta configurar a base URL da Anthropic para apontar ao MiniMax:

LLM_PROVIDER=CLAUDEAI
ANTHROPIC_API_KEY=sua-chave-minimax
ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
ANTHROPIC_MODEL=MiniMax-M2.7

Isso funciona porque o endpoint api.minimax.io/anthropic é 100% compatível com a API da Anthropic. Use esta abordagem para aproveitar o tool calling nativo do Anthropic com modelos MiniMax.

Moonshot (Kimi)

Variável	Descrição	Obrigatório?
`MOONSHOT_API_KEY`	Chave de API (Bearer token) da Moonshot AI.	Sim
`MOONSHOT_MODEL`	Modelo a usar (`kimi-k2.6`, `kimi-k2.5`, `kimi-latest`, `kimi-thinking-preview`, `moonshot-v1-128k`, `moonshot-v1-32k`, `moonshot-v1-8k`).	Não
`MOONSHOT_MAX_TOKENS`	Define o máximo de tokens para a resposta.	Não
`MOONSHOT_THINKING`	Modo de raciocínio: `enabled`, `disabled`, `auto`. Modelos sem capability `thinking` ignoram a flag.	Não
`MOONSHOT_API_URL`	Endpoint customizado. Padrão: `https://api.moonshot.ai/v1/chat/completions`. Com host customizado, a listagem de modelos não é filtrada por família.	Não

Modo Thinking vs Instant: O default auto deixa o modelo decidir; enabled força raciocínio explícito (mais caro em latência e tokens); disabled força resposta direta. Útil para alternar entre tarefas que se beneficiam de chain-of-thought e respostas rápidas (extração, classificação). A flag é injetada via extra_body.thinking.type no payload OpenAI-compatible.

OpenRouter

Variável	Descrição	Obrigatório?
`OPENROUTER_API_KEY`	Sua chave de API do OpenRouter (openrouter.ai). Uma única chave para acessar 200+ modelos.	Sim
`OPENROUTER_API_URL`	URL customizada da API.	Não
`OPENROUTER_MAX_TOKENS`	Define o máximo de tokens para a resposta.	Não
`OPENROUTER_FALLBACK_MODELS`	Lista de modelos de fallback separados por vírgula. O OpenRouter tenta automaticamente o próximo modelo se o principal falhar. Ex: `anthropic/claude-sonnet-4,google/gemini-2.5-flash`.	Não
`OPENROUTER_PROVIDER_ORDER`	Preferência de provedores separados por vírgula. Ex: `Anthropic,Google`.	Não
`OPENROUTER_TRANSFORMS`	Transformações de mensagem. Ex: `middle-out` para lidar com overflow de contexto.	Não
`OPENROUTER_HTTP_REFERER`	Header de atribuição HTTP Referer para o dashboard do OpenRouter.	Não
`OPENROUTER_APP_TITLE`	Header de atribuição com o título da sua aplicação.	Não
`OPENROUTER_TOOLS`	Array JSON de ferramentas para injeção no request.	Não

Gateway multi-provedor: O OpenRouter é um gateway que unifica o acesso a modelos de OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek e dezenas de outros provedores. Os modelos usam o formato provedor/nome-do-modelo (ex: openai/gpt-4o, anthropic/claude-sonnet-4). O modelo padrão é openai/gpt-4o. Configure no .env:

LLM_PROVIDER=OPENROUTER
OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxx"

# (Opcional) Modelo — padrão: openai/gpt-4o
# MODEL="anthropic/claude-sonnet-4"

# (Opcional) Fallback nativo do OpenRouter
# OPENROUTER_FALLBACK_MODELS="openai/gpt-4o,google/gemini-2.5-flash"

GitHub Copilot

Variável	Descrição	Obrigatório?
`GITHUB_COPILOT_TOKEN`	Token OAuth do GitHub Copilot. Alternativa: use `/auth login github-copilot` para Device Flow.	Sim*
`COPILOT_MODEL`	O modelo a ser usado. Ex: `gpt-4o`, `claude-sonnet-4`, `gemini-2.0-flash`.	Não
`COPILOT_MAX_TOKENS`	Define o máximo de tokens para a resposta.	Não
`COPILOT_API_BASE_URL`	URL base da API do Copilot (para ambientes enterprise).	Não

AWS Bedrock

Variável	Descrição	Obrigatório?
`AWS_PROFILE`	Profile AWS em `~/.aws/credentials` ou `~/.aws/config` (suporta SSO, assume-role, credential_process). Pode ser definido no `.env`.	Sim*
`AWS_ACCESS_KEY_ID`	Chave de acesso IAM estática. Alternativa ao `AWS_PROFILE`.	Sim*
`AWS_SECRET_ACCESS_KEY`	Chave secreta IAM (obrigatória junto com `AWS_ACCESS_KEY_ID`).	Sim*
`AWS_SESSION_TOKEN`	Token de sessão temporária (STS).	Não
`BEDROCK_REGION`	Região AWS para o Bedrock (prioridade sobre `AWS_REGION`).	Não
`AWS_REGION`	Região AWS (fallback se `BEDROCK_REGION` não definida).	Não
`BEDROCK_PROVIDER`	Override manual do schema: `anthropic` ou `openai`.	Não
`BEDROCK_ANTHROPIC_ENDPOINT`	Roteamento do wire Claude: `auto` (default, por catálogo com fallback Mantle→InvokeModel), `mantle` (pinado, sem fallback) ou `invoke` (só InvokeModel legado).	Não
`BEDROCK_MANTLE_BASE_URL`	Override do endpoint Messages (`bedrock-mantle.{região}.api.aws`) para VPC endpoints/proxies.	Não
`AWS_BEARER_TOKEN_BEDROCK`	Bearer token de curta duração para o endpoint Messages (header `x-api-key`, sem SigV4).	Não
`BEDROCK_MAX_TOKENS`	Limite de tokens de saída.	Não
`BEDROCK_TEMPERATURE`	Temperature usada nos modelos OpenAI no Bedrock.	Não
`CHATCLI_BEDROCK_CA_BUNDLE`	Bundle PEM com CA corporativa para TLS. Precede `AWS_CA_BUNDLE` e o global `CHATCLI_CA_BUNDLE`.	Não
`CHATCLI_BEDROCK_INSECURE_SKIP_VERIFY`	`true` desabilita verificação TLS (inseguro, apenas troubleshooting). Precede o global `CHATCLI_TLS_INSECURE_SKIP_VERIFY`.	Não
`AWS_EC2_METADATA_DISABLED`	`true` desabilita IMDS (evita timeout em 169.254.169.254 fora de EC2).	Não
`CHATCLI_BEDROCK_ENABLE_IMDS`	`true` força habilitar o probe IMDS em máquinas não-EC2.	N��o

O Bedrock não usa API key — a autenticação é feita pela cadeia de credenciais do AWS SDK: env vars → ~/.aws/credentials → ~/.aws/config (SSO, assume-role) → IAM role (EC2/ECS/EKS).* É necessário ao menos uma fonte de credenciais: AWS_PROFILE, AWS_ACCESS_KEY_ID, profile SSO em ~/.aws/config, credenciais em ~/.aws/credentials, ou IAM role. Para detalhes completos (SSO, proxy, inference profiles), consulte a documentação do AWS Bedrock.

* Para OpenAI, Anthropic e GitHub Copilot, a chave de API é obrigatória apenas se você não utilizar autenticação OAuth (/auth login). Ambos os métodos podem coexistir.

Configuração do Modo Agente

Variável	Descrição
`CHATCLI_AGENT_ALLOW_SUDO`	Defina como `"true"` para permitir que o agente sugira e execute comandos com `sudo`. Use com extrema cautela.
`CHATCLI_AGENT_DENYLIST`	Lista de padrões regex (separados por `;`) para bloquear comandos adicionais no modo agente.
`CHATCLI_AGENT_CMD_TIMEOUT`	Timeout para a execução de um único comando pelo agente (padrão: `10m`, máximo: `1h`).
`CHATCLI_AGENT_PLUGIN_MAX_TURNS`	Limite máximo de turnos do agente no modo `/agent`/`/coder` (padrão: `50`, máximo: `200`).
`CHATCLI_AGENT_PLUGIN_TIMEOUT`	Timeout total do plugin do agente (padrão: `15m`).

Multi-Agent (Orquestração Paralela)

Variável	Descrição	Padrão
`CHATCLI_AGENT_PARALLEL_MODE`	Ativa o modo multi-agent com orquestração paralela. O LLM orquestrador despacha agents especialistas em paralelo.	`false`
`CHATCLI_AGENT_MAX_WORKERS`	Número máximo de workers (goroutines) executando agents simultaneamente.	`4`
`CHATCLI_AGENT_WORKER_MAX_TURNS`	Máximo de turnos do mini ReAct loop de cada worker agent.	`10`
`CHATCLI_AGENT_WORKER_TIMEOUT`	Timeout por worker agent individual. Aceita durações Go (ex: `30s`, `2m`, `10m`).	`5m`
`CHATCLI_AGENT_PARALLEL_TOOLS`	Ativa execução paralela de tools concurrency-safe dentro de um único agente (read-only ops como `@read`, `@search`, `@websearch`). Distinto de `CHATCLI_AGENT_PARALLEL_MODE` (multi-agente). Off por default enquanto em rollout.	`false`
`CHATCLI_AGENT_MAX_TOOL_CONCURRENCY`	Cap de fan-out simultâneo para o batch paralelo de tools dentro de um agente.	`10`
`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 deixa passar one-liners read-only e bloqueia apenas padrões com `os.system`, `subprocess`, `socket`, `eval`, file writes, network.	`false`

Para detalhes completos sobre o sistema multi-agent, consulte a documentação de Orquestração Multi-Agent.

Configuração do Modo Servidor (`chatcli server`)

Variável	Descrição	Padrão
`CHATCLI_SERVER_PORT`	Porta do servidor gRPC.	`50051`
`CHATCLI_SERVER_TOKEN`	Token de autenticação para o servidor. Vazio = sem autenticação.	`""`
`CHATCLI_SERVER_TLS_CERT`	Caminho para o certificado TLS do servidor.	`""`
`CHATCLI_SERVER_TLS_KEY`	Caminho para a chave TLS do servidor.	`""`
`CHATCLI_GRPC_REFLECTION`	Habilita gRPC reflection para debugging. Mantenha desabilitado em produção.	`false`

Fallback de Provedores

Variável	Descrição	Padrão
`CHATCLI_FALLBACK_PROVIDERS`	Lista de provedores separados por vírgula para failover automático. Ex.: `OPENAI,CLAUDEAI,GOOGLEAI`.	`""`
`CHATCLI_FALLBACK_MODEL_<PROVIDER>`	Modelo específico por provedor na cadeia. Ex.: `CHATCLI_FALLBACK_MODEL_CLAUDEAI=claude-sonnet-4-20250514`.	(modelo padrão)
`CHATCLI_FALLBACK_MAX_RETRIES`	Tentativas por provedor antes de avançar para o próximo na cadeia.	`2`
`CHATCLI_FALLBACK_COOLDOWN_BASE`	Duração base do cooldown após falha de um provedor.	`30s`
`CHATCLI_FALLBACK_COOLDOWN_MAX`	Duração máxima do cooldown (backoff exponencial).	`5m`

Para detalhes completos, consulte a documentação de Fallback de Provedores.

MCP (Model Context Protocol)

Variável	Descrição	Padrão
`CHATCLI_MCP_ENABLED`	Ativa o gerenciador de servidores MCP.	`false`
`CHATCLI_MCP_CONFIG`	Caminho para o arquivo JSON de configuração dos servidores MCP.	`~/.chatcli/mcp_servers.json`

Arquivos no `~/.chatcli/mcp/`

Além do mcp_servers.json, o subsistema MCP gerencia automaticamente um diretório próprio para state durável:

Arquivo	Propósito
`~/.chatcli/mcp/channels.jsonl`	Ring durável de push notifications (append-only, rotaciona aos 10 MiB para `.1`). Recarregado no boot — alerts recebidos com ChatCLI fechado ficam visíveis ao abrir
`~/.chatcli/mcp/channels.jsonl.1`	Único histórico rotacionado (rotação substitui o anterior)
`~/.chatcli/mcp/triggers.json`	Opt-in — rules do trigger engine (`notify` / `confirm` / `auto`) que decidem como o ChatCLI reage a channel events. Veja MCP Channels

Para detalhes completos, consulte a documentação de MCP e MCP Channels.

Busca Web (WebSearch)

Variável	Descrição	Padrão
`CHATCLI_WEBSEARCH_PROVIDER`	Provider 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`).	—

Os backends são keyless (sem API key de terceiro). DuckDuckGo é o default zero-config; SearxNG self-hosted é preferido em ambientes corporativos. Veja Web Tools para a cadeia de fallback e como habilitar a JSON API do SearxNG.

Bootstrap e Memória

Variável	Descrição	Padrão
`CHATCLI_BOOTSTRAP_ENABLED`	Ativa o carregamento de arquivos bootstrap (SOUL.md, USER.md, etc.) no system prompt.	`true`
`CHATCLI_BOOTSTRAP_DIR`	Diretório contendo os arquivos bootstrap.	`~/.chatcli/bootstrap/`
`CHATCLI_MEMORY_ENABLED`	Ativa o sistema de memória persistente estruturado.	`true`
`CHATCLI_MEMORY_MODE`	Modo de injeção de memória em todos os modos (chat, agent, coder): `index` (pull, digest + ferramenta de recall), `full` (push completo por turno) ou `off`. O chat honra `index` via a exceção da ferramenta de memória; com `CHATCLI_CHAT_MEMORY=off` cai em `full`.	`index`
`CHATCLI_MEMORY_AUTORECALL`	Bloco proativo `[MEMORY AUTO-RECALL]` no modo `index` (top-3 fatos + linha `Related (graph):`).	`true`
`CHATCLI_MEMORY_GRAPH`	Cache persistido do grafo de conhecimento (`graph.json`) + expansão de vizinhança no recall; `off` restaura derivação por chamada, sem expansão.	`true`
`CHATCLI_GRAPH_INDEX`	Injeção por turno do card map-of-content do grafo (pull via `@memory map`/`neighbors` sempre disponível).	`true`
`CHATCLI_CHAT_MEMORY`	Exceção da ferramenta de memória no chat: persistência de fatos/perfil no mesmo turno e o caminho de pull do modo `index` no chat.	`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 automática.	`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 injetados no system prompt.	`4000`
`CHATCLI_SAFETY_ENABLED`	Ativa regras de segurança configuráveis no shell do agente.	`false`

Para detalhes completos, consulte a documentação de Bootstrap e Memória.

Skill Registry (Multi-Registry)

Variável	Descrição	Padrão
`CHATCLI_REGISTRY_URLS`	URLs adicionais de registries separadas por vírgula. Cada URL é adicionada como registry customizado habilitado.	`""`
`CHATCLI_REGISTRY_DISABLE`	Nomes de registries a desabilitar, separados por vírgula. Ex.: `clawhub,chatcli`.	`""`
`CHATCLI_SKILL_INSTALL_DIR`	Diretório onde skills instaladas via registry são salvas.	`~/.chatcli/skills`

O sistema de registries é configurado via arquivo ~/.chatcli/registries.yaml (criado automaticamente com registries padrão: chatcli e clawhub). As variáveis acima servem como overrides.

Para detalhes completos, consulte a documentação do Skill Registry.

Segurança e Controle

Variável	Descrição	Padrão
`CHATCLI_AUTO_UPDATE`	Política de auto-update: `auto` aplica em staging silencioso em background, `notify` mostra o aviso na tela de boas-vindas e na própria sessão, `off` desliga ambos. Veja Auto-Update.	`notify`
`CHATCLI_DISABLE_VERSION_CHECK`	Desabilita a verificação automática de versão no startup (implica auto-update `off`). Útil para ambientes air-gapped ou CI/CD.	`false`
`CHATCLI_GRPC_REFLECTION`	Habilita gRPC server reflection (expõe schema do serviço).	`false`

Segurança do Modo Agente

Variável	Descrição	Padrão
`CHATCLI_AGENT_SECURITY_MODE`	Modo de segurança: `strict` (apenas allowlist) ou `permissive` (allowlist + denylist legada como fallback).	`strict`
`CHATCLI_AGENT_ALLOWLIST`	Comandos adicionais para a allowlist, separados por `;`. Ex: `terraform;ansible;packer`.	`""`
`CHATCLI_AGENT_WORKSPACE_STRICT`	Restringe leituras de arquivo ao workspace atual. Bloqueia caminhos sensíveis (`~/.ssh`, `~/.aws`, etc.).	`false`
`CHATCLI_AGENT_ALLOW_KUBECONFIG`	Permite acesso ao kubeconfig mesmo com `WORKSPACE_STRICT` habilitado.	`false`
`CHATCLI_AGENT_EXTRA_READ_PATHS`	Caminhos adicionais permitidos para leitura, separados por `;`.	`""`
`CHATCLI_AGENT_SOURCE_SHELL_CONFIG`	Habilita source de arquivos de configuração do shell (`~/.bashrc`, `~/.zshrc`). Agora opt-in.	`false`
`CHATCLI_MAX_COMMAND_OUTPUT`	Limite de caracteres para saída de comandos antes da truncagem.	`50000`

Autenticação e Tokens

Variável	Descrição	Padrão
`CHATCLI_MAX_TOKEN_LIFETIME`	Tempo de vida máximo de tokens OAuth/JWT. Aceita durações Go (ex: `24h`, `168h`).	`720h` (30 dias)
`CHATCLI_JWT_SECRET`	Segredo para assinatura de tokens JWT do servidor.	`""`
`CHATCLI_SESSION_ENCRYPTION_KEY`	Chave para criptografia de sessões em repouso (AES-256).	`""`

Segurança de Rede e Servidor

Variável	Descrição	Padrão
`CHATCLI_RATE_LIMIT_RPS`	Limite de requisições por segundo (0 = desabilitado).	`0`
`CHATCLI_BIND_ADDRESS`	Endereço de bind do servidor. Padrão `127.0.0.1` (local); em Kubernetes, auto-detecta `0.0.0.0` via `KUBERNETES_SERVICE_HOST`. Valor explícito sempre prevalece.	`127.0.0.1` / `0.0.0.0` (K8s)
`CHATCLI_AUDIT_LOG`	Habilita log de auditoria de segurança com detalhes de cada operação.	`false`

Segurança de Plugins

Variável	Descrição	Padrão
`CHATCLI_PLUGIN_VERIFY_SIGNATURES`	Exige assinatura Ed25519 válida para carregar plugins.	`false`
`CHATCLI_PLUGIN_TRUSTED_KEYS`	Chaves públicas Ed25519 confiáveis para verificação de plugins, separadas por `;`.	`""`

Segurança do Operador K8s

Variável	Descrição	Padrão
`CHATCLI_OPERATOR_FAIL_CLOSED`	Modo fail-closed: bloqueia operações quando o agente está indisponível.	`false`
`CHATCLI_OPERATOR_RESOURCE_ALLOWLIST`	Lista de recursos K8s permitidos para o operador, separados por `;`.	`""`
`CHATCLI_OPERATOR_LOG_SCRUBBING`	Remove dados sensíveis (tokens, senhas) dos logs do operador.	`true`

Para detalhes completos sobre segurança, consulte a documentação de Segurança e Hardening.

Configuração do Cliente Remoto (`chatcli connect`)

Variável	Descrição	Padrão
`CHATCLI_REMOTE_ADDR`	Endereço do servidor remoto (`host:port`).	`""`
`CHATCLI_REMOTE_TOKEN`	Token de autenticação para conectar ao servidor.	`""`
`CHATCLI_CLIENT_API_KEY`	Sua própria API key/OAuth token, enviada ao servidor.	`""`

Configuração do K8s Watcher (`chatcli watch` / `chatcli server --watch-*`)

Variável	Descrição	Padrão
`CHATCLI_WATCH_DEPLOYMENT`	Nome do deployment Kubernetes a monitorar.	`""`
`CHATCLI_WATCH_NAMESPACE`	Namespace do deployment.	`"default"`
`CHATCLI_WATCH_INTERVAL`	Intervalo entre coletas de dados. Aceita durações Go (ex: `10s`, `1m`).	`"30s"`
`CHATCLI_WATCH_WINDOW`	Janela temporal de dados mantidos em memória.	`"2h"`
`CHATCLI_WATCH_MAX_LOG_LINES`	Número máximo de linhas de log coletadas por pod.	`100`
`CHATCLI_KUBECONFIG`	Caminho para o kubeconfig (opcional, usa default se não definido).	Auto-detectado

​Ordem de Prioridade

​Configuração Geral

​Tema de Cores

​UI Styles

​Trocar a UI em runtime

​Mudanças visuais paralelas (v1.119)

​Compressão de Contexto e Saída

​Autenticação OAuth

​Configuração de Provedores

​OpenAI

​Anthropic (Claude)

​Google (Gemini)

​xAI (Grok)

​Ollama (Local)

​StackSpot

​ZAI (Zhipu AI)

​MiniMax

​Moonshot (Kimi)

​OpenRouter

​GitHub Copilot

​AWS Bedrock

​Configuração do Modo Agente

​Multi-Agent (Orquestração Paralela)

​Configuração do Modo Servidor (chatcli server)

​Fallback de Provedores

​MCP (Model Context Protocol)

​Arquivos no ~/.chatcli/mcp/

​Busca Web (WebSearch)

​Bootstrap e Memória

​Skill Registry (Multi-Registry)

​Segurança e Controle

​Segurança do Modo Agente

​Autenticação e Tokens

​Segurança de Rede e Servidor

​Segurança de Plugins

​Segurança do Operador K8s

​Configuração do Cliente Remoto (chatcli connect)

​Configuração do K8s Watcher (chatcli watch / chatcli server --watch-*)

Ordem de Prioridade

Configuração Geral

Tema de Cores

UI Styles

Trocar a UI em runtime

Mudanças visuais paralelas (v1.119)

Compressão de Contexto e Saída

Autenticação OAuth

Configuração de Provedores

OpenAI

Anthropic (Claude)

Google (Gemini)

xAI (Grok)

Ollama (Local)

StackSpot

ZAI (Zhipu AI)

MiniMax

Moonshot (Kimi)

OpenRouter

GitHub Copilot

AWS Bedrock

Configuração do Modo Agente

Multi-Agent (Orquestração Paralela)

Configuração do Modo Servidor (`chatcli server`)

Fallback de Provedores

MCP (Model Context Protocol)

Arquivos no `~/.chatcli/mcp/`

Busca Web (WebSearch)

Bootstrap e Memória

Skill Registry (Multi-Registry)

Segurança e Controle

Segurança do Modo Agente

Autenticação e Tokens

Segurança de Rede e Servidor

Segurança de Plugins

Segurança do Operador K8s

Configuração do Cliente Remoto (`chatcli connect`)

Configuração do K8s Watcher (`chatcli watch` / `chatcli server --watch-*`)