> ## 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.
# Referência de Configuração (.env)
> Um guia completo de todas as variáveis de ambiente que você pode configurar em seu arquivo .env para personalizar o ChatCLI.
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
Ex: `--provider`, `--model` (maior prioridade)
`export LLM_PROVIDER=OPENAI`
`LLM_PROVIDER=OPENAI`
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](#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](#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](/pt/features/ui-theme).
```bash theme={"system"}
/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 ` (ou `/config theme `) 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](/pt/features/ui-theme).
## 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:
```bash theme={"system"}
/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 ` e depois `/config agent ui ` 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)](/pt/features/context-compression) 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.
```bash theme={"system"}
# 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](/pt/features/context-compression) 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](/pt/features/oauth-authentication) 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.4`, `gpt-4o`, `gpt-4o-mini`. | 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 usar a API de `v1/responses` em vez de `v1/chat/completions`. | 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](https://platform.minimax.io/docs/guides/quickstart-preparation), 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:
```env theme={"system"}
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`. | 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](https://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`:
```env theme={"system"}
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` | Força o wire dos modelos Claude: `mantle` (endpoint Messages) ou `invoke` (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](/pt/features/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](/pt/features/multi-agent-orchestration).
***
## 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_` | 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](/pt/features/provider-fallback).
***
## 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](/pt/features/mcp-channels) |
> Para detalhes completos, consulte a [documentação de MCP](/pt/features/mcp-integration) e [MCP Channels](/pt/features/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](/pt/features/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 agent/coder: `index` (pull, só um digest + `@memory recall`), `full` (push completo por turno) ou `off`. Chat trata `index` como `full`. | `index` |
| `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](/pt/features/bootstrap-memory).
***
## 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](/pt/features/skill-registry).
***
## Segurança e Controle
| Variável | Descrição | Padrão |
| :------------------------------ | :------------------------------------------------------------------------------------------------- | :------ |
| `CHATCLI_DISABLE_VERSION_CHECK` | Desabilita a verificação automática de versão no startup. Ú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](/pt/features/security).
***
## 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 |