Oh My Opencode QuickStart para o OpenCode: Instalar, Configurar e Executar

Instale o Oh My Opencode e desenvolva mais rápido.

Conteúdo da página

O Oh My Opencode transforma o OpenCode em um harness de codificação multi-agente: um orquestrador delega trabalhos para agentes especialistas que executam em paralelo.

oh my opencode agents with laptops and gpu

O modelo mental mais curto que você precisa: instale o plugin e, em seguida, use a palavra-chave ultrawork (ou ulw) quando precisar de execução multi-agente com poder total.

Este guia rápido cobre a instalação e a configuração do primeiro dia. Uma vez que você estiver em funcionamento:

Para a cadeia de ferramentas de codificação de IA mais ampla, veja a visão geral das ferramentas de desenvolvimento de IA. Se você preferir uma alternativa sanduíxada e capaz no navegador ao OpenCode, o OpenHands adota uma abordagem arquitetural diferente para codificação de agentes.

Por que o Oh My Opencode existe

OpenCode é um agente de codificação de IA de código aberto que se executa como uma UI de terminal e gerencia execuções de CLI não interativas para scripts e automação.

O Oh My Opencode eleva esse teto muito mais alto. Ele adiciona uma camada completa de orquestração construída em torno do agente “Sisyphus”, colaboração multi-especialista e integração de ferramentas mais estreita. O resultado é um sistema onde tarefas de engenharia complexas — o tipo que normalmente exigiria que você vigiasse vários prompts — são planejadas, delegadas e verificadas em um único fluxo de trabalho.

Dois conceitos surgem constantemente, então domine-os antes de qualquer outra coisa:

  • Modo Ultrawork: uma mudança de fluxo de trabalho ativada por palavra-chave. Adicionar ultrawork ou ulw ao seu prompt ativa a execução paralela em segundo plano, integração LSP, gerenciamento de contexto e decomposição automática de tarefas — não é apenas uma escolha estilística.
  • Agentes especialistas: papéis nomeados como @oracle para arquitetura e @librarian para pesquisa e documentação. Você pode chamá-los explicitamente ou deixar que o orquestrador os encaminhe automaticamente.

Este artigo usa Oh My Opencode, oh-my-opencode e Oh My OpenCode intercambiavelmente — todos se referem ao mesmo plugin no ecossistema OpenCode.

Pré-requisitos e terminologia

Você precisa ter o OpenCode instalado e funcionando primeiro. Veja nosso Guia Rápido do OpenCode para aprender como instalar, configurar e iniciar.

Por padrão, o opencode inicia a UI do terminal quando executado sem argumentos, e você também pode usar opencode run ... para execução não interativa.

O Oh My Opencode requer pelo menos um provedor configurado. O OpenCode carrega provedores de credenciais, variáveis de ambiente ou um .env do projeto. A maneira mais rápida de resolver isso:

opencode auth login
opencode auth list

As credenciais vivem em ~/.local/share/opencode/auth.json.

Uma peculiaridade de nomenclatura que vale a pena saber desde o início: o repositório GitHub upstream agora é comercializado como oh-my-openagent (“anteriormente oh-my-opencode”), mas o nome do plugin e do pacote nas configurações ainda é oh-my-opencode. Ambos os nomes circulam em posts da comunidade — são a mesma coisa.

Guia rápido de instalação

Existem várias rotas (instalador CLI, clone manual do repositório ou “deixar um agente instalar”). A escolha certa depende de se você quer um fluxo de instalador repetível ou controle manual total.

Se você tiver o Bun instalado, bunx é o equivalente ao npx do Bun, projetado para executar pacotes npm rapidamente sem uma etapa de instalação global separada.

Para instalar o bunx no Linux:

curl -fsSL https://bun.com/install | bash

Instalação automática com OpenCode

Você pode executar o prompt no OpenCode e ele instalará o OmO automaticamente.

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

Ele fará algumas perguntas sobre suas assinaturas de LLM e registrará o Oh My Opencode nos plugins do OpenCode.

