Pular para o conteúdo principal
Encontrou um problema? Esta página lista os erros mais comuns e como resolvê-los.
Para diagnósticos mais detalhados, ative o log de debug: LOG_LEVEL=debug chatcli

​
Problemas Comuns

Sintomas: bash: chatcli: command not found ou zsh: command not found: chatcli.Causa: O diretório de binários do Go não está no PATH do seu sistema.Solução:
  1. Abra seu arquivo de configuração de shell (~/.bashrc, ~/.zshrc, etc.)
  2. Adicione ao final do arquivo:
export PATH=$PATH:$(go env GOPATH)/bin
  1. Reinicie seu terminal ou execute source ~/.zshrc
Sintomas: O ChatCLI encerra imediatamente após iniciar.Causa: Nenhuma chave de API foi configurada no .env.Solução:
  1. Crie ou abra o arquivo .env no diretório onde você executa o chatcli (ou no HOME)
  2. Adicione as credenciais para pelo menos um provedor:
LLM_PROVIDER=OPENAI
OPENAI_API_KEY="sk-sua-chave-secreta-aqui"
  1. Salve e execute chatcli novamente
Sintomas: Você alterou o LLM_PROVIDER ou outro valor, mas o ChatCLI usa a configuração antiga.Causa: O ChatCLI carrega as configurações na inicialização.Solução: Use o comando /reload dentro do modo interativo para recarregar as variáveis instantaneamente.
/reload
Sintomas: Erro “o arquivo não existe” ou “caminho não encontrado”.Solução:
  • Caminhos Relativos — são relativos ao diretório onde você executou o chatcli. Ex: @file ./project/src/main.go
  • Home (~) — funciona como atalho: @file ~/documentos/notas.txt
  • Permissões — verifique com ls -l se você tem permissão de leitura no arquivo
Sintomas: A IA apresenta um plano de ação, mas apenas aguarda sem executar.Causa: Isso é o comportamento esperado! O Modo Agente exige aprovação explícita.Solução:
  • Digite o número do comando (ex: 1) para executá-lo individualmente
  • Digite a para executar todos os comandos em sequência
  • Use --agent-auto-exec no modo one-shot para execução automática de comandos seguros
Sintomas: Mesmo com OLLAMA_ENABLED=true, o provedor não aparece disponível.Solução:
  1. Servidor Ollama — confirme que está rodando: ollama serve
  2. Modelo baixado — verifique com ollama list. Se vazio, baixe um: ollama pull llama3
  3. URL Base — se não está no endereço padrão, defina no .env:
OLLAMA_BASE_URL="http://localhost:11434"
Sintomas: A resposta da IA para no meio de uma frase.Causa: O limite de tokens da resposta foi atingido.Solução: Aumente o MAX_TOKENS do seu provedor no .env:
OPENAI_MAX_TOKENS=60000
ANTHROPIC_MAX_TOKENS=20000
GOOGLEAI_MAX_TOKENS=50000
Sintomas: Erro de timeout ou a aplicação trava aguardando resposta.Solução:
  • Use --timeout para definir um limite: chatcli -p "pergunta" --timeout 60s
  • Configure MAX_RETRIES e INITIAL_BACKOFF no .env para retentativas automáticas
  • Considere configurar Fallback de Provedores para redundância
O modo /coder valida que toda escrita ocorra dentro do diretório do projeto. A partir desta versão, o ChatCLI cria um Workspace de Sessão em $TMPDIR/chatcli-agent-<random>/ que está automaticamente na allowlist:
<tool_call name="@coder" args='{"cmd":"exec","args":{"cmd":"cat > $CHATCLI_AGENT_TMPDIR/script.sh <<EOF\n...\nEOF\nbash $CHATCLI_AGENT_TMPDIR/script.sh"}}' />
Para escritas via write ou patch, use o caminho absoluto que aparece no system prompt (a variável $CHATCLI_AGENT_TMPDIR não é expandida no campo file).Cleanup automático no exit; defina CHATCLI_AGENT_KEEP_TMPDIR=true para preservar e inspecionar.
Quando o orçamento corta o output e mostra [full output saved to /tmp/chatcli-agent-XXX/tool-results/...], o caminho está na allowlist de leitura do agente. Basta abrir com read_file:
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"/tmp/chatcli-agent-XXX/tool-results/budget_tc_3_1.txt","start":1200,"end":1500}}' />
Não refaça a tool call original — o conteúdo já está em disco. Detalhes em Resultados de Tools.
Duas estratégias complementares:
  1. Filtros do @webfetch — passe filter, exclude, from_line/to_line para filtrar antes do truncamento, ou save_to_file: true para persistir o corpo no scratch dir e ler trechos com read_file. Ver Web Tools.
  2. Delegação para subagente — delegate_subagent executa a análise em janela de contexto isolada e devolve só o resumo. Ver Subagent Delegation.
Você atingiu o limite de delegação aninhada (default 2). Causa comum: um subagente que delega para outro subagente em loop. Aumente com cuidado:
CHATCLI_AGENT_SUBAGENT_MAX_DEPTH=3 chatcli
Mas considere se a tarefa não cabe melhor em uma única delegação com prompt mais explícito sobre o que precisa ser feito.

​
Ainda com problemas?

Logs de Debug

Execute com LOG_LEVEL=debug e verifique ~/.chatcli/app.log para detalhes completos do erro.

Abrir Issue

Inclua: versão (chatcli --version), SO, Go version, passos para reproduzir e logs relevantes.