Resposta curta
Trate o OpenCode V2 como uma migração planejada, não como uma atualização às cegas
Vale testar o V2 quando os recursos atuais de CLI e desktop atendem ao seu fluxo e você tem tempo para validar a mudança. Mantenha o V1 disponível até verificar modelos, credenciais, agentes, permissões, servidores MCP, plugins, clientes de editor e tarefas reais. Uma configuração pessoal pequena pode começar em um projeto de teste; uma equipe ou repositório com plugins próprios deve migrar por etapas.
O guia oficial informa que configurações V1 compatíveis e definições baseadas em arquivos devem continuar funcionando, e o comando conhecido opencode foi mantido. Três diferenças exigem atenção: plugins V1 não executam no V2, o contrato da API do servidor e de seus clientes mudou, e as preferências do terminal passam para um arquivo global cli.json. Verifique a compatibilidade mesmo sem converter a configuração principal.
Este guia reúne os canais oficiais de instalação, uma comparação prática e uma lista de migração reversível. A documentação principal não promete converter por completo bancos de dados antigos de sessão. Para escolher modelos, configurar chaves de API ou comparar planos, veja os guias de modelos, provedores e planos.
OpenCode V1 vs. V2: mudanças que afetam o trabalho diário
O número da versão não revela sozinho o esforço de migração. Verifique as partes que você realmente usa: cliente de terminal, plugins, API do servidor e configuração. Arquivos de projeto compatíveis são diferentes de código executável de plugin ou de clientes de API.
| Área | V1 | V2 e impacto da migração |
|---|---|---|
| Comando CLI | opencode | O nome continua igual. Instalações V1 e V2 gerenciadas por pacotes não ficam lado a lado por padrão. |
| Configuração e arquivos compatíveis | Configuração V1 e arquivos em .opencode/ | Campos e definições compatíveis devem continuar; valide provedores e permissões. |
| Plugins | API e pontos de entrada de plugins V1 | API nova; cada plugin V1 precisa ser portado antes de rodar. |
| API do servidor e clientes | Contrato V1 e clientes gerados | Contratos novos; integrações precisam de clientes compatíveis com V2 e testes. |
| Preferências do terminal | Arquivos tui.json ou tui.jsonc em camadas | Configurações compatíveis vão para o cli.json global; confira o resultado. |
| Instalação | Pacote ou instalador V1 | Use um canal oficial específico para V2; talvez seja preciso remover primeiro o V1 instalado por pacote. |
A tabela delimita o que conferir, mas não garante suporte a todos os campos antigos. O guia de migração separa valores compatíveis, aceitos porém sem suporte e não aceitos. Consulte a documentação atual antes de alterar segurança, acesso a provedores ou automação, e leia os avisos do início do programa.
Você deve atualizar o OpenCode para V2 agora?
Decida pela compatibilidade e pela possibilidade de voltar atrás, não apenas pelo número principal. Uma configuração pessoal que usa recursos integrados tem custo diferente de um repositório com plugins próprios e integração de editor.
Um teste com V2 faz sentido quando
- Seu fluxo depende principalmente de configuração compatível, provedores, comandos integrados, agentes, skills e MCP, e você consegue testá-los em um projeto de exemplo.
- Você quer usar a CLI ou o desktop V2 e pode preservar uma cópia funcional da instalação atual.
- Seus plugins ou clientes do servidor já têm uma versão V2, ou há alguém responsável e tempo para portá-los e testá-los.
É melhor manter o V1 por enquanto quando
- Um plugin V1, endpoint de servidor, cliente de IDE ou automação é crítico e ainda não foi testado com o contrato V2.
- Você não consegue restaurar pacote, configuração ou dados de sessão se o novo fluxo falhar.
- A ferramenta é compartilhada por uma equipe, mas ainda não há plano para atualizar ambientes, documentação e suporte.
Se houver dúvida, use um projeto descartável e registre o comando, o gerenciador de pacotes, a versão do OpenCode e o resultado esperado. Por exemplo, uma pessoa que usa apenas agentes e provedores pode validar uma cópia do repositório enquanto outra mantém o V1 para um plugin de servidor. Isso transforma uma decisão abstrata em uma lista verificável, sem presumir que toda versão nova seja automaticamente melhor.
Como instalar o OpenCode V2 por um canal oficial
A introdução oficial do V2 lista canais de instalação pelo terminal. Escolha o gerenciador que você já usa e siga as instruções atuais, inclusive o suporte à sua plataforma. Não copie um comando antigo de pacote V1 sem confirmar que ele serve para migrar.
| Canal | Comando na documentação V2 | O que conferir |
|---|---|---|
| Instalador oficial | curl -fsSL https://opencode.ai/v2/install | bash | Confirme que o instalador e o sistema operacional correspondem ao guia V2. |
| Homebrew | brew install anomalyco/tap/opencode-v2 | Confira se o tap e o nome do pacote continuam atualizados. |
| npm | npm install -g @opencode/cli | A tag npm @latest apontava para 2.0.22 em 3 de outubro de 2026; verifique a versão atual. |
A documentação V2 também apresenta Bun, pnpm e outros métodos. O suporte varia conforme a plataforma. No Windows, consulte os binários listados em vez de presumir que qualquer gerenciador será compatível. Para Yarn, Vite+ ou AUR, use a sintaxe atual da documentação V2 e evite links de sites não oficiais para baixar instaladores.
Antes de instalar, identifique como o V1 foi instalado. O guia oficial informa que talvez seja necessário remover o V1 gerenciado por pacotes porque ambas as versões usam o comando opencode. O instalador curl do V2 substitui o binário V1. Remover o pacote não deve apagar configurações ou dados compartilhados: faça uma cópia separada e confira o que o gerenciador vai excluir.
Como migrar do OpenCode V1 para V2 sem perder o controle
Deixe a primeira etapa reversível. O objetivo é confirmar que o V2 inicia e que o projeto funciona, não reescrever todos os arquivos de configuração no primeiro dia. Siga as instruções oficiais adequadas ao sistema e ao pacote que você usa.
- Registre a instalação V1. Anote o gerenciador ou instalador, a versão, as variáveis e os caminhos de configuração. Preserve o pacote antigo ou um meio confiável de reinstalá-lo.
- Faça um backup datado. Guarde configurações, definições de projeto e dados que precisam ser restaurados. Confirme que a cópia está acessível e não ficou apenas numa pasta temporária.
- Liste dependências executáveis. Registre plugins, clientes de API, comandos de CI e integrações de editor. Marque cada item como testado no V2, aguardando portabilidade ou não mais necessário.
- Instale pelo canal correto. Remova o pacote V1 somente se o guia exigir. Uma atualização normal do V1 não é a instalação do V2.
- Valide a configuração. Inicie o V2 em um projeto de teste. Revise avisos sobre campos antigos, modelos, credenciais, permissões e conexões MCP antes de uma tarefa importante.
- Adapte código e clientes. Porte os plugins para a nova API e atualize os clientes do servidor. Teste também permissões e situações de erro.
- Converta preferências depois. Preferências de terminal compatíveis migram para um
cli.jsonglobal. Converter a configuração para o formato nativo V2 é opcional e pode esperar até que o fluxo básico esteja validado.
Durante a primeira validação, mantenha no lugar a configuração V1 compatível. Segundo o guia, o V2 pode normalizar essas configurações em memória sem reescrever o arquivo de origem. Separar instalação, portabilidade de plugins e conversão facilita identificar uma regressão e voltar atrás.
O que continua funcionando e o que exige revisão manual
Considere compatível apenas o comportamento explicitamente suportado pelo guia V2 atual. Essa distinção responde a dúvidas sobre compatibilidade do OpenCode V2 sem sugerir que todo campo antigo ou extensão continuará funcionando.
| Componente | Expectativa cuidadosa | Verificação prática |
|---|---|---|
| Configuração e arquivos de projeto compatíveis | Devem continuar, mas alguns campos podem não ter suporte ou ser ignorados. | Leia os avisos e teste provedores, permissões e tarefas reais. |
| Agentes, comandos e skills baseados em arquivos | O guia prevê continuidade quando o comportamento usado é compatível. | Execute cada recurso em um projeto de teste e compare os resultados esperados. |
| Plugins | Implementações V1 não funcionam como plugins V2. | Adapte o ponto de entrada e teste carregamento, permissões e erros. |
| API e clientes do servidor | O contrato mudou; não presuma que clientes V1 sejam compatíveis. | Migre o cliente e valide chamadas, eventos e autenticação. |
| Sessões antigas | O guia principal não promete conversão em massa de bancos históricos. | Faça backup e verifique as sessões importantes antes de mudar o fluxo diário. |
A documentação oficial classifica algumas configurações antigas como aceitas, porém sem suporte, e informa que elas podem gerar avisos. Se uma opção controla permissões de arquivos, limites de ferramentas ou acesso a provedores, não confie apenas no fato de o programa iniciar: confira os registros e execute um teste que comprove o controle esperado.
Valide o OpenCode V2 antes de remover seu plano de retorno ao V1
Faça uma aceitação curta em um projeto de exemplo e guarde o resultado nas notas de atualização. Uma equipe pode repetir a lista em outras máquinas; um usuário individual pode usá-la para decidir com dados se continua no V2 ou volta ao V1.
- O comando executado corresponde à instalação esperada e mostra uma versão V2.
- Provedor, credenciais e modelo funcionam sem expor chaves nos registros.
- Agentes, comandos e skills necessários respondem como esperado.
- As permissões de leitura e escrita seguem as regras do projeto.
- Os servidores MCP conectam e uma falha de conexão não produz ação inesperada.
- Plugins e clientes essenciais têm versões compatíveis com V2.
- As sessões necessárias estão disponíveis ou cobertas por um backup conferido.
- Uma tarefa real termina corretamente e o resultado pode ser revisado.
Se uma verificação essencial falhar, suspenda o V2 naquele fluxo e volte à instalação ou ao pacote V1 preservado. Não faça o V1 ler uma configuração exclusiva do V2. A forma de reverter depende do gerenciador; mantenha o pacote disponível e separe os dados do usuário do software instalado. Só apague o backup depois de completar um ciclo normal de trabalho.
Para atualizações normais depois de instalar o V2, a CLI V2 documenta opencode upgrade e o alias update. Esse comando atualiza uma instalação que já é V2; a migração da versão principal V1 tem etapas próprias para pacote e instalação.
Perguntas frequentes sobre a migração para OpenCode V2
OpenCode V2 é uma atualização normal do V1?
Não. É uma migração de versão principal. Ambos usam o comando opencode e, por padrão, instalações gerenciadas por pacotes não ficam lado a lado. Identifique como o V1 foi instalado e siga o guia oficial.
Preciso reescrever minha configuração do OpenCode para V2?
Não necessariamente. O guia oficial diz que o V2 lê e normaliza as configurações V1 compatíveis sem reescrever o arquivo de origem. Revise os avisos e teste provedores, permissões e MCP.
Plugins do OpenCode V1 funcionam no V2?
Não diretamente. As implementações de plugin V1 não rodam como plugins V2. Porte a entrada e o comportamento usando o guia oficial e teste o pacote instalado.
Como instalar o OpenCode V2 com npm?
A documentação V2 atual usa npm install -g @opencode/cli. Confira o guia e a página do pacote para confirmar a versão e os requisitos da plataforma.
Qual comando atualiza o OpenCode V2?
Para uma instalação que já está no V2, a CLI documenta opencode upgrade e o alias update. Migrar do V1 exige tratar separadamente o pacote antigo e o canal de instalação.
A migração para V2 transfere todo o histórico de sessões?
O guia principal não promete converter por completo os bancos de dados antigos. Faça backup dos dados importantes e confirme as sessões necessárias antes de alterar seu fluxo diário.
Referências oficiais do OpenCode
Os comandos e as informações de compatibilidade foram conferidos em fontes oficiais em 3 de outubro de 2026. Pacotes e instruções podem mudar; confirme tudo novamente antes de uma migração principal.