Solução de Problemas

Problemas comuns e como resolvê-los.

Para depurar problemas com o opencode, comece verificando os logs e os dados locais que ele armazena no disco.

Logs

Os arquivos de log são gravados em:

macOS/Linux: ~/.local/share/opencode/log/
Windows: Pressione WIN+R e cole %USERPROFILE%\.local\share\opencode\log

Os arquivos de log são nomeados com timestamps (por exemplo, 2025-01-09T123456.log) e os 10 arquivos de log mais recentes são mantidos.

Você pode definir o nível de log com a opção de linha de comando --log-level para obter informações de depuração mais detalhadas. Por exemplo, opencode --log-level DEBUG.

Armazenamento

opencode armazena dados de sessão e outros dados do aplicativo no disco em:

macOS/Linux: ~/.local/share/opencode/
Windows: Pressione WIN+R e cole %USERPROFILE%\.local\share\opencode

Este diretório contém:

auth.json - Dados de autenticação como chaves de API, tokens OAuth
log/ - Logs do aplicativo
project/ - Dados específicos do projeto, como dados de sessão e mensagens
- Se o projeto estiver dentro de um repositório Git, ele é armazenado em ./<project-slug>/storage/
- Se não for um repositório Git, ele é armazenado em ./global/storage/

opencode Desktop executa um servidor opencode local (o sidecar opencode-cli) em segundo plano. A maioria dos problemas é causada por um plugin com mau funcionamento, um cache corrompido ou uma configuração de servidor incorreta.

Verificações rápidas

Saia completamente do aplicativo e reinicie-o.
Se o aplicativo mostrar uma tela de erro, clique em Reiniciar e copie os detalhes do erro.
Apenas macOS: menu OpenCode -> Recarregar Webview (ajuda se a interface estiver em branco/congelada).

Desativar plugins

Se o aplicativo de desktop estiver travando ao iniciar, pendurado ou se comportando de maneira estranha, comece desativando os plugins.

Verifique a configuração global

Abra seu arquivo de configuração global e procure uma chave plugin.

macOS/Linux: ~/.config/opencode/opencode.jsonc (ou ~/.config/opencode/opencode.json)
macOS/Linux (instalações mais antigas): ~/.local/share/opencode/opencode.jsonc
Windows: Pressione WIN+R e cole %USERPROFILE%\.config\opencode\opencode.jsonc

Se você tiver plugins configurados, desative-os temporariamente removendo a chave ou definindo-a como um array vazio:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

Verifique os diretórios de plugins

opencode também pode carregar plugins locais do disco. Mova-os temporariamente para fora do caminho (ou renomeie a pasta) e reinicie o aplicativo de desktop:

Plugins globais
- macOS/Linux: ~/.config/opencode/plugins/
- Windows: Pressione WIN+R e cole %USERPROFILE%\.config\opencode\plugins
Plugins de projeto (apenas se você usar configuração por projeto)
- <your-project>/.opencode/plugins/

Se o aplicativo voltar a funcionar, reative os plugins um por um para descobrir qual está causando o problema.

Limpar o cache

Se desativar plugins não ajudar (ou se a instalação de um plugin estiver travada), limpe o cache para que o opencode possa reconstruí-lo.

Saia completamente do opencode Desktop.
Exclua o diretório de cache:

macOS: Finder -> Cmd+Shift+G -> cole ~/.cache/opencode
Linux: exclua ~/.cache/opencode (ou execute rm -rf ~/.cache/opencode)
Windows: Pressione WIN+R e cole %USERPROFILE%\.cache\opencode

Reinicie o opencode Desktop.

Corrigir problemas de conexão com o servidor

opencode Desktop pode iniciar seu próprio servidor local (padrão) ou conectar-se a uma URL de servidor que você configurou.

Se você ver um diálogo “Conexão Falhou” (ou o aplicativo nunca passa da tela de inicialização), verifique se há uma URL de servidor personalizada.

Limpar a URL do servidor padrão do desktop

Na tela inicial, clique no nome do servidor (com o ponto de status) para abrir o seletor de Servidor. Na seção Servidor padrão, clique em Limpar.

Remover `server.port` / `server.hostname` da sua configuração

Se seu opencode.json(c) contiver uma seção server, remova-a temporariamente e reinicie o aplicativo de desktop.

Verifique as variáveis de ambiente

Se você tiver OPENCODE_PORT definido em seu ambiente, o aplicativo de desktop tentará usar essa porta para o servidor local.

Desfaça OPENCODE_PORT (ou escolha uma porta livre) e reinicie.

Linux: Problemas com Wayland / X11

No Linux, algumas configurações do Wayland podem causar janelas em branco ou erros de compositor.

Se você estiver no Wayland e o aplicativo estiver em branco/travando, tente iniciar com OC_ALLOW_WAYLAND=1.
Se isso piorar as coisas, remova e tente iniciar sob uma sessão X11.

