Instalar OpenCode puede resultar confuso a veces cuando errores de configuración interrumpen el proceso o la herramienta no funciona como se espera. Desde comandos faltantes hasta problemas de compatibilidad con Node.js, los usuarios suelen tener dificultades durante la instalación inicial. Esta guía sobre la instalación de OpenCode ofrece una solución completa para corregir errores comunes y configurar OpenCode correctamente en Mac y Windows, ya sea que uses la versión de escritorio o la CLI/TUI, para que puedas empezar a programar sin demoras.
¿Qué es OpenCode?
OpenCode es un agente de codificación de IA de código abierto diseñado para ayudar a los desarrolladores a escribir, editar, depurar y gestionar código directamente desde su entorno preferido, ya sea una terminal, un IDE o una aplicación de escritorio. A diferencia de los asistentes de codificación con IA tradicionales, que se centran principalmente en sugerencias de código, OpenCode puede comprender una base de código completa, modificar archivos, ejecutar comandos y automatizar flujos de trabajo de desarrollo. También admite múltiples modelos de IA y modelos locales, lo que brinda a los desarrolladores mayor flexibilidad y control sobre cómo construyen su software.
Requisitos previos para instalar OpenCode
Antes de instalar OpenCode, asegúrate de que tu sistema cumpla con los requisitos básicos. Los requisitos exactos dependen de si planeas usar la aplicación de escritorio o la interfaz basada en terminal, pero contar con la configuración adecuada ayudará a garantizar un proceso de instalación sin problemas.
Para escritorio
Sistema operativo: macOS / Windows / Linux
OpenCode ofrece aplicaciones de escritorio para los principales sistemas operativos, lo que permite a los desarrolladores instalar y usar la herramienta en su entorno preferido. Asegúrate de que tu sistema use un sistema operativo compatible, como macOS (Apple Silicon o Intel), Windows (x64) o Linux (.deb, .rpm).
Permiso para instalar aplicaciones: Es posible que necesites permisos de administrador o de nivel de sistema para descargar e instalar software en tu dispositivo. Esto es especialmente importante en entornos laborales o de TI administrados, donde los derechos de instalación pueden estar restringidos.
Conexión estable a internet: Se requiere una conexión a internet fluida para descargar OpenCode, instalar actualizaciones y conectarte a los modelos y servicios de IA compatibles durante la configuración y el uso.
Para Terminal/TUI
Acceso a la terminal: OpenCode se puede instalar y usar directamente desde la línea de comandos. Asegúrate de tener acceso a una aplicación de terminal, como Terminal en macOS, el símbolo del sistema o PowerShell en Windows, o una shell de Linux.
Un método de instalación: OpenCode admite múltiples métodos de instalación para adaptarse a distintos sistemas operativos y preferencias de los desarrolladores. Elige el gestor de paquetes o la herramienta de instalación que mejor se ajuste a tu entorno, como npm, curl, brew, Scoop, Chocolatey o WSL.
Conocimientos básicos de línea de comandos: Estar familiarizado con los comandos de terminal comunes puede facilitar mucho la instalación y el uso diario. Si bien no se requiere experiencia avanzada, se recomienda comprender la navegación básica y la ejecución de comandos.
¿Cómo instalar OpenCode Desktop?
Instalar OpenCode Desktop es un proceso sencillo que solo requiere unos pocos pasos simples para poner en marcha la aplicación. Estos son los pasos a seguir.
Paso 1: Descarga OpenCode Desktop
Ve a la página oficial de descargas de OpenCode y selecciona la versión de Windows o macOS de la aplicación. El instalador se descargará automáticamente en tu sistema. Asegúrate de descargarlo desde la fuente oficial para garantizar la seguridad y la autenticidad.
Paso 2: Ejecuta el instalador
Ubica el archivo del instalador descargado y haz doble clic en él para iniciar la instalación. Sigue las instrucciones en pantalla para completar la configuración.
Paso 3: Completa la instalación
Avanza por los mensajes de configuración a medida que aparecen y selecciona el directorio de instalación que prefieras cuando se te solicite. Luego deja que el instalador termine el proceso de configuración en tu sistema.
Paso 4: Abre OpenCode Desktop
Una vez terminada la instalación, abre OpenCode Desktop desde el Menú Inicio o el acceso directo del escritorio. Luego inicia un proyecto nuevo o abre una carpeta existente para empezar a trabajar. Cuando tu espacio de trabajo esté cargado, podrás interactuar con el asistente de IA para generar código, depurar problemas o crear funciones directamente dentro de tu proyecto.
¿Cómo instalar OpenCode Terminal/TUI en Mac?
OpenCode Terminal (TUI) en Mac se puede instalar directamente usando los administradores de paquetes oficiales o un comando de instalación de una sola línea. Está diseñado para desarrolladores que prefieren trabajar dentro de la terminal en lugar de una interfaz gráfica. Sigue estos pasos para instalar OpenCode TUI en Mac.
Paso 1: Elige un método de instalación de OpenCode Terminal
Visita la página oficial de descargas de OpenCode y ve a la sección de OpenCode Terminal. Ahí encontrarás varias opciones de instalación, incluyendo curl, Homebrew, npm y bun. Selecciona el método que mejor se adapte a tu entorno de desarrollo y copia el comando de instalación correspondiente.
Paso 2: Abre la aplicación Terminal en Mac
Abre la app Terminal en tu Mac. Puedes hacerlo desde Aplicaciones > Utilidades > Terminal o buscarla rápidamente con Spotlight. Aquí es donde ejecutarás el comando de instalación de OpenCode.
Paso 3: Instala OpenCode Terminal
Pega el siguiente comando de instalación en la Terminal y presiona Enter:
curl -fsSL https://opencode.ai/install | bashEspera a que la instalación termine. OpenCode descargará los archivos necesarios y configurará la CLI automáticamente.
Paso 4: Abre la interfaz de terminal de OpenCode
Después de que la instalación se complete, ejecuta el comando de OpenCode en la Terminal para iniciar la interfaz de usuario de terminal (TUI). La interfaz interactiva se abrirá directamente en tu ventana de terminal, lo que te permitirá conectarte a un proveedor de IA, configurar ajustes y empezar a trabajar con OpenCode.
¿Cómo instalar OpenCode Terminal/TUI en Windows?
OpenCode admite varios métodos de instalación en Windows, incluyendo WSL, npm y bun. Para lograr la mejor compatibilidad y experiencia, la documentación oficial recomienda usar el Subsistema de Windows para Linux (WSL). Los pasos a continuación usan el método de instalación con WSL. Si ya tienes WSL instalado, puedes omitir el primer paso.
Paso 1: Instala WSL (recomendado)
Abre PowerShell como Administrador y ejecuta el siguiente comando:
wsl --installEste comando habilita el Subsistema de Windows para Linux (WSL) e instala Ubuntu de forma predeterminada. Una vez que la instalación termine, reinicia tu computadora. La primera vez que abras Ubuntu, Windows completará automáticamente la configuración del entorno Linux.
Paso 2: Abre WSL e instala OpenCode
Abre tu terminal de WSL (como Ubuntu) desde el menú Inicio de Windows. Si es la primera vez que la abres, completa la configuración inicial. Luego ejecuta el siguiente comando para instalar OpenCode:
curl -fsSL https://opencode.ai/install | bashEspera a que la instalación termine antes de continuar.
Paso 3: Verifica la instalación
Después de que la instalación se complete, ejecuta el siguiente comando:
opencodeSi OpenCode Terminal/TUI se inicia correctamente, la instalación está completa y ya puedes empezar a usar OpenCode para programar con asistencia de IA.
¿Cómo integrar APIs externas en OpenCode?
Una de las principales ventajas de OpenCode es su capacidad de conectarse con proveedores externos de modelos de IA mediante integraciones de API. Al agregar tu propia clave de API, puedes acceder a diferentes modelos de lenguaje y elegir el que mejor se adapte a tu flujo de trabajo de programación.
Integrar APIs externas en OpenCode (pasos generales)
A continuación se muestran los pasos para integrar APIs externas en OpenCode:imi
Paso 1: Crea una cuenta y genera una clave de API
Comienza creando una cuenta con el proveedor de IA de tu preferencia, como Kimi u otro servicio compatible. Una vez que tu cuenta esté configurada, ve a la página de administración de claves de API del proveedor y genera una nueva clave de API. Guarda esta clave de forma segura, ya que se necesitará para conectar el proveedor con OpenCode.
Paso 2: Abre el menú de conexión de proveedores
Inicia OpenCode y abre tu espacio de trabajo. En la interfaz de comandos, ejecuta el siguiente comando:
/connectEste comando abre el menú de conexión de proveedores, donde puedes agregar y administrar servicios de IA externos.
Paso 3: Agrega tu clave de API
Selecciona el proveedor que quieres usar de la lista de opciones disponibles. Cuando se te solicite, pega la clave de API que generaste anteriormente y confirma la conexión. OpenCode almacenará la clave de forma segura y la usará para autenticar las solicitudes al proveedor seleccionado.
┌ API key
│
│ your_api_key_here
│
└ enterPaso 4: Consulta los modelos disponibles
Después de conectar tu proveedor, ejecuta el siguiente comando para ver todos los modelos disponibles a través de esa API:
/modelsOpenCode mostrará una lista de los modelos compatibles junto con sus nombres y opciones de configuración.
Paso 5: Selecciona un modelo y comienza a usarlo
Elige el modelo con el que quieres trabajar de la lista disponible. Una vez seleccionado, OpenCode enrutará tus solicitudes a través de ese modelo, lo que te permitirá generar código, depurar aplicaciones y realizar otras tareas de desarrollo usando la API conectada. Puedes cambiar de modelo más adelante si tus necesidades cambian.
Integrar las APIs de Kimi en OpenCode
OpenCode admite múltiples proveedores de IA, lo que permite a los desarrolladores conectar modelos externos usando claves de API para obtener mayor flexibilidad. Una de las opciones más potentes es la API de Kimi.
La API de Kimi, ofrecida por la Plataforma abierta de Moonshot AI, brinda acceso a modelos de lenguaje avanzados de Kimi a través de una interfaz compatible con OpenAI. Se puede integrar fácilmente en herramientas de programación, aplicaciones y flujos de trabajo basados en IA usando una clave de API segura. La plataforma incluye una variedad de modelos Kimi optimizados para tareas de programación, razonamiento y comprensión de contexto extenso.
Sigue estos pasos para integrar las APIs de Kimi en OpenCode.
Paso 1: Crea una cuenta en Moonshot AI y genera una clave de API
Visita Kimi AI Open Platform e inicia sesión en tu cuenta.
Desde el panel, ve a API Keys y haz clic en Create API Key.
Después de que se genere la clave (comienza con
sk-), cópiala de inmediato y guárdala de forma segura. La clave solo se muestra una vez y se usa para autenticar las solicitudes entre OpenCode y Moonshot AI.
Paso 2: Conecta Moonshot AI con OpenCode
Abre tu espacio de trabajo de OpenCode y ejecuta:
/connectAparecerá el menú de conexión de proveedores. Busca Moonshot AI (o Kimi) en la lista de proveedores integrados y selecciónalo. OpenCode te pedirá que ingreses tu clave de API.
Cuando se te solicite, pega la clave de API que generaste en la consola de Moonshot AI y presiona Enter:
┌ API key
│ sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
│
└ enterUna vez verificada, OpenCode guardará la credencial de forma segura en ~/.local/share/opencode/auth.json y la asociará con la configuración de tu proveedor Moonshot AI.
Nota: por seguridad, OpenCode almacena las claves de API por separado del archivo de configuración principal. El comando
/connectgestiona el almacenamiento de credenciales, mientras que el comportamiento del proveedor se configura enopencode.json.
Paso 3: Configura el proveedor en opencode.json (si es necesario)
Si encuentras un error No endpoints found después de conectarte, o si necesitas personalizar la configuración del proveedor, agrega la configuración de Moonshot AI a tu archivo opencode.json:
{"$schema": "https://opencode.ai/config.json","provider": {"moonshotai": {"name": "Moonshot AI","options": {"baseURL": "https://api.moonshot.ai/v1"},"models": {"kimi-k2.6": {"name": "Kimi K2.6"},"kimi-k2.5": {"name": "Kimi K2.5"}}}}}Guarda el archivo y reinicia OpenCode para aplicar los cambios.
Paso 4: Consulta los modelos de Kimi disponibles
Después de conectar el proveedor, ejecuta:
/modelsOpenCode mostrará todos los modelos disponibles a través de tu cuenta de Moonshot AI, incluidos:
| Modelo | Descripción |
|---|---|
| kimi-k2.6 | El último modelo insignia con arquitectura MoE de 1T, capacidades avanzadas de codificación y razonamiento |
| kimi-k2.5 | Modelo de alto rendimiento optimizado para tareas de codificación y contexto largo |
| moonshot-v1-128k | Modelo de contexto largo para análisis de documentos |
| moonshot-v1-32k | Modelo equilibrado para tareas generales |
| moonshot-v1-8k | Modelo de contexto corto para respuestas rápidas |
Paso 5: Selecciona un modelo de Kimi y comienza a programar
Selecciona moonshotai/kimi-k2.6 y configúralo como el modelo activo. Una vez seleccionado, OpenCode usará el modelo Kimi elegido para la generación de código, la depuración, la refactorización y otras tareas de desarrollo asistidas por IA.
Puedes cambiar a otro modelo en cualquier momento a través del mismo menú de selección de modelos.
Consejo: si experimentas problemas con el modo Agent/Tool (como errores de validación de JSON Schema), se trata de un problema de compatibilidad conocido entre los requisitos estrictos de esquema de Moonshot AI y el formato de parámetros de herramientas de OpenCode. Considera usar el modo Chat para obtener la mejor estabilidad, o instala el plugin
opencode-moonshot-compatibilitypara manejar automáticamente la compatibilidad de temperatura.
Beneficios de usar la Kimi API
La Kimi API está diseñada para respaldar flujos de trabajo de desarrollo modernos, ayudando a los equipos a pasar de las ideas a la implementación de manera más eficiente. Más allá de la generación de código, puede entender diferentes tipos de entradas, adaptarse a los requisitos del proyecto y automatizar tareas de ingeniería rutinarias. Estos son algunos de sus principales beneficios:
Convertir entradas multimodales en implementaciones funcionales
La Kimi API puede interpretar información de múltiples formatos, incluyendo mockups de diseño, diagramas de arquitectura, diagramas de flujo y videos. Utiliza este contexto para entender los requisitos del proyecto y convertirlos en especificaciones técnicas o código funcional. Como resultado, los equipos pueden pasar del concepto a la implementación con menos pasos de traducción manual.
Manejar tareas de codificación de largo alcance y problemas de ingeniería complejos
La Kimi API ayuda a OpenCode a manejar tareas de codificación más grandes que requieren planificación, consistencia y refinamiento. Es útil para crear funciones, refactorizar código y resolver problemas de ingeniería complejos.
Razonar sobre problemas con llamadas a herramientas de varios pasos
La Kimi API puede razonar sobre tareas de varios pasos y llamar a herramientas cuando sea necesario. Esto ayuda con la depuración, el análisis de código y los flujos de trabajo que no se pueden completar en una sola respuesta.
¿Cómo solucionar problemas al instalar OpenCode?
Instalar OpenCode suele ser sencillo, pero los usuarios pueden enfrentar errores de configuración comunes debido a incompatibilidades de entorno, dependencias o problemas de configuración. A continuación, encontrarás una guía clara y práctica para ayudarte a resolver los problemas de instalación más frecuentes de forma rápida y eficiente.
Command not found: opencode
Si ves este error, significa que el sistema no puede localizar el ejecutable de OpenCode en tu PATH. Esto suele ocurrir cuando la instalación está incompleta o cuando las variables de entorno no están configuradas correctamente.
Para solucionarlo, verifica primero la instalación y asegúrate de que el directorio binario esté agregado a tu PATH del sistema. Si lo instalaste mediante npm, revisa la ruta global de npm bin y actualiza la configuración de tu shell en consecuencia. Reiniciar la terminal suele resolver el problema después de hacer las correcciones.
Versión de Node.js demasiado antigua
OpenCode requiere Node.js 18 o superior, y las versiones anteriores provocarán fallas de instalación o de ejecución.
Para resolver esto, revisa tu versión actual con node --version. Si está desactualizada, actualiza Node.js usando un gestor de versiones como nvm. Después de actualizar, vuelve a instalar OpenCode para asegurar la compatibilidad con el entorno de ejecución actualizado.
Errores de permisos de npm
Los errores de permisos suelen ocurrir cuando npm intenta instalar paquetes globales sin el acceso de escritura adecuado.
En lugar de usar sudo, configura un directorio global de npm dedicado en tu carpeta de usuario y actualiza la configuración de PATH. Esto garantiza instalaciones más seguras y estables. Después de corregir los permisos, vuelve a ejecutar el comando de instalación para completar la configuración con éxito.
Problemas de red o firewall
En redes restringidas o entornos corporativos, la instalación de OpenCode puede fallar debido al bloqueo de acceso al registro de npm o a descargas lentas.
Para solucionarlo, cambia a un registro de npm alternativo o usa un método de instalación directo como curl o descarga binaria. Además, asegúrate de que tu firewall permita el tráfico de Node.js y npm, ya que las conexiones bloqueadas suelen interrumpir la instalación de paquetes.
Problemas de renderizado de la TUI
Si OpenCode se abre pero aparece dañado, desalineado o muestra texto ilegible, el problema suele estar relacionado con la compatibilidad de la terminal.
Usa un emulador de terminal moderno que admita color verdadero y renderizado Unicode, como Windows Terminal, WezTerm o iTerm2. Actualizar la configuración de tu terminal o cambiar de entorno suele resolver los problemas de visualización de inmediato.
Conclusión
Una instalación adecuada de OpenCode y una configuración correcta garantizan un rendimiento fluido en diferentes sistemas, reduciendo el riesgo de errores de configuración comunes. Cuando las dependencias, la configuración de la terminal y las conexiones de API se gestionan correctamente, los usuarios pueden resolver problemas rápidamente y mantener un entorno de desarrollo estable. Integrar servicios externos como la Kimi API aumenta aún más la flexibilidad al permitir el acceso a modelos avanzados dentro de los flujos de trabajo.