Guia prático de como usar o OpenCode: primeiros passos, 7 dicas e quando somar Oh My OpenCode

Name

Soren Atelier

Atualizado em 17/03/2026

O OpenCode é um agente de coding open source feito para o terminal, com app desktop, extensão de IDE e uma camada de modelos agnóstica a provider. Para a maioria dos devs, a pergunta útil não é "ele consegue escrever código?". É "quando devo ficar no OpenCode puro e quando faz sentido adicionar uma camada de orquestração mais pesada, como o Oh My OpenCode?"

A forma mais prática de começar é simples: use o OpenCode sozinho primeiro. Entenda o fluxo plan e build, crie um AGENTS.md de verdade e se acostume com permissões e comandos personalizados. Só depois vale adicionar o Oh My OpenCode se você realmente precisa de roteamento multi-model, especialistas em background e um harness mais opinativo para continuar até a tarefa ficar pronta.

Se quiser contexto mais amplo antes do hands-on, comece pelo hub de AI Coding, por Como usar o Codex e por Parallel Code Agents explicados. Se a ideia for comparar frameworks de agentes em um nível mais alto, a página OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot é o melhor complemento.

Resposta rápida: usar só OpenCode ou combinar com Oh My OpenCode?

O OpenCode sozinho já cobre o loop central que a maioria dos devs precisa: entender o codebase, planejar a mudança, editar com segurança e trabalhar a partir do terminal. O par com Oh My OpenCode é útil, mas não é o primeiro passo.

O que o OpenCode é de fato

O OpenCode é um agente de coding open source pensado para um fluxo centrado no terminal. A documentação oficial e o README atual o descrevem como:

• um agente de coding focado em TUI
• um app desktop em beta
• uma extensão de IDE
• um sistema agnóstico a provider, que funciona com OpenAI, Anthropic, Google e outros backends
• um conjunto de ferramentas com agents embutidos, permissões, comandos personalizados, regras, formatação e suporte a LSP

O ponto mais importante é este: o OpenCode não é só uma janela de chat com geração de código. Ele é uma superfície de workflow de agente. Você pode usá-lo para:

• explorar repos desconhecidos
• planejar mudanças antes de editar
• editar arquivos e executar comandos de shell
• criar regras de projeto com AGENTS.md
• definir slash commands repetíveis
• apertar ou relaxar permissões conforme o risco do repo

Um detalhe prático importa porque tutoriais antigos já ficaram desatualizados. Em 17 de março de 2026, os releases atuais do OpenCode são publicados a partir de anomalyco/opencode, e o último release do GitHub é o v1.2.27, publicado em 16 de março de 2026. Se você cair em repos arquivados ou em páginas com redirecionamento antigo, está vendo contexto histórico, não o alvo atual de instalação.

Como começar com o OpenCode

1. Instale o OpenCode

O quick start oficial é:

curl -fsSL https://opencode.ai/install | bash

Também dá para instalar via Homebrew, npm, Scoop, Chocolatey, mise ou nix, mas o script de instalação é o caminho mais rápido quando você só quer começar.

2. Conecte um provider e abra um projeto real

Depois de abrir, a documentação oficial recomenda usar:

/connect

Em seguida, selecione opencode no TUI e conclua a autenticação em opencode.ai/auth, ou configure outro provider que você já usa.

A regra prática é simples: não comece pelo maior repo com o pedido mais vago possível. Abra um projeto que você conheça bem o suficiente para revisar.

3. Rode /init antes de pedir trabalho sério

O OpenCode consegue gerar um arquivo AGENTS.md para o repo:

/init

Esse arquivo dá instruções duráveis para o agente. Comitar isso no Git reduz repetição de prompt e deixa o comportamento mais estável entre sessões.

4. Comece em plan, não em build

O OpenCode vem com dois agents embutidos que você alterna com Tab:

• build para trabalho de desenvolvimento completo
• plan para análise e exploração de código

No primeiro pedido, use plan e mantenha o escopo pequeno:

Resuma o fluxo de build, teste e release deste repositório.
Mostre também os principais pontos de entrada da aplicação.
Ainda não edite nada.

Só mude para build depois que o mapa do repo fizer sentido.

7 dicas práticas de uso

Dica 1: use plan como padrão em codebases que você ainda não conhece

A separação entre planejamento e edição não existe só por segurança. Ela melhora a qualidade da resposta.

Se você pular direto para build, o modelo pode começar a editar antes de validar entendimento. Se começar com plan, você ganha uma rodada barata para confirmar arquitetura, nomes, fluxo de testes e possível impacto.

Um bom prompt é este:

Explique como a autenticação funciona em @src/auth/index.ts.
Depois proponha duas opções mínimas de correção.
Não edite ainda.

O uso de @ para arquivos é muito útil porque o OpenCode suporta busca flexível de arquivos diretamente no prompt.

Dica 2: trate /init e AGENTS.md como multiplicadores, não como burocracia

Muita gente subestima essa parte porque ela parece trabalho de documentação.

Não é. AGENTS.md é o lugar certo para colocar:

• comandos de build, teste e lint
• estrutura do repo e limites entre pacotes
• regras de estilo e expectativa de review
• restrições do tipo "não mexa aqui"
• definição de pronto

Se você pular isso e repetir as regras no chat toda vez, o resultado fica mais barulhento e mais caro.

Se esse tema for relevante para você, vale ler Como construir um agente estilo Claude Code com Claude Agent SDK, porque a mesma lógica aparece do lado de quem cria agentes.

Dica 3: aperte as permissões antes de confiar no padrão

O OpenCode é configurável, e a documentação oficial de permissões deixa isso claro: você pode definir ações como allow, ask ou deny.

Para um repo novo, uma política inicial prática é:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Isso deixa o agente um pouco mais lento, mas evita surpresas enquanto você ainda está aprendendo o comportamento dele. Depois que houver confiança, dá para afrouxar seletivamente comandos de baixo risco e edições rotineiras.

Dica 4: crie alguns comandos personalizados antes de adicionar mais ferramentas

O OpenCode já suporta comandos nativos como /init, /undo, /redo, /share e /help. Ele também permite adicionar comandos personalizados via config ou arquivos markdown em .opencode/commands/.

Ou seja, muitos ganhos de fluxo avançado ainda não exigem um framework novo. Você pode criar comandos como:

• /test
• /review
• /ship-check
• /seo-page

Por exemplo:

---
description: Executa os testes relacionados à mudança atual
agent: build
---
 
Rode apenas os testes relevantes para os arquivos tocados nesta sessão.
Resuma primeiro as falhas e, depois, proponha a menor correção crível.

Isso mantém os prompts comuns curtos e fáceis de revisar.

Dica 5: use bem um provider antes de tentar conectar todos

O modelo agnóstico a provider do OpenCode é uma força, mas também pode levar a setup em excesso cedo demais.

Não comece ligando cinco providers, três fallback chains e uma matriz de modelos customizada. Comece com o provider que você já paga e entende. Depois, expanda só quando souber como o OpenCode se comporta de fato.

Se você é novo na categoria, Como usar o Codex também vale a leitura. A direção do produto é diferente, mas a lição operacional é a mesma: tarefas mais restritas funcionam melhor do que tool sprawl.

Dica 6: saiba quando terminal, desktop e IDE vencem

O OpenCode já é maior do que um binário de terminal.

Use o terminal quando quiser o loop mais rápido entre prompt, edição e teste.

Use o app desktop quando visibilidade de review, gestão de sessões e conforto visual forem mais importantes.

Use a extensão de IDE quando o editor atual já for o seu centro de controle e você não quiser alternar de contexto.

O erro não é escolher a interface errada para sempre. O erro é usar a interface errada para a tarefa atual e culpar o agente por isso.

Dica 7: deixe o OpenCode organizar a mudança, mas revise o diff como engenheiro

A documentação oficial observa que o OpenCode pode usar formatadores específicos da linguagem depois da edição. Isso ajuda bastante, mas formatter não é sinônimo de qualidade de mudança.

Ainda vale revisar:

• se a implementação realmente bate com o requisito
• se os comandos de bash que ele quer executar fazem sentido
• se a orientação do AGENTS.md está sendo seguida
• se o patch não ficou amplo demais para a tarefa

Agentes de coding reduzem digitação. Eles não substituem julgamento de engenharia.

Quando vale somar o Oh My OpenCode

O Oh My OpenCode não é o OpenCode em si. Ele é uma camada de orquestração mais opinativa construída em cima do OpenCode.

A documentação e o README do projeto atual o descrevem como um harness multi-model que adiciona:

• uma camada de orquestração mais forte para agentes especializados
• roteamento de modelos por categoria
• agentes em background e trabalho paralelo
• workflows orientados a MCP
• um estilo de execução que insiste até a tarefa terminar
• comandos como ultrawork / ulw

Isso fica interessante quando o OpenCode puro começa a parecer leve demais para o tipo de trabalho que você faz.

O valor do Oh My OpenCode não está em dizer que o OpenCode é fraco. O valor está em oferecer um harness mais opinativo: mais delegação, mais orquestração, mais especialização de modelo e menos steering manual depois que a tarefa começa.

