Solución de Problemas

Problemas comunes y cómo resolverlos.

Para depurar problemas con OpenCode, comienza revisando los logs y los datos locales que almacena en disco.

Logs

Los archivos de log se escriben en:

macOS/Linux: ~/.local/share/opencode/log/
Windows: Presiona WIN+R y pega %USERPROFILE%\.local\share\opencode\log

Los archivos de log se nombran con marcas de tiempo (ej. 2025-01-09T123456.log) y se mantienen los 10 archivos de log más recientes.

Puedes establecer el nivel de log con la opción de línea de comandos --log-level para obtener información de depuración más detallada. Por ejemplo, opencode --log-level DEBUG.

Almacenamiento

opencode almacena datos de sesión y otros datos de la aplicación en disco en:

macOS/Linux: ~/.local/share/opencode/
Windows: Presiona WIN+R y pega %USERPROFILE%\.local\share\opencode

Este directorio contiene:

auth.json - Datos de autenticación como claves API, tokens OAuth
log/ - Logs de la aplicación
project/ - Datos específicos del proyecto como datos de sesión y mensajes
- Si el proyecto está dentro de un repositorio Git, se almacena en ./<project-slug>/storage/
- Si no es un repositorio Git, se almacena en ./global/storage/

Aplicación de escritorio

OpenCode Desktop ejecuta un servidor OpenCode local (el sidecar opencode-cli) en segundo plano. La mayoría de los problemas son causados por un plugin con mal funcionamiento, una caché corrupta o una configuración de servidor incorrecta.

Verificaciones rápidas

Cierra completamente y reinicia la aplicación.
Si la aplicación muestra una pantalla de error, haz clic en Reiniciar y copia los detalles del error.
Solo macOS: menú OpenCode -> Recargar Webview (ayuda si la UI está en blanco/congelada).

Deshabilitar plugins

Si la aplicación de escritorio se bloquea al iniciar, se cuelga o se comporta de manera extraña, comienza deshabilitando los plugins.

Verificar la configuración global

Abre tu archivo de configuración global y busca una clave plugin.

macOS/Linux: ~/.config/opencode/opencode.jsonc (o ~/.config/opencode/opencode.json)
macOS/Linux (instalaciones antiguas): ~/.local/share/opencode/opencode.jsonc
Windows: Presiona WIN+R y pega %USERPROFILE%\.config\opencode\opencode.jsonc

Si tienes plugins configurados, deshabilítalos temporalmente eliminando la clave o estableciéndola como un array vacío:

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

Verificar directorios de plugins

OpenCode también puede cargar plugins locales desde disco. Mueve estos temporalmente (o renombra la carpeta) y reinicia la aplicación de escritorio:

Plugins globales
- macOS/Linux: ~/.config/opencode/plugins/
- Windows: Presiona WIN+R y pega %USERPROFILE%\.config\opencode\plugins
Plugins de proyecto (solo si usas configuración por proyecto)
- <your-project>/.opencode/plugins/

Si la aplicación comienza a funcionar de nuevo, vuelve a habilitar los plugins uno por uno para encontrar cuál está causando el problema.

Limpiar la caché

Si deshabilitar plugins no ayuda (o una instalación de plugin está atascada), limpia la caché para que OpenCode pueda reconstruirla.

Cierra OpenCode Desktop completamente.
Elimina el directorio de caché:

macOS: Finder -> Cmd+Shift+G -> pega ~/.cache/opencode
Linux: elimina ~/.cache/opencode (o ejecuta rm -rf ~/.cache/opencode)
Windows: Presiona WIN+R y pega %USERPROFILE%\.cache\opencode

Reinicia OpenCode Desktop.

Solucionar problemas de conexión del servidor

OpenCode Desktop puede iniciar su propio servidor local (predeterminado) o conectarse a una URL de servidor que hayas configurado.

Si ves un diálogo de Conexión Fallida (o la aplicación nunca pasa de la pantalla de inicio), verifica si hay una URL de servidor personalizada.

Limpiar la URL del servidor predeterminado del escritorio

Desde la pantalla de inicio, haz clic en el nombre del servidor (con el punto de estado) para abrir el selector de servidor. En la sección Servidor predeterminado, haz clic en Limpiar.

Eliminar `server.port` / `server.hostname` de tu configuración

Si tu opencode.json(c) contiene una sección server, elimínala temporalmente y reinicia la aplicación de escritorio.

Verificar variables de entorno

Si tienes OPENCODE_PORT establecido en tu entorno, la aplicación de escritorio intentará usar ese puerto para el servidor local.

Elimina OPENCODE_PORT (o elige un puerto libre) y reinicia.

Linux: Problemas de Wayland / X11

En Linux, algunas configuraciones de Wayland pueden causar ventanas en blanco o errores del compositor.

Si estás en Wayland y la aplicación está en blanco/se bloquea, intenta iniciar con OC_ALLOW_WAYLAND=1.
Si eso empeora las cosas, elimínalo e intenta iniciar bajo una sesión X11 en su lugar.

Windows: Runtime WebView2

En Windows, OpenCode Desktop requiere el WebView2 Runtime de Microsoft Edge. Si la aplicación se abre con una ventana en blanco o no inicia, instala/actualiza WebView2 e intenta de nuevo.

Windows: Problemas generales de rendimiento

Si experimentas rendimiento lento, problemas de acceso a archivos o problemas de terminal en Windows, intenta usar WSL (Windows Subsystem for Linux). WSL proporciona un entorno Linux que funciona más fluidamente con las características de OpenCode.

Las notificaciones no se muestran

OpenCode Desktop solo muestra notificaciones del sistema cuando:

las notificaciones están habilitadas para OpenCode en la configuración de tu SO, y
la ventana de la aplicación no está enfocada.

Restablecer almacenamiento de la aplicación de escritorio (último recurso)

Si la aplicación no inicia y no puedes limpiar la configuración desde la UI, restablece el estado guardado de la aplicación de escritorio.

Cierra OpenCode Desktop.
Encuentra y elimina estos archivos (están en el directorio de datos de la aplicación OpenCode Desktop):

opencode.settings.dat (URL del servidor predeterminado del escritorio)
opencode.global.dat y opencode.workspace.*.dat (estado de la UI como servidores/proyectos recientes)

Para encontrar el directorio rápidamente:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (luego busca los nombres de archivo anteriores)
Linux: busca bajo ~/.local/share los nombres de archivo anteriores
Windows: Presiona WIN+R -> %APPDATA% (luego busca los nombres de archivo anteriores)

Obtener ayuda

Si tienes problemas con OpenCode:

Reportar problemas en GitHub

La mejor manera de reportar bugs o solicitar características es a través de nuestro repositorio de GitHub:

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

Antes de crear un nuevo issue, busca en los issues existentes para ver si tu problema ya ha sido reportado.
Únete a nuestro Discord

Para ayuda en tiempo real y discusión comunitaria, únete a nuestro servidor de Discord:

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

Problemas comunes

Aquí hay algunos problemas comunes y cómo resolverlos.

OpenCode no inicia

Revisa los logs en busca de mensajes de error
Intenta ejecutar con --print-logs para ver la salida en la terminal
Asegúrate de tener la última versión con opencode upgrade

Problemas de autenticación

Intenta re-autenticarte con el comando /connect en la TUI
Verifica que tus claves API sean válidas
Asegúrate de que tu red permita conexiones a la API del proveedor

Modelo no disponible

Verifica que te hayas autenticado con el proveedor
Verifica que el nombre del modelo en tu configuración sea correcto
Algunos modelos pueden requerir acceso específico o suscripciones

Si encuentras ProviderModelNotFoundError, lo más probable es que estés referenciando incorrectamente un modelo en algún lugar. Los modelos deben referenciarse así: <providerId>/<modelId>

Ejemplos:

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
opencode/kimi-k2

Para saber a qué modelos tienes acceso, ejecuta opencode models

ProviderInitError

Si encuentras un ProviderInitError, probablemente tengas una configuración inválida o corrupta.

Para resolver esto:

Primero, verifica que tu proveedor esté configurado correctamente siguiendo la guía de proveedores
Si el problema persiste, intenta limpiar tu configuración almacenada:
```
rm -rf ~/.local/share/opencode
```
En Windows, presiona WIN+R y elimina: %USERPROFILE%\.local\share\opencode
Re-autentícate con tu proveedor usando el comando /connect en la TUI.

AI_APICallError y problemas de paquetes de proveedor

Si encuentras errores de llamada API, esto puede deberse a paquetes de proveedor desactualizados. opencode instala dinámicamente paquetes de proveedor (OpenAI, Anthropic, Google, etc.) según sea necesario y los almacena en caché localmente.

Para resolver problemas de paquetes de proveedor:

Limpia la caché de paquetes de proveedor:
```
rm -rf ~/.cache/opencode
```
En Windows, presiona WIN+R y elimina: %USERPROFILE%\.cache\opencode
Reinicia opencode para reinstalar los últimos paquetes de proveedor

Esto forzará a opencode a descargar las versiones más recientes de los paquetes de proveedor, lo que a menudo resuelve problemas de compatibilidad con parámetros de modelo y cambios de API.

Copiar/pegar no funciona en Linux

Los usuarios de Linux necesitan tener instalada una de las siguientes utilidades de portapapeles para que la funcionalidad de copiar/pegar funcione:

Para sistemas X11:

apt install -y xclip
# o
apt install -y xsel

Para sistemas Wayland:

apt install -y wl-clipboard

Para entornos headless:

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

opencode detectará si estás usando Wayland y preferirá wl-clipboard, de lo contrario intentará encontrar herramientas de portapapeles en orden: xclip y xsel.

Enterprise Windows (WSL)