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 (ex: 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

O 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, é armazenado em ./<project-slug>/storage/
- Se não for um repositório Git, é armazenado em ./global/storage/

Aplicativo Desktop

O 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

Feche completamente e reinicie o aplicativo.
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 UI estiver em branco/congelada).

Desabilitar plugins

Se o aplicativo desktop estiver travando na inicialização, congelando ou se comportando de forma estranha, comece desabilitando os plugins.

Verificar a configuração global

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

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

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

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

Verificar diretórios de plugins

O OpenCode também pode carregar plugins locais do disco. Mova-os temporariamente (ou renomeie a pasta) e reinicie o aplicativo 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 começar a funcionar novamente, reabilite os plugins um por um para encontrar qual está causando o problema.

Limpar o cache

Se desabilitar plugins não ajudar (ou uma instalação de plugin estiver travada), limpe o cache para que o OpenCode possa reconstruí-lo.

Feche o OpenCode Desktop completamente.
Delete o diretório de cache:

macOS: Finder -> Cmd+Shift+G -> cole ~/.cache/opencode
Linux: delete ~/.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 do servidor

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

Se você vir um diálogo de Conexão Falhou (ou o aplicativo nunca passar da tela de splash), 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 desktop.

Verificar variáveis de ambiente

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

Remova 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 do 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-o e tente iniciar em uma sessão X11.

Windows: Runtime WebView2

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

Windows: Problemas gerais de desempenho

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

Notificações não aparecem

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

as notificações estão habilitadas para o OpenCode nas configurações do seu SO, e
a janela do aplicativo não está em foco.

Resetar armazenamento do aplicativo desktop (último recurso)

Se o aplicativo não iniciar e você não conseguir limpar as configurações de dentro da UI, resete o estado salvo do aplicativo desktop.

Feche o OpenCode Desktop.
Encontre e delete 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 UI como servidores/projetos recentes)

Para encontrar o diretório rapidamente:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (então procure pelos nomes de arquivo acima)
Linux: procure em ~/.local/share pelos nomes de arquivo acima
Windows: Pressione WIN+R -> %APPDATA% (então procure pelos nomes de arquivo acima)

Obtendo ajuda

Se você estiver tendo problemas com o OpenCode:

Reportar problemas no GitHub

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

github.com/anomalyco/opencode/issues (opens in a new tab)

Antes de criar uma nova issue, pesquise as issues existentes para ver se seu problema já foi reportado.
Junte-se ao nosso Discord

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

opencode.ai/discord (opens in a new tab)

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 ter a versão mais recente com opencode upgrade

Problemas de autenticação

Tente re-autenticar 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 na sua configuração está correto
Alguns modelos podem exigir acesso específico ou assinaturas

Se você encontrar ProviderModelNotFoundError, provavelmente está referenciando incorretamente um modelo 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 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:
```
rm -rf ~/.local/share/opencode
```
No Windows, pressione WIN+R e delete: %USERPROFILE%\.local\share\opencode
Re-autentique com seu provedor usando o comando /connect na TUI.

AI_APICallError e problemas de pacotes de provedor

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

Para resolver problemas de pacotes de provedor:

Limpe o cache de pacotes de provedor:
```
rm -rf ~/.cache/opencode
```
No Windows, pressione WIN+R e delete: %USERPROFILE%\.cache\opencode
Reinicie o opencode para reinstalar os pacotes de provedor mais recentes

Isso forçará o opencode a baixar as versões mais recentes dos pacotes de provedor, o que frequentemente resolve problemas de compatibilidade com parâmetros de modelo e mudanças de API.

Copiar/colar não funciona no Linux

Usuários 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
# ou
apt install -y xsel

Para sistemas Wayland:

apt install -y wl-clipboard

Para ambientes headless:

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

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

Enterprise Windows (WSL)