Como migrar do Claude Code para o OpenCode sem perder sua configuração?

Fala aí, beleza? Trocar de agente de código não dá medo por causa do modelo, dá medo por causa da rotina

O arquivo de regras que você ajustou por meses, as permissões que já não te perguntam nada, os MCPs conectados, os comandos que você digita no automático… tudo isso mora em arquivo, e arquivo não migra sozinho 🙂

O OpenCode é o agente de código open source mantido pela organização Anomaly no GitHub, em github.com/anomalyco/opencode, descrito lá mesmo como "The open source coding agent"

A boa notícia é que boa parte da sua configuração do Claude Code tem equivalente do outro lado

A notícia chata (melhor saber antes de começar): nem tudo tem

Então este post é um checklist do que reconfigurar ANTES de abrir o primeiro projeto, na ordem que evita retrabalho

Claude Code x OpenCode: onde cada configuração passa a morar

Antes de sair copiando arquivo, vale ver o mapa

Algumas coisas só mudam de endereço, outras mudam de natureza (ou seja, você não copia, você reescreve)

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Repara na última coluna, porque é ali que mora o retrabalho

Regras e skills você praticamente arrasta de um lado pro outro

Permissões, MCP e hooks você REESCREVE, e é melhor reservar tempo pra isso em vez de descobrir no meio do primeiro projeto

O que ter em mãos antes de migrar

Antes de tocar em qualquer arquivo, faz um inventário

Parece burocracia, mas é o que separa uma migração de meia hora de uma semana descobrindo o que sumiu

1. O inventário do que você já tem

O diretório .claude concentra os arquivos de configuração do seu fluxo no Claude Code: settings.json, hooks, skills, commands, subagents, workflows, rules e auto memory

Ele existe em dois escopos: o de projeto, dentro do repositório (com CLAUDE.md, .mcp.json e .worktreeinclude na raiz), e o global, em ~/.claude/

Abre os dois e lista item a item o que você realmente usa

Tem gente que descobre nessa hora que metade dos hooks estava lá de enfeite… 😀

2. Uma chave de API de algum provedor

Aqui vai o ponto que costuma pegar quem vem do Claude Code achando que leva a assinatura junto

A assinatura Claude Pro ou Max não é caminho oficial de acesso a modelos dentro do OpenCode

Existem plugins de terceiros que fazem isso, mas a Anthropic proíbe explicitamente, e o OpenCode deixou de vir com esses plugins a partir da versão 1.3.0

Ou seja: separa chave de API de um provedor antes de começar, senão você instala tudo e trava na primeira mensagem

Se o seu caso é autenticação por outro caminho, dá uma olhada em como funciona a autenticação do OpenCode com o Antigravity antes de conectar qualquer coisa

3. A decisão de versão: V1 ou OpenCode 2 em beta?

O OpenCode 2 está disponível como beta e ele NÃO substitui a versão 1

A instalação é por uma tag npm separada, o binário é outro e os dados ficam separados:

npm install -g @opencode-ai/cli@next

Depois disso você roda opencode2, e o opencode da V1 continua ali do lado, intacto

Decide isso ANTES, porque a V2 muda uma regra importante de leitura de instruções (volto nisso na seção de armadilhas)

Passo a passo da migração, na ordem que evita retrabalho

A ordem abaixo não é aleatória: ela começa pelo que o agente lê, passa pelo que ele precisa pra funcionar e só no fim mexe no que exige código

1. Regras do projeto: crie o AGENTS.md na raiz

O arquivo de regras de projeto do OpenCode é o AGENTS.md, na raiz, e dentro da ferramenta o comando /init cria um novo pra você

Se você não quiser criar nada agora, o OpenCode aceita as convenções do Claude Code como fallback: o CLAUDE.md do projeto vale se não existir AGENTS.md

O erro comum deste passo: manter os dois arquivos achando que eles somam

Não somam! Havendo AGENTS.md e CLAUDE.md, apenas o AGENTS.md é usado, e aquele contexto lindo que você escreveu no outro simplesmente não entra

2. Regras globais: ~/.config/opencode/AGENTS.md

As regras que valem pra todas as sessões ficam em um AGENTS.md dentro da pasta de configuração global, em ~/.config/opencode/AGENTS.md

O fallback aqui é o ~/.claude/CLAUDE.md, que vale se o arquivo global do OpenCode não existir

O erro comum deste passo: é a mesma armadilha do passo anterior, só que no escopo global, então checa se você não está com dois arquivos brigando

