299 lines
10 KiB
Plaintext
299 lines
10 KiB
Plaintext
---
|
|
title: Solução de Problemas
|
|
description: 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/`
|
|
|
|
---
|
|
|
|
## Aplicativo de Desktop
|
|
|
|
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:
|
|
|
|
```jsonc
|
|
{
|
|
"$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)
|
|
- `<seu-projeto>/.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.
|
|
|
|
1. Saia completamente do OpenCode Desktop.
|
|
2. 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`
|
|
|
|
3. 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)](/docs/windows-wsl). 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.
|
|
|
|
1. Saia do OpenCode Desktop.
|
|
2. 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:
|
|
|
|
1. **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**](https://github.com/anomalyco/opencode/issues)
|
|
|
|
Antes de criar um novo problema, pesquise problemas existentes para ver se seu problema já foi relatado.
|
|
|
|
2. **Junte-se ao nosso Discord**
|
|
|
|
Para ajuda em tempo real e discussão da comunidade, junte-se ao nosso servidor Discord:
|
|
|
|
[**opencode.ai/discord**](https://opencode.ai/discord)
|
|
|
|
---
|
|
|
|
## Problemas comuns
|
|
|
|
Aqui estão alguns problemas comuns e como resolvê-los.
|
|
|
|
---
|
|
|
|
### OpenCode não inicia
|
|
|
|
1. Verifique os logs em busca de mensagens de erro
|
|
2. Tente executar com `--print-logs` para ver a saída no terminal
|
|
3. Certifique-se de que você tem a versão mais recente com `opencode upgrade`
|
|
|
|
---
|
|
|
|
### Problemas de autenticação
|
|
|
|
1. Tente reautenticar com o comando `/connect` na TUI
|
|
2. Verifique se suas chaves de API são válidas
|
|
3. Certifique-se de que sua rede permite conexões com a API do provedor
|
|
|
|
---
|
|
|
|
### Modelo não disponível
|
|
|
|
1. Verifique se você se autenticou com o provedor
|
|
2. Verifique se o nome do modelo em sua configuração está correto
|
|
3. 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:
|
|
|
|
1. Primeiro, verifique se seu provedor está configurado corretamente seguindo o [guia de provedores](/docs/providers)
|
|
2. Se o problema persistir, tente limpar sua configuração armazenada:
|
|
|
|
```bash
|
|
rm -rf ~/.local/share/opencode
|
|
```
|
|
|
|
No Windows, pressione `WIN+R` e exclua: `%USERPROFILE%\.local\share\opencode`
|
|
|
|
3. 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:
|
|
|
|
1. Limpe o cache do pacote de provedores:
|
|
|
|
```bash
|
|
rm -rf ~/.cache/opencode
|
|
```
|
|
|
|
No Windows, pressione `WIN+R` e exclua: `%USERPROFILE%\.cache\opencode`
|
|
|
|
2. 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:**
|
|
|
|
```bash
|
|
apt install -y xclip
|
|
# ou
|
|
apt install -y xsel
|
|
```
|
|
|
|
**Para sistemas Wayland:**
|
|
|
|
```bash
|
|
apt install -y wl-clipboard
|
|
```
|
|
|
|
**Para ambientes sem cabeça:**
|
|
|
|
```bash
|
|
apt install -y xvfb
|
|
# e execute:
|
|
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`. |