Windows: WebView2 runtime

No Windows, o opencode Desktop requer o WebView2 Runtime do Microsoft Edge. Se o aplicativo abrir em uma janela em branco ou não iniciar, instale/atualize o WebView2 e tente novamente.

Windows: Problemas gerais de desempenho

Se você estiver enfrentando desempenho lento, problemas de acesso a arquivos ou problemas no terminal no Windows, tente usar WSL (Windows Subsystem for Linux). O WSL fornece um ambiente Linux que funciona de forma mais integrada com os recursos do opencode.

Notificações não aparecendo

O opencode Desktop só mostra notificações do sistema quando:

as notificações estão habilitadas para o opencode nas configurações do seu sistema operacional, e
a janela do aplicativo não está focada.

Redefinir o armazenamento do aplicativo de desktop (último recurso)

Se o aplicativo não iniciar e você não conseguir limpar as configurações pela interface, redefina o estado salvo do aplicativo de desktop.

Saia do opencode Desktop.
Encontre e exclua estes arquivos (eles estão no diretório de dados do aplicativo opencode Desktop):

opencode.settings.dat (URL do servidor padrão do desktop)
opencode.global.dat e opencode.workspace.*.dat (estado da interface como servidores/projetos recentes)

Para encontrar o diretório rapidamente:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (depois pesquise pelos nomes dos arquivos acima)
Linux: pesquise em ~/.local/share pelos nomes dos arquivos acima
Windows: Pressione WIN+R -> %APPDATA% (depois pesquise pelos nomes dos arquivos acima)

Obtendo ajuda

Se você estiver enfrentando problemas com o opencode:

Relatar problemas no GitHub

A melhor maneira de relatar bugs ou solicitar recursos é através do nosso repositório no GitHub:

github.com/anomalyco/opencode/issues

Antes de criar um novo problema, pesquise problemas existentes para ver se seu problema já foi relatado.
Junte-se ao nosso Discord

Para ajuda em tempo real e discussão da comunidade, junte-se ao nosso servidor Discord:

opencode.ai/discord

Problemas comuns

Aqui estão alguns problemas comuns e como resolvê-los.

opencode não inicia

Verifique os logs em busca de mensagens de erro
Tente executar com --print-logs para ver a saída no terminal
Certifique-se de que você tem a versão mais recente com opencode upgrade

Problemas de autenticação

Tente reautenticar com o comando /connect na TUI
Verifique se suas chaves de API são válidas
Certifique-se de que sua rede permite conexões com a API do provedor

Modelo não disponível

Verifique se você se autenticou com o provedor
Verifique se o nome do modelo em sua configuração está correto
Alguns modelos podem exigir acesso ou assinaturas específicas

Se você encontrar ProviderModelNotFoundError, é mais provável que você esteja referenciando um modelo incorretamente em algum lugar. Os modelos devem ser referenciados assim: <providerId>/<modelId>

Exemplos:

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
opencode/kimi-k2

Para descobrir quais modelos você tem acesso, execute opencode models

ProviderInitError

Se você encontrar um ProviderInitError, provavelmente você tem uma configuração inválida ou corrompida.

Para resolver isso:

Primeiro, verifique se seu provedor está configurado corretamente seguindo o guia de provedores
Se o problema persistir, tente limpar sua configuração armazenada:
Terminal window
```
rm -rf ~/.local/share/opencode
```
No Windows, pressione WIN+R e exclua: %USERPROFILE%\.local\share\opencode
Reautentique-se com seu provedor usando o comando /connect na TUI.

AI_APICallError e problemas com pacotes de provedores

Se você encontrar erros de chamada de API, isso pode ser devido a pacotes de provedores desatualizados. opencode instala dinamicamente pacotes de provedores (OpenAI, Anthropic, Google, etc.) conforme necessário e os armazena em cache localmente.

Para resolver problemas com pacotes de provedores:

Limpe o cache do pacote de provedores:
Terminal window
```
rm -rf ~/.cache/opencode
```
No Windows, pressione WIN+R e exclua: %USERPROFILE%\.cache\opencode
Reinicie o opencode para reinstalar os pacotes de provedores mais recentes

Isso forçará o opencode a baixar as versões mais recentes dos pacotes de provedores, o que muitas vezes resolve problemas de compatibilidade com parâmetros de modelo e alterações na API.

Copiar/colar não funciona no Linux

Usuários do Linux precisam ter um dos seguintes utilitários de área de transferência instalados para que a funcionalidade de copiar/colar funcione:

Para sistemas X11:

apt install -y xclip
# or
apt install -y xsel

Para sistemas Wayland:

apt install -y wl-clipboard

Para ambientes sem cabeça:

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

opencode detectará se você está usando Wayland e preferirá wl-clipboard, caso contrário, tentará encontrar ferramentas de área de transferência na ordem: xclip e xsel.