3. Decida se mantém ou desliga a compatibilidade com o Claude Code

Essa compatibilidade pode ser desligada por variáveis de ambiente: OPENCODE_DISABLE_CLAUDE_CODE, OPENCODE_DISABLE_CLAUDE_CODE_PROMPT e OPENCODE_DISABLE_CLAUDE_CODE_SKILLS

Porque isso importa? Porque se você desligar sem ter migrado o conteúdo, o agente fica sem regra nenhuma e você vai achar que ele "ficou burro"

Minha sugestão: migra primeiro, desliga depois, quando o AGENTS.md já estiver de pé

4. Credenciais e provedor

A autenticação de provedores é feita por comando, dentro da ferramenta com /connect ou pelo terminal:

opencode auth login

As credenciais ficam gravadas em ~/.local/share/opencode/auth.json

O erro comum deste passo: tratar esse arquivo como configuração normal de projeto

Ele guarda credencial, então trata com o carinho que você trataria qualquer .env

5. Modelos: escolha o principal e o barato

O OpenCode tem as opções provider, model e small_model, sendo o último o modelo mais barato pra tarefas leves, tipo gerar título

Dá também pra bloquear provedores carregados automaticamente com disabled_providers, ou fazer o inverso e usar enabled_providers como lista de permitidos

{
  "model": "provedor/modelo-principal",
  "small_model": "provedor/modelo-barato",
  "disabled_providers": ["provedor-que-eu-nao-uso"]
}

O catálogo de provedores vem do Models.dev, com mais de 75 provedores de LLM via AI SDK, incluindo suporte a rodar modelos locais

O erro comum deste passo: definir só o model e esquecer o small_model, e aí toda tarefinha boba roda no modelo caro

6. Permissões: reconfigure por ferramenta

Aqui a lógica muda de verdade

No Claude Code, as regras do settings.json são avaliadas em ordem fixa (deny, depois ask, depois allow) e o primeiro match decide, independente da especificidade da regra

No OpenCode, você declara por nome de ferramenta: read, edit, glob, grep, bash, task, skill, lsp, question, webfetch, websearch e external_directory

Cada uma recebe allow, deny ou ask, e dá pra usar padrão com curinga, tipo grep *

O erro comum deste passo: assumir que o padrão é restritivo

Não é! A maioria das permissões vem como allow, e só doom_loop e external_directory vêm como ask

Ou seja, se você tinha um ask no bash pra não deixar o agente sair rodando comando sozinho, isso NÃO vem junto e você tem que declarar de novo

É o mesmo tipo de decisão de quando você pensa em deixar o agente commitar por você: o limite tem que ser explícito, não presumido

7. MCP: reescreva os servidores

No Claude Code, o MCP de escopo de projeto vive no .mcp.json da raiz, e o de usuário é escrito por comando (claude mcp add --scope user grava na chave mcpServers de ~/.claude.json), com precedência local, depois project, depois user

No OpenCode, os servidores são declarados na configuração, na chave mcp.servers, com nome único e tipo:

{
  "mcp": {
    "servers": {
      "meu-servidor-local": {
        "type": "local",
        "command": ["npx", "-y", "pacote-do-mcp"],
        "environment": {
          "API_KEY": "{env:MINHA_CHAVE}"
        }
      },
      "meu-servidor-remoto": {
        "type": "remote",
        "url": "https://exemplo.com/mcp",
        "headers": {
          "Authorization": "Bearer {env:MEU_TOKEN}"
        }
      }
    }
  }
}

O local usa command em array, com cwd, environment e disabled opcionais

O remote usa url absoluta, com headers e oauth opcionais

A substituição de variáveis é feita com a sintaxe {env:NOME}, e o tempo limite é configurável em mcp.timeout

O erro comum deste passo: colar a chave de API direto no arquivo de configuração porque "é só pra testar"

Usa o {env:NOME}, sério, já vi gente se ferrar com isso indo pro Git

8. Skills: confira as pastas e o frontmatter

Essa parte é generosa com quem vem do Claude Code, porque o OpenCode carrega skills das próprias pastas E das pastas do Claude Code

No projeto ele olha .opencode/skills//SKILL.md, .claude/skills//SKILL.md e .agents/skills/*/SKILL.md

No global, ~/.config/opencode/skills//SKILL.md, ~/.claude/skills//SKILL.md e ~/.agents/skills/*/SKILL.md

