Solução de problemas

Comece pelo ícone de estado

Antes de tudo, abra o coração da barra superior: é o Estado do aplicativo. Ele diz em uma frase se há uma IA conectada, se o modelo escolhido continua existindo, se há internet e se falta algum programa auxiliar — e cada aviso traz um botão Resolver que leva você ao passo concreto que falta.

Os erros do chat também já saem em linguagem simples, com a sua ação: «Esta IA ainda não tem a sua conta» → Conectar minha IA; «Esse modelo já não está disponível» → Escolher outro modelo; «Você atingiu o limite do seu plano» → Usar outra IA; «Não há conexão com a internet» → Instalar uma IA local; «Falta um programa que isto precisa» → Ver o que falta.

O chat não responde

A causa número um: o perfil ativo do provedor não tem credenciais válidas.

1. Abra o seletor de provedor (ao lado do campo do chat) e veja o estado: ele deve dizer Conectado. Se disser Sem autenticação, conecte-o novamente.
2. Atenção ao detalhe: a conexão é por perfil. Você pode ter o provedor conectado em um perfil e estar usando outro sem credenciais — verifique qual está ativo no chat.
3. Com provedores OAuth (Claude, OpenAI, Copilot): os tokens vencidos se renovam sozinhos, mas se você revogou o acesso pela sua conta, a renovação falha — faça login outra vez.
4. Se você acabou de trocar de provedor ou de modelo no meio do chat e algo ficou estranho, envie a mensagem de novo depois de verificar o estado do provedor.

O agente não faz nada, só fala

Verifique o modo de aprovação: em Apenas Chat o agente não pode escrever arquivos nem executar comandos, por design. Suba para “Perguntar” ou mais.

Não há autocompletar nem erros no editor

O servidor de linguagem (LSP) dessa linguagem não está instalado. O app avisa você ao abrir o arquivo e oferece instalá-lo pelo próprio aviso; você também pode administrá-los na aba LSP do painel de extensões — veja Skills, MCP e plugins.

Problemas com modelos locais

• Ollama / LM Studio não aparecem ou não listam modelos: confira se o aplicativo externo está rodando e se ele tem modelos instalados; depois tente de novo pelo seletor de provedor.
• O Context Forge não responde na aba API: o servidor sobe ao executar um modelo. Vá em Catálogo → Instalado e clique em Executar em um deles; confira que o campo model das suas requisições seja o id de um modelo em execução.
• A API key do Forge parou de funcionar: ela muda a cada inicialização do servidor; copie a nova pela aba API.
• O modelo está lento ou o computador fica sem memória: teste uma quantização menor do mesmo modelo, ou use Liberar memória / Parar o motor local na barra superior para descarregar modelos que você não esteja usando.

O Gemini responde «o modelo está saturado»

Com Gemini API Key o app já tenta de novo sozinho três vezes diante de um 503 ou de um 429 (aos 2, 5 e 10 segundos). Se mesmo assim a mensagem insistir — «O Google reporta saturação do modelo» —, o problema está do lado do Google: espere um momento e envie novamente, ou troque para outro modelo do catálogo pelo seletor do chat.

A conversa por voz não inicia

• «o servidor LiveKit não iniciou»: clique em Tentar de novo. Desde a 3.6.0 o motor vem dentro do instalador e não há nada para baixar; se repetir, veja se nada está ocupando a porta 7880 e se o seu antivírus não está bloqueando o servidor.
• «o agente de voz fechou antes de se registrar»: encerre a conversa, espere alguns segundos e clique em Tentar de novo. Se persistir, reinicie o aplicativo.
• O microfone não entra: os microfones «virtuais» publicam silêncio — escolha outro no seletor de Microfone. No Windows, verifique Configurações → Privacidade e segurança → Microfone e ative «Permitir que aplicativos da área de trabalho acessem o microfone».
• Ativa com o barulho do teclado: o detector está calibrado para ignorar cliques, mas um microfone colado a um teclado mecânico continua sendo má ideia. Use um fone de ouvido com microfone.
• Escolhi uma voz do Groq e soa outra: algumas vozes do Groq exigem aceitar os termos na sua conta. Enquanto isso o app não desliga a ligação: responde com Edge TTS.
• Todo o detalhe em Conversa em tempo real.

