OpenCode: como montar uma equipe de agentes de IA em qualquer gateway compatível com OpenAI

Conversar com um modelo logo encontra um limite: ele não enxerga seu projeto, não executa testes e não lembra o contexto. É por isso que todo mundo fala de agentes. Na essência, um agente é um modelo mais um harness: a estrutura ao redor dele, com habilidades, contexto, integrações e lógica multiagente. Claude Code e Codex estabeleceram o padrão, mas o primeiro está vinculado aos modelos da Anthropic, enquanto o segundo continua sendo um produto da OpenAI. OpenCode oferece uma terceira opção: licença MIT, 75+ provedores, modelos locais via Ollama ou vLLM e liberdade para escolher um modelo para cada função.

O artigo foi publicado no Habr AI e escrito por um funcionário do serviço Bothub, portanto a menção ao gateway e o link de indicação têm caráter publicitário. A configuração em si, porém, é universal e serve para qualquer endpoint compatível com OpenAI.

Conexão do provedor e armadilhas dos proxies

A versão atual da linha v2 é instalada com npm i -g @opencode/cli. O pacote antigo opencode-ai pertence à linha 1.x, e é fácil confundir os dois. Também há alternativas: brew, bun ou o script oficial de instalação.

O provedor é definido em opencode.json por meio do pacote @ai-sdk/openai-compatible: basta informar a baseURL do gateway e listar os IDs dos modelos. Em vez de colocar a chave na configuração ou em variáveis de ambiente, é melhor inseri-la por opencode auth login. Assim, ela fica fora dos arquivos do projeto.

A principal armadilha prática envolve os proxies. OpenCode roda sobre Bun, cujo fetch nativo lida de forma inconsistente com HTTP_PROXY e HTTPS_PROXY. Ao instalar plugins, pode aparecer o erro fetch() proxy.url must be a non-empty string: o agente retorna um objeto URL, mas fetch espera uma string. Bun não aceita socks5://; é preciso usar http://. Mesmo com a configuração correta, NO_PROXY precisa incluir localhost e 127.0.0.1; caso contrário, a interface pode entrar em um loop com as próprias requisições. A solução mais simples é remover todas as variáveis de proxy e reiniciar o serviço. Só depois disso faz sentido montar os agentes.

A equipe de agentes e a separação de permissões

OpenCode tem dois tipos de agentes. O primary é aquele com quem você conversa diretamente. Um subagent trabalha em uma sessão filha, com contexto próprio, e devolve apenas o resultado ao chat principal. Os agentes integrados build e plan são primary, enquanto general e explore são subagentes. Você pode deixá-los como estão e simplesmente adicionar os seus.

O autor criou sete funções:

• orchestrator (GPT-6.1 Sol) divide a tarefa e delega, sem escrever código;
• architect (Gemini 4 Argon) projeta módulos e fluxos de dados;
• coder (Claude Sonnet 5.5) implementa as mudanças e mantém os diffs mínimos;
• reviewer (Claude Opus 5.5) apenas revisa, sem produzir patches;
• security (GLM-5.3) procura vulnerabilidades;
• docs (GPT-6 Luna) escreve documentação;
• tests (GLM-5.3 Flash) escreve testes.

Os modelos são distribuídos segundo o princípio de usar um modelo caro onde é preciso mais capacidade de raciocínio e um barato onde ele basta. O autor ressalta que a escolha é parcialmente subjetiva: acompanhou as notícias e queria experimentar modelos diferentes, inclusive modelos abertos.

A regra central do esquema é que apenas coder recebe edit: allow. Se todos editarem arquivos, o diff cresce e deixa de ficar claro quem alterou o quê. Já reviewer e security mantêm bash: allow porque precisam executar linters, consultar git diff e rodar testes.

Restrições no harness, não no prompt

O modelo pode ignorar uma instrução no prompt como «não execute git push», especialmente quando a tarefa é ambígua. Uma proibição em permission não pode ser contornada. As regras são granulares: por padrão, bash pede confirmação; git status e git diff são permitidos; git commit e git push são bloqueados. Os agentes também podem sair do JSON e passar para arquivos markdown em .opencode/agents/<name>.md: o nome do arquivo vira o nome do agente, o frontmatter contém a configuração e o corpo se torna o prompt de sistema. Isso é útil quando os prompts são longos e precisam de controle de versão.

Como colocar isso em prática

Se você já trabalha com Claude Code ou Codex, vale experimentar OpenCode, nem que seja para comparar modelos nas suas próprias tarefas em um único dia. Leve este princípio: um agente tem permissão de escrita, os demais aconselham e revisam, e as restrições críticas são definidas por permissions. É melhor testar a seleção específica de modelos no seu próprio código, porque as escolhas do autor se baseiam mais em impressões do que em benchmarks. O artigo não substitui a documentação, mas pode poupar várias horas gastas com armadilhas comuns.