Caminho manual: execute o instalador do Oh My Opencode com bunx ou npx

Instalador interativo que pergunta sobre seus provedores e gera uma configuração “ótima” automaticamente, além de um modo não interativo para automação e agentes.

Instalação interativa:

bunx oh-my-opencode install
# ou se você preferir ferramentas npm
npx oh-my-opencode install

Instalação não interativa (útil para scripts de provisionamento, imagens de CI ou “instalações de agentes”):

bunx oh-my-opencode install --no-tui \
  --claude=<yes|no|max20> \
  --openai=<yes|no> \
  --gemini=<yes|no> \
  --copilot=<yes|no>

O que o instalador faz, em um nível alto:

  • registra o plugin na configuração do OpenCode
  • gera atribuições de modelos usando a disponibilidade do provedor e regras de fallback
  • escreve a configuração oh-my-opencode junto com os arquivos de configuração do OpenCode

Caminho manual: clone o repositório e execute o script de instalação

Também existe um fluxo manual “humano”: clone o repositório, instale as dependências e, em seguida, execute um script de instalação que detecta a localização da sua configuração do OpenCode, faz um backup e mescla as configurações.

git clone https://github.com/code-yeongyu/oh-my-opencode.git ~/.oh-my-opencode
cd ~/.oh-my-opencode
npm install
npm run install

Se o script não conseguir encontrar sua configuração do OpenCode automaticamente, defina explicitamente a variável de ambiente do caminho da configuração antes de reexecutar o instalador.

Lista de verificação de verificação rápida

Após a instalação, valide três coisas:

  • seu arquivo de configuração do Oh My Opencode existe em um local reconhecido
  • agentes especialistas podem ser invocados
  • o acionamento da palavra-chave ultrawork funciona conforme o esperado

Exemplos para copiar:

# Mostrar o arquivo de configuração do plugin (tente o local que corresponde à sua configuração)
cat .opencode/oh-my-opencode.json
cat ~/.config/opencode/oh-my-opencode.json

# Teste rápido de agente
opencode run "Use @oracle to analyse the architecture of the current project"

# Teste rápido de acionamento ultrawork
opencode run "ulw list all configuration files in this project"

Se os três passarem, você está genuinamente pronto — não apenas instalado.

Configuração e ajuste

Onde a configuração reside e como a precedência funciona

O Oh My Opencode procura arquivos de configuração em uma ordem de prioridade, com a configuração de nível de projeto tendo precedência sobre a configuração de nível de usuário. A ordem de pesquisa documentada é:

  • .opencode/oh-my-opencode.json (nível de projeto, maior prioridade)
  • ~/.config/opencode/oh-my-opencode.json (nível de usuário no macOS e Linux)
  • %APPDATA%\opencode\oh-my-opencode.json (nível de usuário no Windows)

O próprio OpenCode também suporta múltiplas fontes de configuração e as mescla em vez de substituí-las, com fontes posteriores sobrescrevendo as anteriores apenas quando as chaves conflitam. Isso importa porque você geralmente quer uma base global estável mais sobrescritas por repositório.

Suporte JSONC para configurações sensatas

Tanto o OpenCode quanto o Oh My Opencode suportam JSONC, o que significa que você pode manter comentários e vírgulas finais em arquivos de configuração sem quebrar a análise. Isso é especialmente útil para documentar por que certos limites ou modelos foram escolhidos.

A palavra-chave “ultrawork” e o que ela habilita

ultrawork (ou ulw) é a mudança de modo para a qual você mais recorrerá. Insira-o na sua descrição de tarefa e o sistema habilitará a execução paralela em segundo plano, integração LSP, gerenciamento de contexto e decomposição automática de tarefas. Não é um dica para o modelo — é um gatilho rígido que muda como toda a execução é estruturada.

Concurrencia e tarefas em segundo plano

O Oh My Opencode expõe controles de concorrência para execução em segundo plano via sisyphus.max_concurrent_tasks.

