@neurocode-ai/web 1.18.8

package/src/content/docs/pt-br/troubleshooting.mdx

@@ -0,0 +1,299 @@
+---
+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
+
+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, ele é armazenado em `./<project-slug>/storage/`
+  - Se não for um repositório Git, ele é armazenado em `./global/storage/`
+
+---
+
+## Aplicativo de 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
+
+- 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).
+
+---
+
+### Desativando plugins
+
+Se o aplicativo de desktop estiver travando ao iniciar, pendurado ou se comportando de maneira estranha, comece desativando os plugins.
+
+#### Verificando 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": [],
+}
+```
+
+#### Verificando os diretórios de plugins
+
+O 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.
+
+---
+
+### Limpando 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.
+
+---
+
+### Corrigindo problemas de conexão com o 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ê 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.
+
+#### Limpando 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**.
+
+#### Removendo `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.
+
+#### Verificando 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: Runtime do WebView2
+
+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.
+
+---
+
+### Redefinindo 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.
+
+---
+
+### O 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. O 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
+# or
+apt install -y xsel
+```
+
+**Para sistemas Wayland:**
+
+```bash
+apt install -y wl-clipboard
+```
+
+**Para ambientes sem cabeça:**
+
+```bash
+apt install -y xvfb
+# and run:
+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`.