O SKILL.md precisa começar com frontmatter YAML, e os campos obrigatórios são name e description (license, compatibility e metadata são opcionais):

---
name: revisao-de-pr
description: Revisa o diff atual e aponta riscos antes do merge
---

O erro comum deste passo: skill sem description ou com frontmatter mal formado, e aí ela simplesmente não aparece

9. Agentes e comandos: tudo vira Markdown

Agentes do OpenCode podem ser definidos em Markdown, em .opencode/agents/ ou ~/.config/opencode/agents/, e o nome do arquivo vira o nome do agente

O frontmatter tem description (obrigatório), mode (que aceita primary, subagent ou all), além de modelo e permissões

E o corpo do documento é o system prompt, o que é bem prático:

---
description: Explora o projeto e devolve um mapa dos arquivos relevantes
mode: subagent
---

Você é um agente de exploração. Leia a estrutura do projeto e devolva um resumo
dos arquivos que importam para a tarefa, sem editar nada.

Os comandos personalizados seguem a mesma ideia, em .opencode/commands/ ou ~/.config/opencode/commands/, com o nome do arquivo virando o nome do comando

Aqui muda o vocabulário dos placeholders: tem $ARGUMENTS, parâmetros posicionais, !comando pra injetar saída de shell e @arquivo pra incluir arquivos

---
description: Explica o que mudou no branch atual
---

Analise o diff abaixo e explique em português o que mudou:

!git diff

Foco: $ARGUMENTS

O erro comum deste passo: copiar comando do Claude Code e esperar que os placeholders sejam os mesmos

O conceito é o mesmo, a sintaxe não é, então revisa arquivo por arquivo

10. Hooks: aceite que não tem tradução em configuração

Esse é o passo que ninguém gosta

No Claude Code, os hooks são configurados no settings.json e disparam em eventos de ferramenta: PreToolUse e PostToolUse disparam em cada chamada de ferramenta dentro do loop do agente, inclusive nas chamadas feitas por subagentes

No OpenCode, a extensão por eventos é feita por plugin escrito em código, não por configuração

O plugin é um módulo JavaScript ou TypeScript que exporta funções recebendo um contexto e retornando um objeto de hooks, e os arquivos ficam em .opencode/plugins/ ou ~/.config/opencode/plugins/

O erro comum deste passo: tentar migrar hook por último e no susto

Se a sua rotina depende MUITO de hook (lint automático, bloqueio de comando, log), deixa isso pesar na decisão de migrar, porque aqui você não copia configuração, você escreve código

Armadilhas da migração (e como não cair nelas)

Três situações que aparecem justamente em quem já tinha tudo montado do outro lado

As regras somem ou parecem ignoradas

Sintoma: o agente age como se nunca tivesse lido o seu contexto de projeto, ignora convenção, ignora tom, ignora tudo

Causa: ou você está com AGENTS.md e CLAUDE.md convivendo (e só o AGENTS.md está sendo usado), ou você desligou a compatibilidade por uma das variáveis OPENCODE_DISABLE_CLAUDE_CODE, OPENCODE_DISABLE_CLAUDE_CODE_PROMPT ou OPENCODE_DISABLE_CLAUDE_CODE_SKILLS

Prevenção: escolhe UM arquivo por escopo e trata o outro como histórico

Se for desligar a compatibilidade, desliga só depois de ter movido o conteúdo

Na V2, o CLAUDE.md deixa de ser lido

Sintoma: funcionava na V1, você foi testar o OpenCode 2 e o contexto evaporou

Causa: no OpenCode 2, a descoberta de instruções reconhece apenas o AGENTS.md

O fallback pro CLAUDE.md e a precedência descrita na documentação anterior não se aplicam na V2

Prevenção: a orientação é direta, move o conteúdo pro AGENTS.md

Se você pretende ir pra V2 em algum momento, faz isso já na migração e resolve de uma vez

Plugin da V1 não roda na V2

Sintoma: você reescreveu seus hooks como plugin, ficou feliz, subiu pra V2 e nada acontece

Causa: plugins da V1 não funcionam na V2

Enquanto isso, definições de agentes, comandos, skills e demais arquivos em .opencode/ seguem funcionando normalmente

A configuração do cliente de terminal também muda: sai dos arquivos tui.json(c) em camadas e vai pra um único cli.json global, e essa parte é migrada automaticamente

Prevenção: decide a versão ANTES de investir tempo escrevendo plugin

