1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
---
title: Solución de problemas
description: Problemas comunes y cómo resolverlos.
---
Para depurar problemas con OpenCode, comience verificando los registros y los datos locales que almacena en el disco.
---
## Registros
Los archivos de registro se escriben en:
- **macOS/Linux**: `~/.local/share/opencode/log/`
- **Windows**: Presione `WIN+R` y pegue `%USERPROFILE%\.local\share\opencode\log`
Los archivos de registro reciben nombres con marcas de tiempo (por ejemplo, `2025-01-09T123456.log`) y se conservan los 10 archivos de registro más recientes.
Puede configurar el nivel de registro 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 aplicaciones en el disco en:
- **macOS/Linux**: `~/.local/share/opencode/`
- **Windows**: Presione `WIN+R` y pegue `%USERPROFILE%\.local\share\opencode`
Este directorio contiene:
- `auth.json` - Datos de autenticación como API claves, OAuth tokens
- `log/` - Registros de aplicaciones
- `project/` - Datos específicos del proyecto, como datos de sesión y mensajes.
- Si el proyecto está dentro de un repositorio de Git, se almacena en `./<project-slug>/storage/`
- Si no es un repositorio de 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 se deben a un complemento que no funciona correctamente, una memoria caché dañada o una mala configuración del servidor.
### Comprobaciones rápidas
- Salga por completo y reinicie la aplicación.
- Si la aplicación muestra una pantalla de error, haga clic en **Reiniciar** y copie los detalles del error.
- Solo macOS: menú `OpenCode` -> **Recargar vista web** (ayuda si la interfaz de usuario está en blanco/congelada).
---
### Deshabilitar complementos
Si la aplicación de escritorio falla al iniciarse, se bloquea o se comporta de manera extraña, comience por deshabilitar los complementos.
#### Verifique la configuración global
Abra su archivo de configuración global y busque una clave `plugin`.
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc` (o `~/.config/opencode/opencode.json`)
- **macOS/Linux** (instalaciones anteriores): `~/.local/share/opencode/opencode.jsonc`
- **Windows**: Presione `WIN+R` y pegue `%USERPROFILE%\.config\opencode\opencode.jsonc`
Si tiene complementos configurados, desactívelos temporalmente eliminando la clave o configurándola en una matriz vacía:
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"plugin": [],
}
```
#### Verificar directorios de complementos
OpenCode también puede cargar complementos locales desde el disco. Quítelos temporalmente del camino (o cambie el nombre de la carpeta) y reinicie la aplicación de escritorio:
- **Complementos globales**
- **macOS/Linux**: `~/.config/opencode/plugins/`
- **Windows**: Presione `WIN+R` y pegue `%USERPROFILE%\.config\opencode\plugins`
- **Complementos de proyecto** (solo si usas la configuración por proyecto)
- `<your-project>/.opencode/plugins/`
Si la aplicación comienza a funcionar nuevamente, vuelva a habilitar los complementos uno a la vez para encontrar cuál está causando el problema.
---
### Borrar el caché
Si deshabilitar los complementos no ayuda (o la instalación de un complemento está bloqueada), borre el caché para que OpenCode pueda reconstruirlo.
1. Salga de OpenCode Desktop por completo.
2. Elimine el directorio de caché:
- **macOS**: Buscador -> `Cmd+Shift+G` -> pegar `~/.cache/opencode`
- **Linux**: eliminar `~/.cache/opencode` (o ejecutar `rm -rf ~/.cache/opencode`)
- **Windows**: Presione `WIN+R` y pegue `%USERPROFILE%\.cache\opencode`
3. Reinicie el escritorio OpenCode.
---
### Solucionar problemas de conexión del servidor
OpenCode Desktop puede iniciar su propio servidor local (predeterminado) o conectarse a la URL de un servidor que haya configurado.
Si ve un cuadro de diálogo **"Error de conexión"** (o la aplicación nunca pasa de la pantalla de inicio), busque una URL de servidor personalizada.
#### Borrar la URL del servidor predeterminado del escritorio
Desde la pantalla de inicio, haga clic en el nombre del servidor (con el punto de estado) para abrir el selector de servidor. En la sección **Servidor predeterminado**, haga clic en **Borrar**.
#### Elimina `server.port` / `server.hostname` de tu configuración
Si su `opencode.json(c)` contiene una sección `server`, elimínela temporalmente y reinicie la aplicación de escritorio.
#### Verificar variables de entorno
Si tiene `OPENCODE_PORT` configurado en su entorno, la aplicación de escritorio intentará usar ese puerto para el servidor local.
- Desarme `OPENCODE_PORT` (o elija un puerto libre) y reinicie.
---
### Linux: Problemas con Wayland/X11
En Linux, algunas configuraciones de Wayland pueden causar ventanas en blanco o errores de compositor.
- Si estás en Wayland y la aplicación está en blanco o falla, intenta iniciarla con `OC_ALLOW_WAYLAND=1`.
- Si eso empeora las cosas, elimínelo e intente iniciarlo en una sesión X11.
---
### Windows: tiempo de ejecución de WebView2
En Windows, el escritorio OpenCode requiere Microsoft Edge **WebView2 Runtime**. Si la aplicación se abre en una ventana en blanco o no se inicia, instale/actualice WebView2 e inténtelo nuevamente.
---
### Windows: Problemas generales de rendimiento
Si tiene un rendimiento lento, problemas de acceso a archivos o problemas de terminal en Windows, intente usar [WSL (Windows Subsistema para Linux)](/docs/windows-wsl). WSL proporciona un entorno Linux que funciona de manera más fluida con las funciones de OpenCode.
---
### Notificaciones que no se muestran
OpenCode Desktop solo muestra notificaciones del sistema cuando:
- las notificaciones están habilitadas para OpenCode en la configuración de su sistema operativo, y
- la ventana de la aplicación no está enfocada.
---
### Restablecer el almacenamiento de la aplicación de escritorio (último recurso)
Si la aplicación no se inicia y no puede borrar la configuración desde la interfaz de usuario, restablezca el estado guardado de la aplicación de escritorio.
1. Salga del escritorio OpenCode.
2. Busque y elimine estos archivos (se encuentran en el directorio de datos de la aplicación de escritorio OpenCode):
- `opencode.settings.dat` (URL del servidor predeterminado de escritorio)
- `opencode.global.dat` y `opencode.workspace.*.dat` (estado de la interfaz de usuario como servidores/proyectos recientes)
Para encontrar el directorio rápidamente:
- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support` (luego busque los nombres de archivo arriba)
- **Linux**: busque en `~/.local/share` los nombres de archivo anteriores
- **Windows**: Presione `WIN+R` -> `%APPDATA%` (luego busque los nombres de archivo arriba)
---
## Obtener ayuda
Si tiene problemas con OpenCode:
1. **Informar problemas el GitHub**
La mejor manera de informar errores o solicitar funciones es a través de nuestro repositorio GitHub:
[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
Antes de crear un nuevo problema, busque los problemas existentes para ver si su problema ya ha sido informado.
2. **Únete a nuestro Discord**
Para obtener ayuda en tiempo real y debates comunitarios, únase a nuestro servidor de Discord:
[**opencode.ai/discord**](https://opencode.ai/discord)
---
## Problemas comunes
A continuación se detallan algunos problemas comunes y cómo resolverlos.
---
### OpenCode no se inicia
1. Verifique los registros en busca de mensajes de error.
2. Intente ejecutar con `--print-logs` para ver el resultado en la terminal.
3. Asegúrese de tener la última versión con `opencode upgrade`
---
### Problemas de autenticación
1. Intente volver a autenticarse con el comando `/connect` en TUI
2. Verifique que sus claves API sean válidas
3. Asegúrese de que su red permita conexiones al API del proveedor.
---
### Modelo no disponible
1. Comprueba que te has autenticado con el proveedor.
2. Verifique que el nombre del modelo en su configuración sea correcto
3. Algunos modelos pueden requerir acceso o suscripciones específicas
Si encuentra `ProviderModelNotFoundError`, lo más probable es que esté equivocado.
haciendo referencia a un modelo en alguna parte.
Se debe hacer referencia a los modelos así: `<providerId>/<modelId>`
Ejemplos:
- `openai/gpt-4.1`
- `openrouter/google/gemini-2.5-flash`
- `opencode/kimi-k2`
Para saber a qué modelos tiene acceso, ejecute `opencode models`
---
### Error de inicio del proveedor
Si encuentra un ProviderInitError, es probable que tenga una configuración no válida o dañada.
Para resolver esto:
1. Primero, verifique que su proveedor esté configurado correctamente siguiendo la [guía de proveedores](/docs/providers)
2. Si el problema persiste, intente borrar la configuración almacenada:
```bash
rm -rf ~/.local/share/opencode
```
En Windows, presione `WIN+R` y elimine: `%USERPROFILE%\.local\share\opencode`
3. Vuelva a autenticarse con su proveedor utilizando el comando `/connect` en TUI.
---
### AI_APICallError y problemas con el paquete del proveedor
Si encuentra errores de llamada API, esto puede deberse a paquetes de proveedores obsoletos. opencode instala dinámicamente paquetes de proveedores (OpenAI, Anthropic, Google, etc.) según sea necesario y los almacena en caché localmente.
Para resolver problemas con el paquete del proveedor:
1. Borre la caché del paquete del proveedor:
```bash
rm -rf ~/.cache/opencode
```
En Windows, presione `WIN+R` y elimine: `%USERPROFILE%\.cache\opencode`
2. Reinicie opencode para reinstalar los paquetes del proveedor más recientes.
Esto obligará a opencode a descargar las versiones más recientes de los paquetes del proveedor, lo que a menudo resuelve problemas de compatibilidad con los parámetros del modelo y los cambios de API.
---
### Copiar/pegar no funciona en Linux
Los usuarios de Linux deben tener instalada una de las siguientes utilidades del portapapeles para que funcione la función copiar/pegar:
**Para sistemas X11:**
```bash
apt install -y xclip
# or
apt install -y xsel
```
**Para sistemas Wayland:**
```bash
apt install -y wl-clipboard
```
**Para entornos sin cabeza:**
```bash
apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0
```
opencode detectará si estás usando Wayland y prefieres `wl-clipboard`; de lo contrario, intentará encontrar herramientas del portapapeles en el orden de: `xclip` y `xsel`.
|
