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 da aplicação 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 e tokens OAuth
log/ - Logs da aplicação
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/

App 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 app.
Se o app mostrar uma tela de erro, clique em Restart e copie os detalhes do erro.
Apenas macOS: menu OpenCode -> Reload Webview (ajuda se a UI estiver em branco/congelada).

Desativar plugins

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

Verificar a config global

Abra seu arquivo de config 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, desative-os temporariamente removendo a chave ou definindo-a como um array vazio:

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

Verificar os diretórios de plugins

O OpenCode também pode carregar plugins locais do disco. Mova-os temporariamente (ou renomeie a pasta) e reinicie o app 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 config por projeto)
- <your-project>/.opencode/plugins/

Se o app voltar a funcionar, reative os plugins um de cada vez para descobrir qual deles está causando o problema.

Limpar o cache

Se desativar os 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.
Apague o diretório de cache:

macOS : Finder -> Cmd+Shift+G -> cole ~/.cache/opencode
Linux : apague ~/.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 "Connection Failed" (ou o app 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 Default server, clique em Clear.

Remover `server.port` / `server.hostname` da sua config

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

Verificar variáveis de ambiente

Se você tiver OPENCODE_PORT definida no seu ambiente, o app 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ê está no Wayland e o app está 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 app 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 enfrentando desempenho lento, problemas de acesso a arquivos ou problemas de terminal no Windows, tente usar o WSL (Windows Subsystem for Linux). O WSL oferece um ambiente Linux que funciona de forma mais integrada 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 ativadas para o OpenCode nas configurações do seu SO, e
a janela do app não está em foco.

Resetar o armazenamento do app desktop (último recurso)

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

Feche o OpenCode Desktop.
Encontre e apague estes arquivos (eles ficam no diretório de dados do app 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 (depois procure pelos nomes de arquivo acima)
Linux : procure em ~/.local/share pelos nomes de arquivo acima
Windows : Pressione WIN+R -> %APPDATA% (depois procure pelos nomes de arquivo acima)

Obtendo ajuda

Se você estiver enfrentando problemas com o OpenCode:

Reporte problemas no GitHub A melhor maneira de reportar bugs ou solicitar recursos é pelo nosso repositório no GitHub: github.com/anomalyco/opencode/issues (opens in a new tab) Antes de criar uma nova issue, pesquise as issues existentes para ver se o seu problema já foi reportado.
Junte-se ao nosso Discord Para ajuda em tempo real e discussão com a comunidade, junte-se ao nosso servidor no Discord: opencode.ai/discord (opens in a new tab)

Problemas comuns

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

O 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 se reautenticar com o comando /connect na TUI
Verifique se as suas chaves de API são válidas
Certifique-se de que a 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 config está correto
Alguns modelos podem exigir acesso ou assinaturas específicas

Se você encontrar ProviderModelNotFoundError, provavelmente está 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 tem uma config inválida ou corrompida.

Para resolver isso:

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

AI_APICallError e problemas com pacotes de provedor

Se você encontrar erros de chamada de API, isso pode ser causado por 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 com pacotes de provedor:

Limpe o cache de pacotes de provedor:
```
rm -rf ~/.cache/opencode
```
No Windows, pressione WIN+R e apague: %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 muitas vezes resolve problemas de compatibilidade com parâmetros de modelo e mudanças de API.

Copiar/colar não funciona no Linux

Os usuários de 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á o wl-clipboard; caso contrário, tentará encontrar ferramentas de área de transferência na ordem: xclip e xsel.

Enterprise Windows (WSL)