O que aprendi rodando o OpenCode depois de vir do Claude Code

Agora a parte de quem sentou e usou 😀

Antes de gravar o vídeo eu desinstalei o OpenCode de propósito, pra instalar do zero junto com quem estava assistindo

Aí veio a primeira surpresa: abri a ferramenta e já tinha um modelo selecionado

Ou seja, alguma configuração tinha ficado salva em algum canto da máquina, e eu segui mesmo assim

Guarda esse detalhe pra sua migração: pode sobrar estado de instalação antiga na sua máquina, então não confia no "instalei do zero, então está limpo"

Eu instalei pelo npm porque já tinha Node aqui, copiando o comando direto da página de instalação (também tem opção via curl)

Depois abri a ferramenta digitando o nome dela no terminal, dentro de uma pasta criada só pro projeto, usando o VS Code como editor

A primeira coisa que fiz depois de abrir foi conectar um provider pelo /connect, porque sem modelo conectado não dá pra trabalhar, simples assim

No meu caso eu conectei minha própria assinatura do ChatGPT: o comando abriu um link, autorizei na aba do navegador, fechei a janela e voltei já autenticado

No meio do fluxo de conexão dá pra escolher o nível de esforço de raciocínio, e eu fiquei no médio como padrão

Dá pra mudar depois, e vale lembrar do óbvio: quanto maior o esforço, mais token consome

Depois troquei de modelo pelo /models, e ali apareciam também modelos gratuitos oferecidos pelo OpenCode Zen, que na minha máquina já aparecia conectado sem configuração extra

É um jeito de testar a ferramenta sem pagar nada, MAS com um aviso importante: usando modelo gratuito você provavelmente compartilha prompts e resultados

Lê os termos antes de sair usando com código de cliente, beleza?

Antes de partir pra código de verdade eu validei a instalação com um prompt trivial, tipo perguntar em que pasta eu estava e quais arquivos existiam ali

Parece bobo, mas é o teste que separa "o modelo não entendeu" de "a ferramenta nem está enxergando meu projeto"

Depois disso eu mandei um prompt de portfólio pessoal em HTML, CSS e JavaScript (página única, tema escuro, responsiva) e fui acompanhando o fluxo de raciocínio aparecendo na tela

Segui o resto do conteúdo com o modelo da OpenAI conectado pela assinatura

O que muda na cabeça de quem vem do Claude Code

O paralelo mais direto é esse: os custom commands do OpenCode são o equivalente aos slash commands, e existem comandos pra limpar sessão e pra compactar contexto

Os recursos que você espera estão lá: modo de planejamento e modo de construção, subagents (inclusive um de exploração do projeto), skills, conexão de MCPs e múltiplas sessões

Então a sensação de uso não é de downgrade, é de mudança de sotaque

O que eu senti falta mesmo foi de tradução automática de configuração: não tem aquele momento "importa tudo e segue o baile", você refaz na mão o que é permissão, MCP e hook

E aqui vai meu veredito honesto

Vale migrar agora se o seu incômodo é ficar preso a um único fornecedor de modelo, porque a premissa do OpenCode é justamente ser a casca aberta onde você escolhe o que roda dentro

Não vale migrar agora se a sua rotina inteira depende de hooks e automações finas em cima do settings.json, porque isso vira código do outro lado, e código dá manutenção

E um conselho que eu repito sempre: lê a documentação oficial em vez de depender só de vídeo (inclusive do meu)

A fonte fiel sempre foi a documentação, e o repositório no GitHub é ótimo pra entender a ferramenta pelo próprio código

No vídeo abaixo eu mostro esse caminho inteiro na prática: instalação, /connect, troca de modelo pelo /models e o primeiro projeto saindo do zero

Conclusão

Se você chegou até aqui, o próximo passo é bem concreto

Começa pelo AGENTS.md e pelas credenciais, porque sem regra e sem modelo conectado nada mais importa

Depois migra permissões e MCP, que são as duas coisas que mudam de natureza e costumam morder quem só copiou arquivo

Só no fim mexe em plugin, e só se você realmente depender daqueles hooks

E decide de forma consciente entre a V1 e o OpenCode 2 em beta, lembrando que na V2 a descoberta de instruções reconhece apenas o AGENTS.md e que plugin da V1 não roda lá

No fim das contas, migrar do Claude Code para o OpenCode não é mover arquivo, é remontar rotina

A parte boa é que rotina remontada com calma costuma sair melhor que a original 😉

Até o próximo post!