Não persiga alta concorrência aqui. Cada plano de provedor tem um teto — o Claude Max20, por exemplo, chega a 3 tarefas paralelas — e empurrar além disso produz conclusões instáveis e tempos de espera difíceis de depurar. Comece conservador e só aumente após execuções limpas.

Uma configuração de concorrência mínima parece-se assim:

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "task_timeout": 300
  }
}

Uma concorrência de 2 é um ponto de partida seguro para a maioria dos planos.

Roteamento de modelos por agente e por categoria

O Oh My Opencode é construído em torno da ideia de que tarefas diferentes se beneficiam de modelos diferentes, então a configuração suporta:

  • seleção de modelo por agente, variantes e extensões de prompt
  • roteamento baseado em categoria para trabalho “rápido” vs “profundo”
  • modelos de fallback quando seu provedor preferido estiver indisponível

O mergulho profundo em agentes especializados cobre o sistema completo de roteamento de modelos em detalhes — incluindo por que certos agentes não devem ser trocados para a família de modelo errada, as cadeias de fallback completas e como substituir modelos com segurança para configurações auto-hospedadas.

A resolução de modelo é em camadas: sua substituição explícita ganha, depois o fallback do provedor, depois o padrão do sistema. A cadeia de fallback começa com seus provedores nativos e pode cair para alternativas como o GitHub Copilot se nada mais estiver disponível — o que significa que um agente mal configurado é improvável de falhar silenciosamente; ele apenas usará um modelo mais fraco.

Uma configuração inicial prática que você pode adaptar (JSONC recomendado):

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  // Mantenha a concorrência conservadora até confiar nos limites do seu provedor
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "task_timeout": 300
  },

  // Ajuste de agentes
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "openai/gpt-5.2",
      "variant": "high",
      "temperature": 0.7,
      "prompt_append": "Provide concise tradeoffs and a clear recommendation"
    },
    "librarian": {
      "enabled": true,
      "model": "google/gemini-3.1-pro"
    }
  },

  // Roteamento de categoria para consultas rápidas vs trabalho mais profundo
  "categories": {
    "quick": { "model": "opencode/gpt-5-nano" },
    "visual-engineering": { "model": "google/gemini-3.1-pro" }
  }
}

O campo $schema vale a pena manter — ele desbloqueia autocompletamento na maioria dos editores e detecta erros de digitação nos nomes dos agentes antes de você desperdiçar uma execução em uma configuração quebrada.

Integração MCP e hooks

O Oh My Opencode suporta servidores MCP (Model Context Protocol) via um bloco de configuração onde você define o comando do servidor, argumentos e variáveis de ambiente.

Na prática, o caminho mais fácil é gerenciar MCPS diretamente através do OpenCode usando o grupo de comandos opencode mcp — ele lida com adicionar, listar e autenticação OAuth sem que você toque nos arquivos de configuração manualmente.

Exemplos de fluxo de trabalho que você pode copiar

Os dois exemplos abaixo são intencionalmente moldados como “repositório real”: eles mostram como acionar a orquestração, como mirar agentes especialistas e como manter resultados verificáveis.

Exemplo: Revisão de arquitetura com Oracle e um mapa de repositório

Use isso quando você ingressa em uma nova base de código ou herda um serviço e precisa de uma visão rápida e acionável da arquitetura. O Oracle é um especialista de leitura — ele não pode fazer alterações, apenas aconselhar.

Execute-o da raiz do seu projeto:

opencode

O OpenCode iniciará sua UI de terminal por padrão quando lançado sem argumentos.

Em seguida, peça ao Oracle que produza uma análise de arquitetura e um plano concreto de refatoração ou modularização:

Use @oracle to analyse the architecture of this repository.
Identify the key bounded contexts, major dependency edges, and the highest risk components.
End with a refactoring plan that can be executed in small PRs.

Para registro ou scripting, pule a TUI completamente e use opencode run:

opencode run "Use @oracle to analyse the architecture of this repository and propose a staged refactor plan"

opencode run passa o prompt diretamente e sai quando terminar — exatamente o que você quer para etapas de CI ou pipelines de automação.

Exemplo: Implementação de recurso completo com orquestração ultrawork

Use isso quando você precisar de um recurso que toque vários arquivos ou camadas, ou quando quiser tarefas em segundo plano e agentes especialistas habilitados automaticamente.

Comece com um prompt ultrawork:

opencode run "ultrawork implement a new /health endpoint with readiness and liveness checks, add tests, update documentation, and verify it runs locally"

A palavra-chave ultrawork ativa todos os agentes especialistas configurados, paralelismo de tarefas em segundo plano e ferramentas mais profundas em uma única vez. Você não precisa de prompts separados para planejamento, implementação e testes.

Quando você usa ultrawork, ainda pode direcionar explicitamente o comportamento do especialista. Por exemplo, você pode forçar o design de arquitetura primeiro:

opencode run "ultrawork ask @oracle to design the endpoint contract and dependencies first, then implement with minimal changes and add tests"

Combinar ultrawork com menções explícitas de agentes como @oracle é o ponto ideal: você obtém orquestração completa, mas ainda controla qual especialista lida com as decisões de design críticas.

Uma coisa a acertar para tarefas ultrawork maiores: mantenha a concorrência dentro dos limites do seu provedor. Comece em 2, execute algumas tarefas limpas e, em seguida, decida se deve aumentar. Empurrar além do teto do seu plano não torna as coisas mais rápidas — torna-as pouco confiáveis.

Solução de problemas e melhores práticas

A palavra-chave Ultrawork não aciona

Se ulw ou ultrawork estiverem sendo ignorados, trate isso como um sinal para verificar o carregamento do plugin e a compatibilidade de versão. Houve pelo menos uma regressão relatada onde a detecção de palavra-chave não injetou o prompt de modo ultrawork esperado, com a investigação apontando para o hook de detector de palavra-chave dedicado.

Na prática, os reparos mais rápidos são:

  • confirme que o plugin está registrado e os arquivos de configuração estão presentes (veja a lista de verificação de verificação anterior)
  • atualize o OpenCode ou o plugin se você estiver em uma versão conhecida por regressar a detecção de palavras-chave

O script de instalação não consegue encontrar sua configuração do OpenCode

Verifique se o OpenCode está instalado (opencode --version), em seguida, defina uma variável de ambiente de caminho de configuração explícita antes de reexecutar o instalador.

Muitas tarefas em segundo plano ou problemas de throttling

Se você atingir limites de taxa, tempos de espera ou conclusões instáveis, a correção é sempre a mesma: reduza a concorrência e reexecute. Perseguir maior paralelismo quando seu provedor já está limitando você é uma batalha perdida.

Quando você não deve usar ultrawork

Ultrawork é poderoso, mas não é gratuito — cada agente paralelo custa tokens e conta contra seus limites de taxa. Reserve-o para grandes refatorações, trabalho de recursos full-stack e tarefas complexas de múltiplas etapas. Para uma pequena edição de arquivo único ou uma pergunta rápida, um prompt simples é mais rápido e barato.

Uma boa regra de bolso:

  • use prompts normais para pequenas edições e perguntas diretas
  • use ultrawork quando você quiser que o sistema decomponha, delegue, execute e verifique em todo o repositório

Nota de conformidade sobre termos do provedor

Alguma discussão da comunidade ao redor deste ecossistema toca em restrições de provedores e termos de serviço, particularmente em torno de OAuth de terceiros e camadas de compatibilidade. Estas são restrições reais — revise os termos do seu provedor antes de executar fluxos de trabalho automatizados ou paralelos em escala e não assuma que uma integração funcional significa uma permitida.

Pronto para aprofundar? O mergulho profundo em agentes especializados explica o papel de cada agente, requisitos de modelo e opções de auto-hospedagem. Para dados de desempenho honestos e riscos de faturamento relatados pela comunidade, veja o artigo de experiência do Oh My Opencode.

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.