> ## 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.

# Solução de Problemas

> Encontre soluções rápidas para os problemas e erros mais comuns ao usar o ChatCLI.

Encontrou um problema? Esta página lista os erros mais comuns e como resolvê-los.

<Tip>
  Para diagnósticos mais detalhados, ative o log de debug: `LOG_LEVEL=debug chatcli`
</Tip>

***

## Problemas Comuns

<AccordionGroup>
  <Accordion title="Comando chatcli não encontrado" icon="terminal">
    **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:

    ```bash theme={"system"}
    export PATH=$PATH:$(go env GOPATH)/bin
    ```

    3. Reinicie seu terminal ou execute `source ~/.zshrc`
  </Accordion>

  <Accordion title="Erro &#x22;Nenhum provedor LLM está configurado&#x22;" icon="key">
    **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:

    ```env theme={"system"}
    LLM_PROVIDER=OPENAI
    OPENAI_API_KEY="sk-sua-chave-secreta-aqui"
    ```

    3. Salve e execute `chatcli` novamente
  </Accordion>

  <Accordion title="Alterações no .env não têm efeito" icon="rotate">
    **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.

    ```bash theme={"system"}
    /reload
    ```
  </Accordion>

  <Accordion title="@file não encontra um arquivo/diretório" icon="file-circle-exclamation">
    **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
  </Accordion>

  <Accordion title="Modo Agente não executa nada" icon="robot">
    **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
  </Accordion>

  <Accordion title="Provedor Ollama não é detectado" icon="server">
    **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`:

    ```env theme={"system"}
    OLLAMA_BASE_URL="http://localhost:11434"
    ```
  </Accordion>

  <Accordion title="Respostas cortadas ou incompletas" icon="scissors">
    **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`:

    ```env theme={"system"}
    OPENAI_MAX_TOKENS=60000
    ANTHROPIC_MAX_TOKENS=20000
    GOOGLEAI_MAX_TOKENS=50000
    ```
  </Accordion>

  <Accordion title="Timeout em chamadas de API" icon="clock">
    **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](/pt/features/provider-fallback) para redundância
  </Accordion>

  <Accordion title="Agent precisa criar arquivo temporário e o /coder bloqueia">
    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](/pt/features/session-workspace) em `$TMPDIR/chatcli-agent-<random>/` que está automaticamente na allowlist:

    ```xml theme={"system"}
    <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.
  </Accordion>

  <Accordion title="Tool result truncado mas não consigo ver o conteúdo completo">
    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`:

    ```xml theme={"system"}
    <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](/pt/features/tool-result-management).
  </Accordion>

  <Accordion title="Endpoint /metrics ou log enorme satura o contexto">
    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](/pt/features/web-tools#filtros-para-payloads-grandes).
    2. **Delegação para subagente** — `delegate_subagent` executa a análise em janela de contexto isolada e devolve só o resumo. Ver [Subagent Delegation](/pt/features/subagent-delegation).
  </Accordion>

  <Accordion title="Subagente recusa rodar com erro 'subagent depth N exceeds maximum'">
    Você atingiu o limite de delegação aninhada (default 2). Causa comum: um subagente que delega para outro subagente em loop. Aumente com cuidado:

    ```bash theme={"system"}
    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.
  </Accordion>
</AccordionGroup>

***

## Ainda com problemas?

<CardGroup cols={2}>
  <Card title="Logs de Debug" icon="bug">
    Execute com `LOG_LEVEL=debug` e verifique `~/.chatcli/app.log` para detalhes completos do erro.
  </Card>

  <Card title="Abrir Issue" icon="github" href="https://github.com/diillson/chatcli/issues">
    Inclua: versão (`chatcli --version`), SO, Go version, passos para reproduzir e logs relevantes.
  </Card>
</CardGroup>