Como atualizar para o OpenCode 2.0: migre config, plugins e sessões da v1

Name

Soren Atelier

Atualizado em 04/11/2026

Resposta curta: faça backup das pastas do OpenCode, atualize para a última versão 1.x e só então rode o upgrade de versão principal.

# 1. Backup da config e dos dados (as sessões ficam na pasta de dados)
cp -R ~/.config/opencode ~/opencode-v1-config-backup
cp -R ~/.local/share/opencode ~/opencode-v1-data-backup
 
# 2. Primeiro vá para a última 1.x (--major existe a partir da v1.19.0)
opencode upgrade
 
# 3. Passe para o OpenCode 2
opencode upgrade --major

Dentro da interface de terminal, /update faz a mesma coisa. Se preferir uma instalação limpa, remova primeiro o pacote da v1 e depois use um dos comandos de instalação da v2 do Passo 3.

A maior parte das configurações da v1 continua funcionando. Três coisas quebram de propósito: plugins da v1 não carregam, a API do servidor é nova e o tui.json foi substituído pelo cli.json. Duas mudanças mais discretas pegam muita gente de surpresa: a v2 não lê mais o CLAUDE.md e permite por padrão o acesso a pastas fora do projeto. O restante deste guia cobre cada ponto, além dos bugs conhecidos das primeiras semanas da 2.x.

O que verificamos e o que não verificamos: em 25 de outubro de 2026, verificamos o lado da v1 no macOS com o OpenCode 1.18.19 instalado. Lemos os comandos upgrade, export, session e debug paths. Também lemos os dados do registro npm do @opencode/cli 2.1.4 e as issues do GitHub e respostas dos mantenedores citadas abaixo. Não executamos o OpenCode 2 para este guia. Tudo sobre o comportamento da v2 vem do guia de migração (opens in a new tab) oficial, da documentação da v2 (opens in a new tab), do anúncio do OpenCode 2.0 (opens in a new tab) e dessas respostas dos mantenedores. Cada fonte tem link. Em 4 de novembro de 2026, conferimos de novo as versões, as páginas de release e as threads das issues com o @opencode/cli 2.2.5 e o opencode-ai 1.19.5.

Vale a pena atualizar agora?

O OpenCode 2.0 chegou ao npm em 11 de setembro de 2026, como @opencode/cli. Muitos usuários da v1 que instalaram pelo npm ou pelo script de instalação só o viram em outubro (quem usa o Homebrew core o recebeu antes; veja a armadilha do Homebrew no Passo 3). Isso porque o caminho opencode upgrade --major chegou na v1.19.0, em 11 de outubro, e a equipe anunciou o 2.0 em 14 de outubro. O anúncio chegou a 888 pontos no Hacker News. Desde 11 de outubro, o repositório recebeu mais de 4.000 novas issues, e 130 delas mencionam o 2.0.

As duas versões agora são distribuídas lado a lado. opencode-ai no npm continua sendo a v1 (1.19.5 em 28 de outubro). @opencode/cli é a v2 (2.2.5 em 30 de outubro). Desde a v2.2.0 (27 de outubro), builds da 2.x também aparecem no GitHub Releases (opens in a new tab), mas a release marcada como Latest ainda é a 1.x. Isso é proposital: a v1 procura atualizações pela release Latest, e a equipe não quer que a atualização automática da v1 leve os usuários para a 2.x (#57675 (opens in a new tab)).

Passo 1: faça backup antes de mexer em qualquer coisa

O guia oficial de migração diz para guardar uma cópia da sua configuração da v1 enquanto você testa. Ele não diz o que copiar. No macOS e no Linux, opencode debug paths lista as pastas. Nossa instalação 1.18.19 mostrou:

Copie as duas primeiras (com os comandos do topo desta página). Feche o OpenCode antes, para que o banco de sessões (opencode.db e o arquivo -wal dele) seja copiado em um estado consistente. Copie também qualquer opencode.json e pasta .opencode/ de projeto que importe para você. Elas ficam nos seus repositórios, então na maioria dos casos o git já as versiona.

Para ter uma cópia portátil de uma conversa importante, exporte-a na v1 antes de atualizar:

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

opencode export grava a sessão em JSON. Adicione --sanitize para remover dados sensíveis da transcrição e dos arquivos antes de compartilhar o arquivo.

Passo 2: vá para a última 1.x

opencode upgrade --major só existe a partir da v1.19.0. Na nossa instalação 1.18.19, opencode upgrade --help não mostrou a flag --major. Se você está na 1.18 ou anterior, rode primeiro um upgrade simples:

opencode --version
opencode upgrade

Depois confira se opencode --version mostra 1.19.x. Desde a v1.19.0, as atualizações não se instalam mais sozinhas, então uma instalação antiga continua antiga até você rodar esse comando.

Passo 3: atualize ou instale a v2

Upgrade no lugar (a partir da 1.19.x):

opencode upgrade --major

Instalação limpa. O guia de migração diz para remover primeiro uma instalação da v1 feita por gerenciador de pacotes, porque por padrão a v1 e a v2 não se instalam lado a lado. Depois escolha um dos comandos oficiais da v2:

# Instalador oficial (substitui o binário da v1)
curl -fsSL https://opencode.ai/v2/install | bash
 
# Homebrew (repare na fórmula -v2; remova antes uma instalação da v1 pelo brew)
brew uninstall opencode
brew install anomalyco/tap/opencode-v2
 
# npm (novo nome de pacote)
npm uninstall -g opencode-ai
npm install -g @opencode/cli

Armadilhas dos gerenciadores de pacotes:

• Nome do pacote no npm. A v1 é opencode-ai. A v2 é @opencode/cli. Se você rodar npm install -g opencode-ai hoje, ainda recebe a 1.19.5.
• Homebrew core x tap. brew install opencode (sem tap) instala o OpenCode 2 desde 28 de setembro, então brew upgrade já leva essa instalação para a 2.x sem --major. A fórmula da 1.x é anomalyco/tap/opencode e a da 2.x é anomalyco/tap/opencode-v2. Elas entram em conflito, então rode brew uninstall opencode antes de instalar a outra.
• Scripts de instalação. O pacote npm da v2 usa um script postinstall para escolher o binário nativo. Se você usa Bun ou pnpm, adicione --trust (Bun) ou --allow-build=@opencode/cli (pnpm). Sem essa flag, o binário fica faltando.
• Dois nomes de comando. O pacote npm registra tanto opencode quanto opencode2 no campo bin (conferimos os metadados do registro).
• mise só instala a v2 a partir do mise 2026.10.9. Versões mais antigas do mise instalam o OpenCode 1.
• Gerenciadores de pacotes do Windows (Scoop, Chocolatey) não têm suporte para a v2, e o opencode upgrade --major não consegue migrar essas instalações. Baixe o binário independente da CLI para Windows ou o app desktop na página de instalação da v2 (opens in a new tab), ou use o WSL. Um relato em chinês da v2 travando no WSL (#55033 (opens in a new tab)) foi fechado em 16 de outubro por falta de detalhes.
• Docker: existem imagens versionadas, por exemplo ghcr.io/anomalyco/opencode:2.0.0.

Rode opencode --version e confirme que aparece 2.x.

Passo 4: confira o que a v2 aproveitou da sua config da v1

Você não precisa reescrever sua config. A v1 e a v2 leem os mesmos locais (~/.config/opencode/opencode.json, opencode.json do projeto, .opencode/). A v2 converte os nomes de campos da v1 em memória e não reescreve seus arquivos. Na primeira execução da v2, as configurações globais do tui.json vão para um novo ~/.config/opencode/cli.json. Seus arquivos da v1 continuam como estavam.

Abra um projeto real e confira cinco coisas antes de confiar no resultado: modelos, credenciais dos provedores, agentes, permissões e servidores MCP. O guia de migração usa o mesmo checklist.

Se depois você quiser a config nativa da v2, estas são as mudanças de campo que mais importam:

Duas regras do guia evitam a maioria dos erros de migração:

1. Mantenha cada entrada em um único formato. Você pode misturar sintaxe da v1 e da v2 no nível superior. Dentro de uma mesma entrada de agente, provedor, comando ou modelo, escolha um formato.
2. Não aponte a v1 para um arquivo convertido. As duas versões leem os mesmos caminhos. Depois que você converte um arquivo para sintaxe exclusiva da v2, a v1 não consegue mais lê-lo. Se pretende voltar à v1, converta por último.

O guia também sugere deixar o próprio OpenCode fazer a conversão. Inicie a v2 no projeto e passe 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." (em português: migre minha configuração do OpenCode, incluindo as definições em arquivos, do formato V1 para o formato nativo V2, preservando o comportamento e todas as configurações não relacionadas). Revise o diff antes de mantê-lo.

Campos da v1 que a v2 ignora

Estes geram um aviso e não fazem nada:

temperature, top_p e options em nível de agente também deixam de funcionar. A v2 os mantém no request.body do agente, mas não os envia. Defina-os em uma variante do modelo.

Estes campos da v1 parecem antigos, mas continuam funcionando sem aviso, porque a v2 os converte para você. Não os apague durante a limpeza:

A config de LSP é mantida, mas não é executada. Se você dependia dos diagnósticos de LSP do OpenCode, passe ao agente comandos explícitos de lint, typecheck ou compilação (por exemplo no AGENTS.md).

Passo 5: as mudanças de comportamento que aparecem depois

Nada dá erro quando estes pontos mudam, por isso eles causam mais surpresas.

A v2 não lê o CLAUDE.md

A v1 usava o CLAUDE.md como alternativa quando não existia AGENTS.md. A v2 não faz isso. Se as regras do seu projeto estão no CLAUDE.md, a v2 começa sem elas e nada avisa você. A correção leva um minuto:

# Em cada repositório que só tem CLAUDE.md
git mv CLAUDE.md AGENTS.md

A v1 também usava o ~/.claude/CLAUDE.md como regras globais quando não existia ~/.config/opencode/AGENTS.md. A v2 também abandonou essa alternativa. Se você não tem um AGENTS.md global, copie o arquivo para lá:

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

O Claude Code agora lê o AGENTS.md quando não há CLAUDE.md, então um único arquivo ainda serve às duas ferramentas. O pedido de funcionalidade para restaurar essa alternativa está aberto como #53402 (opens in a new tab).

Pastas fora do projeto são permitidas por padrão

Na v1, o agente perguntava antes de mexer em um diretório fora do projeto. Na v2, o acesso a diretórios externos é permitido por padrão. Para restaurar o comportamento da v1, adicione esta regra em permissions:

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

Se você roda o OpenCode com aprovação automática, ou em uma máquina com arquivos sensíveis fora dos seus repositórios, adicione esta regra antes da sua primeira sessão na v2.

Todos desativados

A lista de tarefas (todo) vinha ativada por padrão na v1. Na v2 ela vem desativada. Reative com "experimental": { "todo": true }.

Agora roda um serviço em segundo plano para toda a sua conta de usuário

A v2 inicia um único servidor compartilhado em segundo plano. A TUI, a interface web e o app desktop se conectam a ele. É isso que faz o opencode pair (um link de uso único que expira após 5 minutos) e as tarefas em segundo plano (Ctrl+B) funcionarem. Se preferir não tê-lo:

opencode service set disabled true   # para o serviço e desativa o início automático
opencode service unset disabled      # reativa o serviço
opencode --standalone                # um servidor privado só para esta execução

O pareamento não funciona com o serviço desativado. O serviço também não lê o cli.json, então as configurações da interface de terminal só afetam o cliente de terminal.

Passo 6: plugins, Oh My OpenCode e a extensão do VS Code

Plugins da v1 não carregam na v2. A API de plugins é nova. Renomear plugin para plugins na config não basta. O código de cada plugin precisa ser portado (veja o guia de migração de plugins (opens in a new tab) oficial).

A falha mais comum foi o Oh My OpenCode (oh-my-openagent). No OpenCode 2.0.27, a versão 5.1.32 falhou com Plugin must export a default definition with an id and an effect or setup function (oh-my-openagent #10089 (opens in a new tab)). A correção (#10439 (opens in a new tab)) foi mesclada em 18 de outubro, e a 5.1.38 é a primeira release no npm que a inclui. Em 2 de novembro, o mantenedor confirmou que as versões atuais carregam no OpenCode 2 e mostram um aviso que aponta para o OmO Native, o app independente omo. Atualize o oh-my-openagent para a 5.1.38 ou mais nova antes de atualizar o OpenCode. Se preferir migrar para o omo, o README dele diz para rodar omo setup uma vez para levar chaves de provedores, servidores MCP, skills e escolhas de modelo. Se você está começando agora com o próprio harness, comece por Oh My OpenCode e OpenCode: instalação, configuração e correções.

Erro da extensão do VS Code Unrecognized flag: --port. Versões antigas da extensão iniciam a CLI com opencode --port <port>. A v2 removeu essa flag. Atualize a extensão para a v1.0.0 ou mais nova (Marketplace ou Open VSX). Até lá, abra um terminal no VS Code e rode opencode você mesmo (#55219 (opens in a new tab)).

Seus scripts que chamam o servidor. A API de servidor da v1 não existe mais. Porte-os para o pacote @opencode/client, que também encontra o serviço em segundo plano sozinho. No shell, opencode api chama a mesma API. O OPENCODE_SERVER_USERNAME não é mais suportado; o nome de usuário é sempre opencode. A GitHub Action do OpenCode foi removida na 2.2.0.

Problemas conhecidos depois do upgrade

Estas são issues do GitHub abertas ou corrigidas recentemente, das primeiras semanas da 2.x. As correções vêm dos mantenedores, de quem reportou ou do bot do projeto, em cada thread.

Como voltar para a 1.x

O guia de migração não cobre a volta. Esta é a ordem segura:

1. Remova a v2. opencode uninstall --dry-run mostra o que será removido. Depois opencode uninstall remove o programa e mantém sessões, config e estado no disco.
2. Reinstale a v1 com versão fixada: npm install -g opencode-ai@1.19.5 ou brew install anomalyco/tap/opencode (a fórmula sem -v2).
3. Se você converteu algum arquivo de config para sintaxe exclusiva da v2, restaure-o a partir de ~/opencode-v1-config-backup.
4. Se a v1 não conseguir ler o banco de sessões depois que a v2 o usou, restaure ~/opencode-v1-data-backup. Não testamos se a v1 abre um banco em que a v2 já escreveu. Conte com o backup.

Nota de segurança: o incidente no OpenCode Console

Isso é separado do upgrade, mas aconteceu na mesma semana. Em 17 de outubro, a equipe do OpenCode disse que alguém obteve acesso não autorizado a um sistema legado que estava sendo desativado (comunicado citado no Hacker News (opens in a new tab)). Chaves de provedores de terceiros salvas em um workspace do Console "may have been exposed" (podem ter sido expostas). A orientação deles: revogar e substituir essas chaves no painel de cada provedor e revisar o uso recente. Uma publicação posterior estimou em 1,4% a parcela de usuários do Console afetados, e o cofundador Dax Raad disse que a CLI e o app desktop não foram afetados (TechCrunch (opens in a new tab)). Se você já salvou chaves da OpenAI, Anthropic ou de outros provedores no Console, troque-as antes ou depois do upgrade.

O que de fato é novo no 2.0

Nada disto é necessário para concluir o upgrade. São os recursos que explicam por que a arquitetura mudou:

• Serviço em segundo plano compartilhado pela TUI, pela interface web e pelo app desktop, além do opencode pair para acesso web.
• Tarefas em segundo plano: pressione Ctrl+B para mandar um comando de shell ou subagente em execução para segundo plano enquanto o agente principal continua trabalhando.
• Code Mode: transforma servidores MCP e endpoints OpenAPI em funções que o agente pode encadear em um passo. Os servidores MCP o usam por padrão.
• Hot reload: o OpenCode pode escrever um plugin para si mesmo no meio da sessão e usá-lo na hora.
• @opencode/sdk e @opencode/client: o código por trás da CLI, para você criar seus próprios clientes.

Se você está escolhendo um agente de terminal do zero, em vez de atualizar um, Como usar o Codex cobre a alternativa mais próxima.

Guias relacionados

• Oh My OpenCode e OpenCode: instalação, configuração e correções
• Como usar o Codex
• Como usar o DeepSeek Harness
• Agentes de código em paralelo explicados