OpenCode no funciona: arregla el PATH, la pantalla en negro y los errores de modelos
Una lista de arreglos con el diagnóstico primero para OpenCode — "command not found" en Windows, ventanas de terminal en negro, errores de límite gratuito y de proveedores, una lista de modelos que parece incompleta y la extensión de VS Code — cada arreglo mostrado en una grabación real.
Respuestas rápidas
- ¿"opencode: command not found" justo después de instalar? A la carpeta bin del instalador le falta estar en el PATH — expórtala en el perfil de tu shell (el vídeo añade la ruta .opencode/bin para Git Bash) y abre una terminal nueva.
- ¿El script de instalación lanza errores? Es un script Bash — ejecutado desde PowerShell falla en el flag -fsSL. Cambia primero el perfil de terminal por defecto de VS Code a Git Bash y vuelve a lanzar curl -fsSL https://opencode.ai/install | bash.
- ¿La terminal o la ventana de escritorio se abre en negro? Borra la carpeta de datos dañada en .local/share/opencode (AppData\Local\share\opencode en Windows), cierra los procesos colgados y vuelve a arrancar — en la grabación la TUI vuelve a dibujarse en menos de un minuto.
- ¿"Free usage exceeded" o errores de proveedor? Abre el selector de modelos con /models y cambia a otro modelo, o reautentícate con /connect. Lanza opencode auth list para confirmar que tus credenciales llegaron.
- ¿Faltan modelos en la lista? Solo aparecen los proveedores conectados. Añade el proveedor con /connect, o curate la lista con las claves model, disabled_providers y las listas blancas/negras por proveedor en opencode.json.
Fix OpenCode Error in Antigravity Terminal (Git Bash + PATH Solution)
Canal:teacher account5:52
OpenCode docs — install, config & troubleshooting
Docs:opencode.ai/docs
Los fotogramas vienen de tres grabaciones de pantalla: el arreglo del PATH de arriba, una reparación de pantalla en negro en Windows (xiXPoY2d4iw por Vũ Văn Hà) y un cambio de modelo al agotarse el límite gratuito (DX8MZFuu1BM por Free Code). Cada paso enlaza a su propio momento del vídeo.
Los fotogramas del vídeo siguen siendo propiedad de sus creadores y se incrustan aquí como documentación paso a paso con atribución y enlaces profundos.
Arregla OpenCode paso a paso
Instalación y PATH — la etapa del "not recognized"
- 1
Consigue el comando de instalación oficial
Abre opencode.ai y copia el comando del recuadro de instalación — curl -fsSL https://opencode.ai/install | bash — o cambia la pestaña a npm, bun o brew. Si OpenCode "no funciona" porque nunca llegó a instalarse del todo, recomenzar desde este comando oficial gana a depurar uno copiado a medias.
El recuadro de instalación de opencode.ai con pestañas curl, npm, bun y brewVer en 0:08 - 2
Ejecuta el instalador desde un shell Bash, no desde PowerShell
El script de instalación está escrito para Bash. Pegado en PowerShell produce Invoke-WebRequest: A parameter cannot be found that matches parameter name 'fsSL', exactamente como se capturó en la grabación. El arreglo mostrado en pantalla: poner terminal.integrated.defaultProfile.windows a Git Bash en el settings.json del IDE para que el comando caiga en un shell Bash.
El error -fsSL que lanza PowerShell, junto al ajuste de perfil por defectoVer en 1:32 - 3
Arregla "opencode: command not found" ampliando el PATH
La instalación termina pero la terminal sigue diciendo bash: opencode: command not found — la carpeta del binario nunca llegó al PATH. En la grabación se añade el directorio .opencode/bin con export PATH=/c/Users/<you>/.opencode/bin:$PATH en Git Bash y se vuelve a lanzar opencode — el mismo export en tu ~/.bashrc lo hace permanente.
command not found, el export del PATH y el reintento que funcionaVer en 4:32 - 4
Relanza el instalador en Git Bash y confirma
Con Git Bash como perfil por defecto, lanza otra vez curl -fsSL https://opencode.ai/install | bash y déjalo terminar. También puedes instalar vía npm con npm install -g opencode-ai, o con choco y scoop en Windows. Reabre la terminal después para que se recoja el PATH actualizado.
Git Bash como perfil por defecto mientras se relanza el comando de instalaciónVer en 2:30
Pantalla en negro y cuelgues al arrancar
- 5
Reconoce el arranque con pantalla en negro
Segundo modo de fallo: escribes opencode, el título de la ventana cambia y el cuerpo sigue negro — sin banner, sin prompt. La grabación muestra exactamente esta ventana muerta en Windows 11. Tu entrada no tiene nada que ver: el estado en disco o un proceso colgado impide que la TUI se dibuje.
La ventana de símbolo del sistema en negro justo tras lanzar opencodeVer en 0:09 - 6
Borra la carpeta de datos dañada
El arreglo mostrado en la grabación: cierra OpenCode, termina las instancias colgadas en el Administrador de tareas y borra la carpeta de datos AppData\Local\share\opencode (en macOS y Linux es ~/.local/share/opencode). Guarda auth.json, logs y estado de proyectos, así que después tendrás que autenticarte de nuevo — un precio pequeño por una TUI que funciona.
La carpeta de datos de opencode en AppData\Local\share antes del borradoVer en 0:28 - 7
Relanza y confirma que la TUI se dibuja
Lanza opencode otra vez. La siguiente escena de la grabación es la UI de terminal sana — banner, prompt Ask anything y el consejo "Run /connect to add an AI provider and start coding". Si tu ventana sigue oscura, arranca con opencode --print-logs y revisa el archivo más reciente de la carpeta log/ para encontrar la línea que falla.
La TUI de OpenCode restaurada tras la limpieza del estadoVer en 1:09
Proveedores, modelos y problemas del IDE
- 8
Lee el mensaje del límite gratuito antes de cambiar
Cuando se agota la cuota de un modelo incluido, la sesión muestra un banner rojo "Free usage exceeded, subscribe to Go [retrying…]" y deja de responder. No es un cuelgue — la grabación enseña cómo la sesión se recupera en cuanto se elige otro modelo, así que lee el mensaje como la señal de pasar al paso 9.
El banner Free usage exceeded y la línea del modelo actualVer en 0:36 - 9
Abre el selector de modelos y elige otro
Lanza /models en la sesión (u opencode models desde el shell) para listar todo lo que exponen tus proveedores conectados. En la grabación se elige otro modelo con etiqueta Free del catálogo de OpenCode Zen; cualquier modelo con el que tengas credenciales vale, incluidos Claude, GPT o Gemini una vez conectados con /connect.
El selector Select model con modelos etiquetados Free y proveedoresVer en 0:12 - 10
Elige una variante de esfuerzo de razonamiento si te la ofrece
Algunos modelos abren un segundo diálogo Select variant con las opciones Default, minimal, medium, high y xhigh, tal como se capturó en la grabación. Los esfuerzos más bajos responden más rápido y cuestan menos; reserva high para refactors peliagudos. La elección se aplica a la sesión actual, así que es un experimento sin riesgo.
Select variant con opciones de razonamiento de minimal a xhighVer en 0:20 - 11
Confirma el cambio en la barra de estado
La barra de estado bajo el prompt nombra el modelo activo — en la grabación, tras el cambio lee Build · Muse Spark 1.2 Free · OpenCode Zen · xhigh, y el panel de contexto muestra los tokens usados y $0.00 gastados. Si un error terco persiste incluso en el modelo nuevo, reautentícate con /connect y verifica con opencode auth list.
La barra de estado confirmando el modelo y el esfuerzo cambiadosVer en 0:30 - 12
Conecta OpenCode a VS Code
Para la cara de "no funciona en VS Code": abre la terminal integrada, lanza opencode, y la extensión de OpenCode se instala automáticamente — la grabación muestra opencode for VS Code by SST en la lista Installed. Después Ctrl+Esc abre OpenCode en una terminal dividida; si falla, busca "OpenCode" en el Marketplace de extensiones e instálala a mano.
La extensión de opencode instalada y las instrucciones de ejecución del instaladorVer en 3:02
¿Sigue roto? Recorre la checklist
Si las tres etapas de arriba no cubrieron tu síntoma, estos son los patrones de fallo restantes — cada uno mapeado a la documentación oficial para que arregles la causa, no el síntoma.
- 1Sigue "not recognized" tras instalar — cada terminal abierta conserva su PATH viejo. Cierra y vuelve a abrir el shell, y mete la línea de export en ~/.bashrc (o ajusta el PATH de Windows en Propiedades del sistema) para que sobreviva a los reinicios. Usuarios de npm: asegúrate de que la carpeta bin global de npm también esté en el PATH.
- 2No arranca en absoluto — lanza opencode --print-logs para ver el fallo en vivo y lee el último log en ~/.local/share/opencode/log/ (Windows: %USERPROFILE%\.local\share\opencode\log). Solo se conservan los últimos 10 logs; el relevante es el más reciente. Si sospechas un binario desactualizado, prueba opencode upgrade.
- 3ProviderInitError o "invalid or corrupted configuration" — la documentación prescribe borrar el directorio de datos (rm -rf ~/.local/share/opencode) y reautenticarse con /connect. El mismo remedio que el arreglo de pantalla en negro del paso 6, pero llegando desde el mensaje de error.
- 4AI_APICallError en plena sesión — limpia la caché de paquetes de proveedores con rm -rf ~/.cache/opencode y reinicia para que los SDK se reinstalen. Comprueba opencode auth list después; credenciales caducadas o ausentes son la segunda causa más común.
- 5La app de escritorio muerta en Windows — actualiza el runtime de WebView2, cierra del todo y vuelve a arrancar, y quita cualquier override personalizado de server.port / OPENCODE_PORT. La documentación recomienda WSL para la experiencia más fluida en Windows, lo que además esquiva la mayoría de problemas de perfiles de terminal.
- 6No se muestran todos los modelos — /models solo lista los proveedores conectados. Añade uno con /connect y curate el catálogo en opencode.json: pon "model": "provider/model-id" por defecto, oculta proveedores con disabled_providers o acota la lista de un proveedor con su whitelist/blacklist.
Recorrer la lista en orden resuelve la abrumadora mayoría de reportes de "opencode no funciona": primero el PATH, luego el estado, y al final proveedores y modelos. Cuando nada ayude, captura el archivo de log más reciente y abre un issue en el repositorio de OpenCode — a los mantenedores les piden el log, no una captura.