Oh My Opencode QuickStart para 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 sistema de orquestração multi-agente: um orquestrador delega tarefas a agentes especialistas que executam em paralelo.

agentes do oh my opencode com laptops e gpu

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

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

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

Por que o Oh My Opencode existe

OpenCode é um agente de codificação de IA de código aberto que funciona como uma interface 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 apertada. O resultado é um sistema onde tarefas de engenharia complexas — o tipo que normalmente exigiria que você supervisionasse 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 troca de fluxo de trabalho ativada por palavra-chave. Adicionar ultrawork ou ulw ao seu prompt ativa execução de fundo paralela, 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 o orquestrador rotear para eles automaticamente.

Este artigo usa Oh My Opencode, oh-my-opencode e Oh My OpenCode de forma intercambiável — todos se referem ao mesmo plugin no ecossistema OpenCode.

Pré-requisitos e terminologia

Você precisa do OpenCode instalado e funcionando primeiro. Veja nosso Guia Rápido do OpenCode para aprender como instalar, configurar e iniciá-lo.

Por padrão, opencode inicia a interface de 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 arquivo .env do projeto. A maneira mais rápida de resolver isso é:

opencode auth login
opencode auth list

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

Uma peculiaridade de nomeamento que vale a pena saber antecipadamente: o repositório upstream do GitHub agora é marcado 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 múltiplas rotas (instalador CLI, clone manual do repositório ou “deixe um agente instalá-lo”). A escolha certa depende se você quer um fluxo de instalação repetível ou controle manual total.

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

Para instalar bunx no linux:

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

Instalação automática com OpenCode

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

Instale e configure o oh-my-opencode seguindo as instruções aqui:
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, e também 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 agente”):

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 alto nível:

  • registra o plugin na configuração do OpenCode
  • gera atribuições de modelos usando disponibilidade de provedores 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 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 a variável de ambiente do caminho da configuração explicitamente antes de executar o instalador novamente.

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 uma localização reconhecida
  • agentes especialistas podem ser invocados
  • o acionamento da palavra-chave ultrawork funciona como esperado

Exemplos para copiar:

# Mostrar o arquivo de configuração do plugin (tente a localização 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 para analisar a arquitetura do projeto atual"

# Teste rápido de acionamento de ultrawork
opencode run "ulw liste todos os arquivos de configuração neste projeto"

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 busca 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 nos 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 troca de modo para a qual você recorrerá mais. Insira-o na descrição da tarefa e o sistema habilitará execução paralela em segundo plano, integração LSP, gerenciamento de contexto e decomposição automática de tarefas. Não é uma dica para o modelo — é um gatilho rígido que muda como toda a execução é estruturada.

Concorrência 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 ultrapassar isso produz conclusões instáveis e timeouts difíceis de depurar. Comece conservador e aumente apenas após execuções limpas.

Uma configuração mínima de concorrência parece com isso:

{
  "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 modelos 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 não está disponível

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

A resolução de modelos é em camadas: sua sobrescrita explícita vence, depois o fallback do provedor e, por fim, 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 usará apenas 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": "Forneça compensações concisas e uma recomendação clara"
    },
    "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 libera a autocompletar na maioria dos editores e detecta erros de digitação nos nomes dos agentes antes que você desperdice uma execução em uma configuração quebrada.

Integração MCP e ganchos

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 gerencia a adição, listagem 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órios reais”: eles mostram como acionar a orquestração, como mirar agentes especialistas e como manter os resultados verificáveis.

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

Use isso quando você entra 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 interface de terminal por padrão quando lançado sem argumentos.

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

Use @oracle para analisar a arquitetura deste repositório.
Identifique os principais contextos limitados, arestas de dependência principais e os componentes de maior risco.
Termine com um plano de refatoração que possa ser executado em pequenos PRs.

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

opencode run "Use @oracle para analisar a arquitetura deste repositório e propor um plano de refatoração em estágios"

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 em múltiplos arquivos ou camadas, ou quando quiser tarefas de fundo e agentes especialistas habilitados automaticamente.

Comece com um prompt ultrawork:

opencode run "ultrawork implemente uma nova extremidade /health com verificações de prontidão e vivacidade, adicione testes, atualize a documentação e verifique se funciona localmente"

A palavra-chave ultrawork ativa todos os agentes especialistas configurados, paralelismo de tarefas de fundo e ferramentas mais profundas de uma só vez. Você não precisa de prompts separados para planejamento, implementação e teste.

Quando você usa ultrawork, ainda pode orientar explicitamente o comportamento dos especialistas. Por exemplo, você pode forçar o design de arquitetura primeiro:

opencode run "ultrawork peça ao @oracle para projetar o contrato da extremidade e as dependências primeiro, depois implemente com mudanças mínimas e adicione testes"

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 com 2, execute algumas tarefas limpas e, em seguida, decida se deve aumentar. Ultrapassar o teto do seu plano não torna as coisas mais rápidas — torna-as instáveis.

Solução de problemas e melhores práticas

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 palavras-chave não injetou o prompt de modo ultrawork esperado, com investigação apontando para o gancho de detector de palavras-chave dedicado.

Na prática, os correções mais rápidas 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 regredir a detecção de palavras-chave

Script de instalação não consegue encontrar sua configuração OpenCode

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

Muitas tarefas em segundo plano ou problemas de limitação

Se você atingir limites de taxa, timeouts ou conclusões instáveis, a correção é sempre a mesma: reduza a concorrência e execute novamente. 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 geral:

  • 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 de provedor

Alguma discussão da comunidade em torno 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 funcionando 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.