Desde la documentación de solución de problemas

Reparar problemas comunes de OpenCode

Pasos oficiales de recuperación para una ventana de escritorio en blanco, un proveedor que falla y los reportes de antivirus de Windows que siguen apareciendo en el issue tracker. Hazlos en orden.

El escritorio no arranca

La mayoría de los crashes son un plugin, una caché mala o una URL de servidor personalizada. El sidecar sigue siendo el CLI de OpenCode.

1. Cierra por completo y vuelve a abrir. Si ves una pantalla de error, usa Restart y copia los detalles.
2. En macOS usa el menú OpenCode y luego Reload Webview cuando la UI esté en blanco o congelada.
3. Abre %USERPROFILE%\.config\opencode\opencode.jsonc (o ~/.config/opencode/opencode.jsonc) y pon "plugin": [].
4. Aparta %USERPROFILE%\.config\opencode\plugins y cualquier carpeta .opencode/plugins/, y luego vuelve a abrir.
5. Borra la caché en %USERPROFILE%\.cache\opencode (o ~/.cache/opencode) y arranca de nuevo.
6. En Windows, si la ventana queda en blanco, instala o actualiza Microsoft Edge WebView2.

Connection Failed o un splash trabado

1. En la pantalla Home haz clic en el nombre del servidor (el punto de estado) y Clear la URL de servidor por defecto.
2. Quita cualquier bloque server.port o server.hostname de opencode.json y vuelve a abrir.
3. Quita OPENCODE_PORT si apunta a un puerto ocupado.

Errores de proveedor

ProviderModelNotFoundError

1. Confirma que te autenticaste con /connect.
2. Nombra los modelos como provider/model, por ejemplo openai/gpt-4.1 o openrouter/google/gemini-2.5-flash.
3. Corre opencode models y elige un nombre que de verdad aparezca.

ProviderInitError

1. Confirma el bloque del proveedor en opencode.json.
2. Si sigue roto, borra %USERPROFILE%\.local\share\opencode (o ~/.local/share/opencode).
3. Corre /connect otra vez.

AI_APICallError

1. Limpia la caché de paquetes del proveedor en %USERPROFILE%\.cache\opencode.
2. Reinicia para que OpenCode reinstale los paquetes de OpenAI, Anthropic o Google que cachea en local.

Antivirus de Windows y Smart App Control

Esta es la queja que aparece como Wacatac, Kaspersky PDM y Event 3077. OpenCode extrae dependencias nativas a un directorio temporal en el primer arranque. Los motores heurísticos lo tratan como malware empaquetado. Los mantenedores firmaron CLI y escritorio desde v1.3.4. Builds npm posteriores igual dispararon algunas máquinas.

1. Prefiere el exe de escritorio firmado de download.html antes que un drop viejo de npm i -g opencode-ai.
2. Compara el SHA256 de opencode-desktop-win-x64.exe con 7e6e4bca1b243609172fa580520e72ed240627fc9c36a80763a6f29bd64b698f.
3. Si Defender ya puso en cuarentena una DLL con nombre aleatorio bajo Temp, restaura ese archivo solo cuando el hash coincida, y luego agrega la carpeta de instalación de OpenCode (no todo Temp) como exclusión.
4. No desactives Smart App Control. SAC ignora las exclusiones de Defender. Un build firmado es la reparación de verdad.
5. Si tienes que quedarte en npm un rato, fija una versión que sepas que funciona en vez de dejar que autoupdate baje la siguiente. El issue tracker documentó que autoupdate volvió a romper un pin que ya andaba.

Windows por WSL

1. Instala WSL desde la guía propia de Microsoft.
2. En la terminal de WSL corre el script de instalación, luego cd /mnt/c/Users/YourName/project y opencode.
3. Para escritorio más WSL: opencode serve --hostname 0.0.0.0 --port 4096, y luego conecta la app a http://localhost:4096. Pon OPENCODE_SERVER_PASSWORD cuando hagas bind a 0.0.0.0.
4. Prefiere un clone bajo el filesystem de Linux (por ejemplo ~/code/) cuando un disco de Windows se sienta lento.

Portapapeles de Linux y Wayland

1. X11: instala xclip o xsel.
2. Wayland: instala wl-clipboard. OpenCode lo prefiere cuando detecta Wayland.
3. Ventana en blanco o que se cae en Wayland: arranca con OC_ALLOW_WAYLAND=1. Si empeora, quita la variable y usa una sesión X11.

Buenas prácticas de la intro

Haz commit de AGENTS.md: Después de /init, mete el archivo al repo para que cada sesión vea las mismas notas de arquitectura.
Plan, luego Build: Pasa con Tab a Plan para un cambio de varios archivos. Itera el plan. Vuelve con Tab a Build solo cuando quieras escrituras.
Nombra los archivos: Usa @ en vez de "el archivo de auth". El ejemplo de la intro apunta a una ruta concreta bajo packages/functions.
Lee los logs primero: Windows: Win+R, luego %USERPROFILE%\.local\share\opencode\log. macOS/Linux: ~/.local/share/opencode/log/. Usa opencode --log-level DEBUG o --print-logs.