Como combinar OpenCode com Oh My OpenCode

1. Faça o OpenCode puro funcionar primeiro

Não instale um harness em cima de uma base que você nem testou.

Antes de adicionar qualquer coisa, confirme que você consegue:

• instalar o OpenCode
• autenticar um provider
• rodar /init
• concluir uma tarefa em plan
• concluir uma tarefa em build

Se essa base ainda estiver instável, adicionar o Oh My OpenCode só vai tornar o debugging mais difícil.

2. Entenda a nomenclatura antes de instalar

Há um detalhe de nome que confunde muita gente:

• o repo GitHub atual é code-yeongyu/oh-my-openagent
• o branding e o nome do pacote ainda usam Oh My OpenCode
• o comando de instalação continua sendo oh-my-opencode

Em 17 de março de 2026, trate isso como a mesma linha de projeto.

3. Instale o harness com o installer oficial

O caminho manual mais simples é:

bunx oh-my-opencode install

O próprio projeto também incentiva usar um agente de IA para ler o guia de instalação e seguir os passos. Isso combina com a filosofia de workflow do projeto.

4. Comece por um comando de alto valor, não pela lista inteira de recursos

O hábito principal é:

ultrawork

ou o atalho curto:

ulw

Isso é útil, mas não trate como mágica. Primeiro use em uma tarefa de tamanho médio e com definição de pronto clara. Bons casos:

• corrigir um bug contido junto com testes relacionados
• implementar uma feature com escopo fechado
• limpar um conjunto barulhento de arquivos
• fazer pesquisa paralela + implementação em um repo que você já entende

Más primeiras escolhas:

• arquitetura greenfield vaga
• migração em produção sem rollback plan
• repo sensível sem política de permissão revisada

5. O melhor ganho aparece quando você realmente aproveita a orquestração multi-model

O Oh My OpenCode fica mais defensável quando o seu trabalho se beneficia de:

• modelos diferentes para planejamento, raciocínio e frontend
• especialistas em background
• uso mais amplo de MCP
• disciplina maior de subagents

Se o seu dia a dia é mais "corrige um arquivo, roda testes e segue", o OpenCode puro muitas vezes já basta.

OpenCode sozinho vs OpenCode + Oh My OpenCode

A recomendação prática é simples:

1. Aprenda o OpenCode puro.
2. Escreva e comite um AGENTS.md real.
3. Adicione 2 ou 3 comandos personalizados.
4. Aperte permissões.
5. Só então decida se o seu workload justifica o Oh My OpenCode.

Armadilhas comuns

Confundir OpenCode com OpenClaw

Não são o mesmo projeto.

Se você procurou OpenClaw, mas quer o agente de coding open source para terminal com plan, build, /init e compatibilidade com Oh My OpenCode, então provavelmente está falando de OpenCode.

Usar links antigos de repositório

Já existe churn suficiente em referências antigas do OpenCode para justificar uma checagem do caminho de instalação antes de seguir qualquer tutorial aleatório. Comece sempre pela documentação oficial.

Instalar o harness antes de aprender a base

Se você não entende como o OpenCode puro se comporta, não consegue saber se um resultado estranho veio do agente base, do harness, do provider ou das regras do repo.

Comprar provider demais logo no primeiro dia

Flexibilidade de provider é útil, mas a maioria dos usuários deve começar com o acesso que já possui e conhece.

FAQ

OpenCode é o mesmo que OpenClaw?

Não. São projetos diferentes. Este guia é sobre o OpenCode, o agente de coding open source documentado em opencode.ai.

Preciso do Oh My OpenCode para usar bem o OpenCode?

Não. O OpenCode já é útil sozinho. O Oh My OpenCode faz mais sentido quando você quer orquestração mais pesada, delegação mais opinativa e um workflow multi-model mais amplo.

O que devo fazer primeiro depois de instalar?

Rode /connect, abra um projeto real, rode /init, mude para plan e peça um resumo do repo antes de solicitar edições.

Começo pelo terminal, pelo desktop ou pela IDE?

Comece pelo terminal, a menos que você já saiba que prefere fluxos de desktop mais focados em review ou um fluxo nativo do editor.

Qual é o sinal mais simples de que já vale usar o Oh My OpenCode?

Você já usa o OpenCode com conforto, seu AGENTS.md está realmente estabelecido e você percebe com frequência que gostaria de mais orquestração entre passes especializados.

Guias relacionados

• Hub de AI Coding
• Como usar o Codex
• Parallel Code Agents explicados
• Como construir um agente estilo Claude Code com Claude Agent SDK
• OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot