Cómo actualizar a OpenCode 2.0: migra tu configuración, plugins y sesiones de v1

Name

Soren Atelier

Actualizado el 4/11/2026

Respuesta corta: haz copia de seguridad de las carpetas de OpenCode, actualiza a la última versión 1.x y luego ejecuta la actualización mayor.

# 1. Copia de seguridad de la configuración y los datos (las sesiones están en la carpeta de datos)
cp -R ~/.config/opencode ~/opencode-v1-config-backup
cp -R ~/.local/share/opencode ~/opencode-v1-data-backup
 
# 2. Pasa primero a la última 1.x (--major existe desde v1.19.0)
opencode upgrade
 
# 3. Pasa a OpenCode 2
opencode upgrade --major

Dentro de la interfaz de terminal, /update hace lo mismo. Si prefieres una instalación limpia, elimina primero el paquete de v1 y usa uno de los comandos de instalación de v2 del Paso 3.

La mayoría de los ajustes de v1 siguen funcionando. Tres cosas se rompen a propósito: los plugins de v1 no cargan, la API del servidor es nueva y tui.json se sustituye por cli.json. Otros dos cambios, más discretos, pillan a mucha gente desprevenida: v2 ya no lee CLAUDE.md y permite por defecto el acceso a carpetas fuera del proyecto. El resto de esta guía cubre cada punto, además de los bugs conocidos de las primeras semanas de 2.x.

Qué comprobamos y qué no: El 25 de octubre de 2026 revisamos el lado de v1 en macOS con OpenCode 1.18.19 instalado. Leímos sus comandos upgrade, export, session y debug paths. También leímos los datos del registro de npm de @opencode/cli 2.1.4 y los issues de GitHub y respuestas de los mantenedores citados más abajo. No ejecutamos OpenCode 2 para esta guía. Todo lo que se dice sobre el comportamiento de v2 viene de la guía de migración (opens in a new tab) oficial, la documentación de v2 (opens in a new tab), el anuncio de OpenCode 2.0 (opens in a new tab) y esas respuestas de los mantenedores. Enlazamos cada fuente. El 4 de noviembre de 2026 volvimos a comprobar las versiones, las páginas de releases y los hilos de issues con @opencode/cli 2.2.5 y opencode-ai 1.19.5.

¿Conviene actualizar ya?

OpenCode 2.0 llegó a npm el 11 de septiembre de 2026 como @opencode/cli. Muchos usuarios de v1 que instalaron con npm o con el script de instalación no lo vieron hasta octubre (los usuarios de Homebrew core lo recibieron antes; consulta la trampa de Homebrew en el Paso 3). El motivo: la ruta opencode upgrade --major llegó con v1.19.0 el 11 de octubre, y el equipo anunció 2.0 el 14 de octubre. El anuncio alcanzó 888 puntos en Hacker News. Desde el 11 de octubre, el repositorio ha recibido más de 4.000 issues nuevos, y 130 de ellos mencionan 2.0.

