OpenCode no instala: los errores comunes y su solución

Tabla de Contenidos

• Antes de nada: ¿es un error de instalación o de conexión?
• Error 1: error: opencode-ai's postinstall script was not run.
• Error 2: brew install opencode no funciona
• Error 3: command not found: opencode
• Error 4: instalé en Ubuntu y no encuentro el paquete
• Error 5: tengo la v1 y quiero pasar a la v2
• Error 6: el instalador pide permisos o falla con EACCES
• Error 7: la TUI abre pero el modelo no responde
• Error 8: funcionaba y de pronto se agotó a media tarde
• Error 9: instalé dos veces y ahora tengo comportamientos raros
• Checklist rápido
• Sigue leyendo

Antes de nada: ¿es un error de instalación o de conexión?

Esta distinción te ahorra horas, y casi nadie la hace.

Si la TUI abre —si ves la interfaz de OpenCode en tu terminal— la instalación funcionó. Cualquier problema a partir de ahí es de configuración: la API key, el proveedor, la cuota. No reinstales nada.

Si el comando no existe o el instalador aborta, entonces sí es instalación, y sigue leyendo.

Error 1: error: opencode-ai's postinstall script was not run.

Este es el error más buscado, y tiene dos causas distintas que se confunden.

Causa A: tu gestor de paquetes bloqueó el script. El paquete de npm usa un script de postinstall de confianza para bajar el binario nativo de tu plataforma. bun y pnpm no ejecutan scripts de postinstall sin permiso explícito, por diseño de seguridad. Si instalaste con uno de ellos sin el flag, el paquete queda a medias: existe, pero sin binario.

# bun
bun install -g --trust @opencode/cli

# pnpm
pnpm add -g --allow-build=@opencode/cli @opencode/cli

Causa B: estás en el paquete antiguo. Fíjate en el nombre que aparece en el error: opencode-ai. Ese es el paquete viejo. El de v2 se llama @opencode/cli. Si seguiste un tutorial de 2025, instalaste el equivocado.

npm uninstall -g opencode-ai
npm install -g @opencode/cli

Haz la desinstalación aunque creas que no lo tienes. Dos paquetes que registran el mismo comando opencode en el PATH producen errores que no se parecen a su causa.

Error 2: brew install opencode no funciona

No funciona porque no existe. La documentación de v2 es explícita: Homebrew, AUR, Scoop y Chocolatey no están soportados.

Si buscaste brew install anomalyco/tap/opencode y no te resolvió, no es que el tap esté caído: es que no es un canal oficial. Lo mismo con cualquier .exe suelto de un espejo.

Los canales que sí funcionan:

Vía	Comando
npm	npm install -g @opencode/cli
bun	bun install -g --trust @opencode/cli
pnpm	pnpm add -g --allow-build=@opencode/cli @opencode/cli
yarn	yarn global add @opencode/cli
Script oficial	curl -fsSL https://opencode.ai/v2/install | bash
Docker	ghcr.io/anomalyco/opencode con tag de versión

Cualquier tutorial que te dé un brew install para OpenCode es de 2025 o de una fuente no oficial. La lista vigente está en la documentación de OpenCode.

Error 3: command not found: opencode

Esto casi nunca es la instalación. Es el PATH.

1. Abre una terminal nueva. Si instalaste con el script de curl, el directorio puede no estar cargado en la sesión actual.
2. Si no quieres cerrar la terminal, recarga tu shell: source ~/.bashrc o source ~/.zshrc.
3. Comprueba dónde quedó el binario: npm bin -g te dice el directorio global de npm. Si ese directorio no está en tu $PATH, añádelo.

En Windows este error es más frecuente porque el prefijo global de npm a veces no queda en el PATH del sistema al instalar Node. Es un problema de Node, no de OpenCode: se arregla una vez y afecta a todos tus paquetes globales.

Error 4: instalé en Ubuntu y no encuentro el paquete

No hay paquete de apt ni de snap. En Linux se instala exactamente igual que en macOS: por npm/bun/pnpm/yarn o con el script oficial de v2.

Si usaste el script curl en Ubuntu y el comando no aparece, vuelve al error 3: es el PATH. El script instala en un directorio propio que tu shell tiene que conocer.

Error 5: tengo la v1 y quiero pasar a la v2

El salto de versión cambió el nombre del paquete, y eso es lo que rompe las actualizaciones. Un npm update -g sobre el paquete antiguo no te lleva a v2, porque son paquetes distintos en el registro.

npm uninstall -g opencode-ai
npm install -g @opencode/cli
opencode --version

Comprueba la versión al final. Si sigue dando la antigua, te queda un binario huérfano en otro directorio del PATH: busca con which -a opencode y borra el que no corresponda.

Error 6: el instalador pide permisos o falla con EACCES

Es el clásico de npm global en Linux y macOS: el directorio global pertenece a root y tu usuario no puede escribir en él.

La solución incorrecta y tentadora es sudo npm install -g. Funciona, pero deja archivos de root en tu home y te generará problemas después. La solución correcta es cambiar el prefijo de npm a un directorio de tu usuario, o usar un gestor de versiones de Node como nvm, fnm o volta, que instalan todo en tu home y eliminan el problema de raíz.

Error 7: la TUI abre pero el modelo no responde

Repito el aviso del principio porque es donde más gente reinstala sin necesidad: esto no es un error de instalación.

Ejecuta /connect dentro de la TUI. Revisa que la API key sea la correcta y que el proveedor seleccionado sea el que pagaste. Si usas el Coding Plan de Z.ai, el endpoint importa: hay uno compatible con Anthropic y otro compatible con OpenAI, y elegir mal hace que no se descuente tu cuota. Eso está detallado en la configuración del Z.ai Coding Plan.

Error 8: funcionaba y de pronto se agotó a media tarde

Tampoco es un bug. Es el techo de uso de tu plan.

OpenCode Go aplica límites por ventana de tiempo, no una cuota mensual única. Si te quedaste sin cuota a media tarde, alcanzaste el tope de la ventana de 5 horas, no el del mes. Los números exactos y cómo se reparten están en OpenCode Go: precio y límites.

Error 9: instalé dos veces y ahora tengo comportamientos raros

Síntomas: el comando responde una versión distinta a la que instalaste, o los cambios de configuración no se aplican.

which -a opencode

Ese comando lista todas las rutas donde existe el binario. Si devuelve más de una, tienes instalaciones compitiendo: típicamente una de npm y otra del script curl, o una de brew de un intento antiguo. Borra las que no quieras conservar y deja una sola.

Checklist rápido

Si no quieres leer todo lo anterior, este es el orden de diagnóstico:

1. ¿Abre la TUI? → el problema no es la instalación, es /connect.
2. which -a opencode → si hay más de uno, limpia.
3. npm uninstall -g opencode-ai → quita el paquete antiguo.
4. npm install -g @opencode/cli → instala el de v2.
5. Terminal nueva → descarta el PATH.
6. Con bun o pnpm → añade --trust o --allow-build.
7. Nunca brew.

Sigue leyendo

• El tutorial completo: Cómo instalar OpenCode paso a paso
• Si el problema es la cuota: OpenCode Go: precio y límites
• Si el problema es el endpoint: Z.ai Coding Plan: base URL y configuración