O console SQL perdeu a conexão

Desde a 3.6 não deveria: a conexão sobrevive à troca de seção e há reconexão automática. Se mesmo assim falhar:

• Depois de reconectar, a sessão é nova: não conserva o USE nem as tabelas temporárias do script anterior. Execute-os de novo.
• Um erro de SQL (coluna inexistente, restrição violada) não é repetido de propósito — repetir um INSERT às cegas seria pior. Corrija a consulta.
• Se o script nomear outro banco, o console avisa: use Reescrever para… ou Remover prefixos de banco.

O celular não conecta (app para celular / acesso web)

• Na rede local, celular e PC precisam estar no mesmo WiFi. O modo Conversa pelo celular só funciona por WiFi local, nunca pelo túnel público.
• O token do QR expira (configurável de 1 minuto a 24 horas): gere um QR novo e escaneie de novo.
• Se você rotacionou o token, todos os links anteriores ficam inválidos — é o esperado.
• Para acesso de fora de casa, crie a URL pública (túnel) pelo painel de Acesso web; a rede local não basta.

Um canal de mensagens não responde

• Você configurou a lista de usuários autorizados? Sem ela, o bot não responde a ninguém — é uma medida de segurança, não uma falha.
• WhatsApp: se você encerrou a sessão pelo celular (Aparelhos conectados), é preciso escanear o QR novamente.
• Telegram: verifique o Bot Token do @BotFather e escreva /start para o bot pela sua conta.
• Slack: o app precisa dos scopes chat:write e channels:history, e do ID do canal correto.

O workspace por SSH cai toda hora

Quase sempre é o NAT do seu roteador ou a VPN, que reciclam as sessões ociosas porque não veem o tráfego criptografado que o SSH manda por dentro. Desde a 3.6 a conexão leva keep-alive nas duas camadas e, se mesmo assim cortar, o aplicativo detecta o túnel morto e volta sozinho a trabalhar em local em vez de encadear esperas por cada comando. Quando a rede volta, tenta de novo com esperas crescentes durante mais de dois minutos.

Se acontecer constantemente, veja se a sua VPN tem um tempo de inatividade agressivo.

contextcode não existe como comando

Depende de como você instalou: o .deb e o instalador .exe do Windows deixam o comando no PATH, mas o AppImage, o .dmg do macOS e o .msi não conseguem. O conserto é uma linha:

contextcode instalar-cli

Detalhe completo em Context Code pelo terminal. No Windows, lembre de abrir um terminal novo depois.

Não sei qual instalação estou usando

contextcode conexion

Ele diz a versão, o executável, as pastas de configuração e dados, o banco de dados e o estado do link remoto — e marca com (DESARROLLO) os builds de desenvolvimento, que usam pastas separadas. É a causa habitual de «editei a configuração e nada acontece»: você editou na outra instalação. Veja a página dele.

As automações não rodaram

Se o app estava fechado e o daemon (execução em segundo plano) estava inativo, as automações não rodam — ative-o no painel de Automações. A aba Histórico mostra cada execução com o seu detalhe.

Continua sem funcionar

Passe de novo pelo guia de boas-vindas (menu da sua conta → «Ver o guia de novo», ou Configurações → Geral): ele percorre idioma, IA, projeto e voz, e deixa o aplicativo pronto sem que você precise procurar nada.

Se mesmo assim falhar, reinicie o aplicativo (feche-o também pela bandeja do sistema) e tente de novo. Se o problema persistir, anote o texto exato do erro — com ele, o suporte (ou o seu próprio agente) vai muito mais longe.