Pular para o conteúdo

Solução de problemas

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.

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.

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.

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.

Os servidores MCP lançados com python não deveriam mais falhar no Windows só porque python não está no PATH: o app usa o inicializador py ou o Python gerenciado pelo uv. Se o cartão continuar vermelho, leia a mensagem dele (exibida em espanhol):

  • «Falta Python…» (falta Python): não há nenhum Python utilizável no computador. Instale-o pelo python.org marcando “Add python.exe to PATH”, instale as dependências do servidor (por exemplo, py -m pip install mcp requests) e clique em Tentar de novo.
  • «Python SÍ arrancó: al servidor le falta un paquete…» (o Python iniciou: falta um pacote ao servidor): o Python funciona, mas falta uma dependência do servidor. Instale-a com py -m pip install … (o que o README do servidor indicar) e clique em Tentar de novo.

O atalho python.exe da Microsoft Store não conta como Python (ele abre a loja), então não basta. Mais detalhes em Skills, MCP e plugins.

Os servidores MCP remotos com Iniciar sessão renovam o token sozinhos quando ele expira e repetem a requisição, então normalmente você não vai notar nada. Se mesmo assim o servidor parar de responder ou pedir credenciais:

  1. Abra o cartão do servidor em Instalado e clique em Iniciar sessão.
  2. Autorize o acesso no navegador. O servidor é relançado sozinho e os chats que você já tinha abertos usam a sessão nova na próxima requisição: não é preciso abrir outro chat.

Se a renovação falhar repetidamente, confira na sua conta do serviço se você não revogou o acesso do Context Code.

Não é um erro. Esse servidor faz algo que o Context Code já traz integrado (arquivos, git, web, memória, bancos de dados, navegador ou grafo de código), por isso foi retirado do catálogo e o cartão o marca em âmbar com a explicação de qual função o substitui. Ele não é desinstalado sozinho: você pode removê-lo com o botão da lixeira (Remover) no cartão, já que não é mais necessário, ou mantê-lo. A lista completa está em Skills, MCP e plugins.

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

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.

  • «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.

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)

Seção intitulada “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.

Se ao clicar em “Obter URL estável (1 clique)” aparecer «Inicia sesión con tu cuenta de Context Code para obtener la URL estable de este equipo.» (Entre com a sua conta do Context Code para obter a URL estável deste computador), o app não tem uma sessão iniciada. Entre com a sua conta do Context Code e clique no botão de novo: não é mais necessária nenhuma chave do broker de túneis. A URL que você obtém é só para este computador. Veja Acesso web por QR code.

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

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.

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:

Ventana de terminal
contextcode instalar-cli

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

Ventana de terminal
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.

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.

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.