Ahora las dos versiones se publican en paralelo. opencode-ai en npm sigue siendo v1 (1.19.5 el 28 de octubre). @opencode/cli es v2 (2.2.5 el 30 de octubre). Desde v2.2.0 (27 de octubre), las builds de 2.x también aparecen en GitHub Releases (opens in a new tab), pero la release marcada como Latest sigue siendo 1.x. Es deliberado: v1 busca actualizaciones a través de la release Latest, y el equipo no quiere que la actualización automática de v1 salte a 2.x (#57675 (opens in a new tab)).

Paso 1: copia de seguridad antes de tocar nada

La guía de migración oficial dice que conserves una copia de tu configuración de v1 mientras pruebas. No dice qué copiar. En macOS y Linux, opencode debug paths muestra las carpetas. Nuestra instalación 1.18.19 mostró:

Copia las dos primeras (los comandos del inicio de esta página). Cierra antes OpenCode, para que la base de datos de sesiones (opencode.db y su archivo -wal) se copie en un estado coherente. Copia también los opencode.json y carpetas .opencode/ de proyecto que te importen. Esos viven en tus repos, así que en la mayoría de los casos git ya los controla.

Para tener una copia portable de una conversación importante, expórtala desde v1 antes de actualizar:

opencode session list
opencode export <sessionID> > my-session.json

opencode export escribe la sesión en JSON. Añade --sanitize para quitar datos sensibles de la transcripción y de archivos antes de compartirlo.

Paso 2: pasa a la última 1.x

opencode upgrade --major solo existe a partir de v1.19.0. En nuestra instalación 1.18.19, opencode upgrade --help no mostraba el flag --major. Si estás en la 1.18 o anterior, ejecuta primero una actualización normal:

opencode --version
opencode upgrade

Después comprueba que opencode --version muestra 1.19.x. Desde v1.19.0 las actualizaciones ya no se instalan solas, así que una instalación antigua se queda antigua hasta que ejecutes esto.

Paso 3: actualiza o instala v2

Actualización en el sitio (desde 1.19.x):

opencode upgrade --major

Instalación limpia. La guía de migración indica que elimines primero una instalación de v1 gestionada por un gestor de paquetes, porque v1 y v2 no se instalan en paralelo por defecto. Después elige uno de los comandos oficiales de v2:

# Instalador oficial (sustituye el binario de v1)
curl -fsSL https://opencode.ai/v2/install | bash
 
# Homebrew (fíjate en la fórmula -v2; elimina antes una instalación de v1 con brew)
brew uninstall opencode
brew install anomalyco/tap/opencode-v2
 
# npm (nombre de paquete nuevo)
npm uninstall -g opencode-ai
npm install -g @opencode/cli

Trampas de los gestores de paquetes:

• Nombre del paquete npm. v1 es opencode-ai. v2 es @opencode/cli. Si hoy ejecutas npm install -g opencode-ai, sigues obteniendo la 1.19.5.
• Homebrew core frente al tap. brew install opencode (sin tap) instala OpenCode 2 desde el 28 de septiembre, así que brew upgrade ya pasa esa instalación a 2.x sin --major. La fórmula de 1.x es anomalyco/tap/opencode y la de 2.x es anomalyco/tap/opencode-v2. Entran en conflicto, así que ejecuta brew uninstall opencode antes de instalar la otra.
• Scripts de instalación. El paquete npm de v2 usa un script postinstall para elegir el binario nativo. Si usas Bun o pnpm, añade --trust (Bun) o --allow-build=@opencode/cli (pnpm). Sin ese flag, falta el binario.
• Dos nombres de comando. El paquete npm registra tanto opencode como opencode2 en su campo bin (lo comprobamos en los metadatos del registro).
• mise instala v2 solo desde mise 2026.10.9. Las versiones anteriores de mise instalan OpenCode 1.
• Los gestores de paquetes de Windows (Scoop, Chocolatey) no tienen soporte para v2, y opencode upgrade --major no puede cambiar esas instalaciones. Descarga el binario independiente de la CLI para Windows o la app de escritorio desde la página de instalación de v2 (opens in a new tab), o usa WSL. Un reporte en chino sobre v2 colgándose en WSL (#55033 (opens in a new tab)) se cerró el 16 de octubre por falta de detalles.
• Docker: existen imágenes versionadas, por ejemplo ghcr.io/anomalyco/opencode:2.0.0.

Ejecuta opencode --version y confirma que muestra 2.x.

Paso 4: revisa qué tomó v2 de tu configuración de v1

No tienes que reescribir tu configuración. v1 y v2 leen las mismas ubicaciones (~/.config/opencode/opencode.json, el opencode.json del proyecto, .opencode/). v2 traduce en memoria los nombres de campo de v1 y no reescribe tus archivos. En el primer arranque de v2, los ajustes globales de tui.json pasan a un nuevo ~/.config/opencode/cli.json. Tus archivos de v1 quedan como estaban.

Abre un proyecto real y revisa cinco cosas antes de fiarte: modelos, credenciales de proveedores, agentes, permisos y servidores MCP. La guía de migración usa la misma lista.

Si más adelante quieres configuración nativa de v2, estos son los cambios de campo más importantes:

Dos reglas de la guía evitan la mayoría de errores de migración:

1. Mantén cada entrada en un solo formato. Puedes mezclar sintaxis de v1 y v2 en el nivel superior. Dentro de una misma entrada de agente, proveedor, comando o modelo, elige un formato.
2. No apuntes v1 a un archivo convertido. Ambas versiones leen las mismas rutas. Cuando conviertes un archivo a sintaxis solo de v2, v1 ya no puede leerlo. Si piensas volver atrás, convierte al final.

La guía también sugiere dejar que OpenCode haga la conversión. Arranca v2 en el proyecto y dale este prompt: "Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings." (es decir: migra tu configuración, incluidas las definiciones en archivos, al formato nativo de V2, conservando su comportamiento y los ajustes no relacionados). Revisa el diff antes de quedártelo.

Campos de v1 que v2 ignora

Estos muestran un aviso y no hacen nada:

temperature, top_p y options a nivel de agente también dejan de funcionar. v2 los guarda en el request.body del agente, pero no los envía. Defínelos en una variante del modelo.

Estos campos de v1 parecen antiguos, pero siguen funcionando sin aviso, porque v2 los convierte por ti. No los borres al hacer limpieza:

La configuración de LSP se conserva, pero no se ejecuta. Si dependías de los diagnósticos LSP de OpenCode, dale al agente comandos explícitos de lint, typecheck o compilación (por ejemplo en AGENTS.md).

Paso 5: los cambios de comportamiento que te sorprenden más tarde

Cuando estos cambian, nada da error, y por eso son los que más desconciertan.

v2 no lee CLAUDE.md

v1 recurría a CLAUDE.md cuando no existía AGENTS.md. v2 no lo hace. Si las reglas de tu proyecto están en CLAUDE.md, v2 arranca sin ellas y nada te avisa. Arreglarlo lleva un minuto:

# En cada repo que solo tenga CLAUDE.md
git mv CLAUDE.md AGENTS.md

Además, v1 usaba ~/.claude/CLAUDE.md como reglas globales cuando faltaba ~/.config/opencode/AGENTS.md. v2 también eliminó ese respaldo. Si no tienes un AGENTS.md global, cópialo ahí:

cp ~/.claude/CLAUDE.md ~/.config/opencode/AGENTS.md

Claude Code ahora lee AGENTS.md cuando no hay CLAUDE.md, así que un solo archivo puede seguir sirviendo a las dos herramientas. La petición para recuperar ese comportamiento de respaldo sigue abierta como #53402 (opens in a new tab).

Las carpetas fuera del proyecto se permiten por defecto

En v1, el agente preguntaba antes de tocar un directorio fuera del proyecto. En v2, el acceso a directorios externos está permitido por defecto. Para recuperar el comportamiento de v1, añade esta regla a permissions:

{
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

Si ejecutas OpenCode con autoaprobación, o en una máquina con archivos sensibles fuera de tus repos, añade esta regla antes de tu primera sesión en v2.

Los todos están desactivados

La lista de tareas (todo) venía activada por defecto en v1. En v2 está desactivada. Vuelve a activarla con "experimental": { "todo": true }.

Ahora corre un único servicio en segundo plano para toda tu cuenta de usuario

v2 arranca un servidor compartido en segundo plano. La TUI, la interfaz web y la app de escritorio se conectan a él. Eso es lo que hace funcionar opencode pair (un enlace de un solo uso que caduca a los 5 minutos) y las tareas en segundo plano (Ctrl+B). Si prefieres no tenerlo:

opencode service set disabled true   # lo detiene y desactiva el arranque automático
opencode service unset disabled      # lo vuelve a activar
opencode --standalone                # un servidor privado solo para esta ejecución

El emparejamiento no funciona con el servicio desactivado. Además, el servicio no lee cli.json, así que los ajustes de la interfaz de terminal solo afectan al cliente de terminal.

Paso 6: plugins, Oh My OpenCode y la extensión de VS Code

Los plugins de v1 no cargan en v2. La API de plugins es nueva. Cambiar plugin por plugins en la configuración no basta. Hay que portar el código de cada plugin (consulta la guía oficial de migración de plugins (opens in a new tab)).

El fallo más habitual fue Oh My OpenCode (oh-my-openagent). En OpenCode 2.0.27, la versión 5.1.32 falló con Plugin must export a default definition with an id and an effect or setup function (oh-my-openagent #10089 (opens in a new tab)). La corrección (#10439 (opens in a new tab)) se fusionó el 18 de octubre, y la 5.1.38 es la primera release en npm que la incluye. El 2 de noviembre, el mantenedor confirmó que las versiones actuales cargan en OpenCode 2 y muestran un aviso que remite a OmO Native, la app independiente omo. Actualiza oh-my-openagent a la 5.1.38 o posterior antes de actualizar OpenCode. Si prefieres pasarte a omo, su README indica que ejecutes omo setup una vez para traer las claves de proveedores, los servidores MCP, las skills y la elección de modelos. Si eres nuevo en el harness, empieza por Oh My OpenCode y OpenCode: instalación, configuración y soluciones.

Error de la extensión de VS Code Unrecognized flag: --port. Las versiones antiguas de la extensión arrancan la CLI con opencode --port <port>. v2 eliminó ese flag. Actualiza la extensión a v1.0.0 o posterior (Marketplace u Open VSX). Mientras tanto, abre una terminal en VS Code y ejecuta opencode tú mismo (#55219 (opens in a new tab)).

Tus propios scripts que llaman al servidor. La API del servidor de v1 ya no existe. Pórtalos al paquete @opencode/client, que además encuentra solo el servicio en segundo plano. Desde la shell, opencode api llama a la misma API. OPENCODE_SERVER_USERNAME ya no está soportado; el nombre de usuario es siempre opencode. La GitHub Action de OpenCode se eliminó en 2.2.0.

Problemas conocidos tras actualizar

Son issues de GitHub abiertos o corregidos hace poco, de las primeras semanas de 2.x. Las soluciones vienen de los mantenedores, de quienes reportaron cada hilo o del bot del proyecto.

Cómo volver a 1.x

La guía de migración no cubre la vuelta atrás. Este es el orden seguro:

1. Elimina v2. opencode uninstall --dry-run muestra lo que va a borrar. Después, opencode uninstall elimina el programa y deja en disco las sesiones, la configuración y el estado.
2. Reinstala v1 con una versión fijada: npm install -g opencode-ai@1.19.5, o brew install anomalyco/tap/opencode (la fórmula sin -v2).
3. Si convertiste algún archivo de configuración a sintaxis solo de v2, restáuralo desde ~/opencode-v1-config-backup.
4. Si v1 no puede leer la base de datos de sesiones después de que v2 la haya usado, restaura ~/opencode-v1-data-backup. No probamos si v1 abre una base de datos en la que v2 ya ha escrito. Cuenta con la copia de seguridad.

Nota de seguridad: la brecha de OpenCode Console

Esto es independiente de la actualización, pero ocurrió la misma semana. El 17 de octubre, el equipo de OpenCode informó de que alguien obtuvo acceso no autorizado a un sistema heredado que estaba retirando (comunicado citado en Hacker News (opens in a new tab)). Las claves de proveedores de terceros guardadas en un workspace de Console "may have been exposed" (podrían haber quedado expuestas). Su consejo: revocar y sustituir esas claves en el panel de cada proveedor y revisar el uso reciente. Una publicación posterior cifró en un 1,4% la proporción de usuarios de Console afectados, y el cofundador Dax Raad dijo que la CLI y la app de escritorio no se vieron afectadas (TechCrunch (opens in a new tab)). Si alguna vez guardaste claves de OpenAI, Anthropic u otros en Console, rótalas antes o después de actualizar.

Qué hay realmente nuevo en 2.0

Nada de esto hace falta para terminar la actualización. Son las funciones que explican por qué cambió la arquitectura:

• Servicio en segundo plano compartido por la TUI, la interfaz web y la app de escritorio, más opencode pair para acceso web.
• Tareas en segundo plano: pulsa Ctrl+B para mandar al fondo un comando de shell o un subagente en ejecución mientras el agente principal sigue trabajando.
• Code Mode: convierte servidores MCP y endpoints OpenAPI en funciones que el agente puede encadenar en un solo paso. Los servidores MCP lo usan por defecto.
• Recarga en caliente: OpenCode puede escribir un plugin para sí mismo a mitad de sesión y usarlo al momento.
• @opencode/sdk y @opencode/client: el código que hay detrás de la CLI, para crear tus propios clientes.

Si estás eligiendo un agente de terminal desde cero en lugar de actualizar uno, Cómo usar Codex cubre la alternativa más cercana.

Guías relacionadas

• Oh My OpenCode y OpenCode: instalación, configuración y soluciones
• Cómo usar Codex
• Cómo usar DeepSeek Harness
• Agentes de código en paralelo, explicado