Respuesta rápida
Trata OpenCode V2 como una migración planificada, no como una actualización a ciegas
Puedes probar V2 cuando sus capacidades actuales de CLI y escritorio encajen con tu forma de trabajar y tengas tiempo para comprobarlas. Conserva V1 mientras verificas modelos, credenciales, agentes, permisos, servidores MCP, complementos, clientes de editor y tareas reales del proyecto. Un usuario puede empezar con un proyecto de prueba; un equipo o un repositorio con extensiones propias debería avanzar por etapas.
La guía oficial indica que la configuración V1 admitida y las definiciones basadas en archivos están pensadas para seguir funcionando, y que se mantiene el comando opencode. Hay tres cambios que requieren atención: los complementos V1 no se ejecutan en V2, el contrato de la API del servidor y sus clientes cambia, y las preferencias del terminal pasan a un archivo global cli.json. Aunque no conviertas tu configuración principal, comprueba que el comportamiento siga siendo correcto.
Esta página reúne los canales oficiales de instalación, una comparación práctica y una lista de migración reversible. La documentación principal no garantiza una conversión completa de bases de datos con sesiones antiguas. Para elegir modelos, configurar claves API o comparar planes, consulta las guías de modelos, proveedores y planes.
OpenCode V1 frente a V2: cambios que afectan al trabajo diario
El número de versión no indica por sí solo el esfuerzo de migración. Revisa las partes que realmente usas: cliente de terminal, complementos, API del servidor y configuración. Los archivos de proyecto compatibles no plantean el mismo problema que el código ejecutable de un complemento o un cliente de API.
| Área | V1 | V2 y efecto de migración |
|---|---|---|
| Comando CLI | opencode | El nombre se conserva. V1 y V2 no suelen quedar instalados a la vez mediante un gestor de paquetes. |
| Configuración y archivos admitidos | Configuración V1 y archivos en .opencode/ | Los campos y definiciones admitidos están pensados para continuar; comprueba proveedores y permisos. |
| Complementos | API e inicio de complementos V1 | La API cambia. Hay que adaptar y probar cada complemento V1. |
| API del servidor y clientes | Contrato V1 y clientes generados | El contrato es nuevo; las integraciones necesitan clientes compatibles con V2 y pruebas. |
| Preferencias del terminal | Archivos tui.json o tui.jsonc en varias capas | Los ajustes admitidos pasan al cli.json global del cliente de terminal; revisa el resultado. |
| Instalación | Paquete o instalador V1 | Usa un canal oficial específico de V2; quizá debas retirar primero el V1 administrado por paquetes. |
La tabla delimita qué revisar; no promete que todos los campos antiguos sigan admitidos. La guía de migración distingue entre valores compatibles, aceptados pero sin soporte y no admitidos. Si cambias opciones relacionadas con seguridad, acceso a proveedores o automatizaciones, consulta la guía actual y atiende los avisos de inicio.
¿Deberías actualizar OpenCode a V2 ahora?
Decide según la compatibilidad y la facilidad para volver atrás, no solo por el número mayor. Una instalación personal que usa funciones incluidas tiene un coste distinto al de un repositorio con complementos propios y una integración de editor.
Una prueba de V2 tiene sentido si
- Tu trabajo depende sobre todo de configuración admitida, proveedores, comandos integrados, agentes, habilidades y MCP, y puedes probarlos en un proyecto de muestra.
- Quieres la experiencia de CLI o escritorio de V2 y puedes conservar una copia funcional de tu instalación actual.
- Tus complementos o clientes del servidor ya tienen una versión V2, o tienes tiempo y una persona responsable para adaptarlos y probarlos.
Conviene conservar V1 por ahora si
- Un complemento V1, endpoint, cliente de IDE o tarea automatizada es imprescindible y nadie la ha probado contra el contrato V2.
- No puedes restaurar el paquete, la configuración o los datos de sesión si la nueva forma de trabajo falla.
- La herramienta se comparte en un equipo y no hay todavía un plan para actualizar documentación, entornos de desarrollo y soporte.
Si no estás seguro, usa un proyecto desechable y apunta el comando, gestor de paquetes, versión de OpenCode y resultado esperado. Por ejemplo, un desarrollador que solo usa agentes y proveedores puede validar esas funciones en una copia del repositorio, mientras otro conserva V1 para sus plugins de servidor. Así la decisión se basa en una lista comprobable y no en una afirmación genérica sobre la nueva versión.
Cómo instalar OpenCode V2 desde un canal oficial
La introducción oficial de V2 enumera varios canales de terminal. Elige el gestor que ya utilizas y consulta sus instrucciones actuales, incluida la compatibilidad de tu sistema. No copies sin revisar el comando de un paquete V1 cuando estés haciendo la migración.
| Canal | Comando indicado en la documentación V2 | Qué comprobar |
|---|---|---|
| Instalador oficial | curl -fsSL https://opencode.ai/v2/install | bash | Confirma que el instalador y el sistema operativo coincidan con la guía V2. |
| Homebrew | brew install anomalyco/tap/opencode-v2 | Comprueba que el tap y el nombre del paquete sigan vigentes. |
| npm | npm install -g @opencode/cli | La etiqueta @latest del paquete resolvía a 2.0.22 el 3 de octubre de 2026; verifica la versión en directo. |
La misma guía V2 describe instrucciones para Bun y pnpm, además de otros métodos. El soporte cambia según la plataforma; en Windows, la guía recomienda las versiones binarias disponibles en lugar de asumir que cualquier gestor funciona. Sigue la sintaxis de la documentación oficial vigente para Yarn, Vite+ o AUR y no uses un enlace de descarga de terceros.
Antes de instalar, identifica cómo obtuviste V1. La guía oficial advierte que una instalación V1 administrada por paquetes quizá deba retirarse antes porque las dos versiones comparten el comando opencode. El instalador curl de V2 sustituye el binario V1. Desinstalar el paquete no debería implicar borrar tu configuración o datos compartidos: haz una copia separada y confirma qué elimina cada gestor.
Cómo migrar de OpenCode V1 a V2 sin perder el control
Mantén reversible la primera pasada. El objetivo inicial es comprobar que V2 arranca y que el proyecto sigue funcionando, no reescribir todos los archivos de configuración el primer día. Usa la guía oficial para el paquete y sistema operativo concretos.
- Registra la instalación V1. Apunta el gestor de paquetes o instalador, la versión, las variables y las rutas de configuración. Conserva el paquete anterior o el método para reinstalarlo.
- Haz una copia con fecha. Guarda los archivos de configuración, definiciones del proyecto y datos que necesites restaurar. Comprueba que la copia exista y que puedas acceder a ella; no la dejes solo en una carpeta temporal.
- Revisa dependencias ejecutables. Inventaría complementos, clientes API, comandos de CI e integraciones de editor. Etiqueta cada dependencia como probada en V2, pendiente de adaptación o innecesaria.
- Instala siguiendo el canal correcto. Retira el paquete V1 solo si la guía para esa instalación lo requiere. No confundas la instalación de V2 con el comando de actualización rutinaria de V1.
- Comprueba la configuración. Inicia V2 en un proyecto de muestra. Revisa avisos sobre campos antiguos, modelos, credenciales, permisos y servidores MCP antes de empezar una tarea importante.
- Adapta código y clientes. Migra los complementos a la nueva API y actualiza clientes del servidor. Prueba tanto el caso correcto como el manejo de errores y permisos.
- Convierte preferencias más tarde. Las preferencias de terminal admitidas se trasladan a un
cli.jsonglobal. La conversión de configuración a formato nativo V2 es opcional; espera hasta haber validado el flujo básico.
Durante la primera verificación deja la configuración V1 admitida en su formato original. Según la guía, V2 puede normalizar estos ajustes en memoria sin reescribir el archivo fuente. Separar la instalación, la migración de complementos y la conversión de configuración permite identificar qué cambio causa un fallo y simplifica la vuelta atrás.
Qué se conserva automáticamente y qué requiere revisión manual
Considera compatible únicamente el comportamiento que la guía V2 actual respalda de forma explícita. Esta distinción responde a dudas de compatibilidad sin insinuar que todos los campos antiguos o extensiones seguirán funcionando.
| Elemento | Expectativa prudente | Comprobación práctica |
|---|---|---|
| Configuración y archivos de proyecto admitidos | Están pensados para funcionar, pero puede haber campos no admitidos o ignorados. | Lee los avisos de V2 y prueba el proveedor, los permisos y las tareas reales. |
| Agentes, comandos y habilidades basados en archivos | La guía los incluye entre las definiciones que pueden continuar si usan comportamiento admitido. | Invoca cada elemento desde un proyecto de prueba y compara el resultado esperado. |
| Complementos | Las implementaciones V1 no se ejecutan como complementos V2. | Adapta la entrada a la nueva API y prueba carga, permisos y errores. |
| API y clientes del servidor | El contrato cambia; los clientes generados para V1 no deben darse por compatibles. | Regenera o migra el cliente y valida llamadas, eventos y autenticación. |
| Sesiones antiguas | La guía central no promete conversión masiva de bases de datos históricas. | Respalda y verifica las sesiones imprescindibles antes de cambiar tu flujo diario. |
La guía oficial clasifica algunos ajustes antiguos como aceptados, aunque sin soporte, y explica que pueden producir avisos. Si una opción afecta a límites de herramientas, permisos de archivos o acceso a proveedores, no deduzcas su efecto solo porque la aplicación se abra: comprueba el registro y ejecuta un caso de prueba que demuestre el control esperado.
Verifica OpenCode V2 antes de retirar V1
Haz una aceptación corta en un proyecto de muestra y guarda el resultado junto a tus notas de actualización. Un equipo puede reutilizar esta lista en otras máquinas; una persona puede usarla para recordar por qué decidió continuar o volver a V1.
- El comando resuelto es la instalación que esperabas y la versión muestra V2.
- El proveedor, las credenciales y el modelo funcionan sin exponer claves en logs.
- Agentes, comandos y habilidades relevantes responden con el comportamiento esperado.
- Los permisos de lectura y escritura siguen las reglas del proyecto.
- Los servidores MCP se conectan y una desconexión o fallo no provoca acciones inesperadas.
- Los complementos y clientes imprescindibles tienen una versión compatible con V2.
- La sesión que necesitas retener está disponible, o cuentas con una copia exportable.
- Una tarea real termina correctamente y la salida puede revisarse.
Si falla un control esencial, pausa V2 para ese flujo y vuelve al V1 que conservaste. No hagas que V1 lea configuración exclusiva de V2. El comando de vuelta depende del gestor; por eso conviene conservar el paquete y separar los datos de usuario del software instalado. No borres la copia hasta que hayas completado al menos un ciclo de trabajo normal.
Para actualizaciones rutinarias después de instalar V2, la CLI V2 documenta opencode upgrade y el alias update. Ese comando pertenece a V2 ya instalado; no sustituye los pasos específicos para pasar del canal principal V1 a V2.
Preguntas frecuentes sobre OpenCode V2
¿OpenCode V2 es una actualización normal desde V1?
No. Es una migración de versión principal. Ambas generaciones usan el comando opencode y, por defecto, las instalaciones gestionadas por paquetes no conviven en paralelo. Confirma cómo instalaste V1 y sigue la guía oficial.
¿Tengo que reescribir mi configuración de OpenCode para V2?
No siempre. La guía oficial dice que V2 lee y normaliza la configuración V1 admitida sin cambiar el archivo fuente. Revisa los avisos y prueba proveedores, permisos y MCP.
¿Funcionan los complementos V1 de OpenCode en V2?
No directamente. Las implementaciones V1 no se ejecutan como complementos V2. Migra su punto de entrada y comportamiento con la guía oficial de complementos y prueba el paquete instalado.
¿Cómo se instala OpenCode V2 con npm?
La documentación V2 actual indica npm install -g @opencode/cli. Antes de instalar, comprueba la guía y la página del paquete para confirmar la versión y los requisitos de tu plataforma.
¿Qué comando actualiza OpenCode V2?
En una instalación que ya usa V2, la CLI documenta opencode upgrade y el alias update. La migración desde V1 requiere tratar aparte el paquete y el canal de instalación anteriores.
¿La actualización a V2 migra todo el historial de sesiones?
La guía principal no garantiza una conversión completa de las bases de datos antiguas. Respalda los datos importantes y verifica las sesiones que necesitas antes de cambiar tu flujo diario.
Fuentes oficiales de OpenCode
Los comandos y las afirmaciones de compatibilidad se comprobaron en documentación de primera parte el 3 de octubre de 2026. Los paquetes y las instrucciones pueden cambiar; confirma la versión actual antes de una migración principal.