O que é o OpenCode e como ele funciona no terminal?

Agente de codificação rodando no terminal deixou de ser curiosidade e virou ferramenta de trabalho, e o nome OpenCode aparece em toda conversa sobre isso

Fala aí, beleza? Se tu caiu aqui, é bem provável que tenha visto o nome circulando em algum lugar e queira entender o que a ferramenta faz ANTES de sair instalando qualquer coisa na máquina

Bora do começo então: o que é, qual problema ele resolve e como ele se comporta dentro do terminal 😀

Qual problema o OpenCode resolve:

O OpenCode é um agente de IA para código, open source, com interface de terminal (TUI), app desktop e integração com IDE

A ideia é simples de entender: em vez de tu ficar copiando código de uma janela de chat e colando no editor, o agente lê e altera o projeto direto de onde tu já trabalha

O código do projeto fica no repositório oficial no GitHub, em github.com/anomalyco/opencode, e é distribuído sob licença MIT

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

E o diferencial dele qual é?

Modelo

O OpenCode usa o AI SDK e o Models.dev por baixo, e suporta mais de 75 provedores de LLM, incluindo modelos rodando localmente na tua máquina

Se você conhece um gerenciador de pacotes tipo NPM ou composer, a lógica de aproximação é parecida: a ferramenta não carrega um fornecedor único embutido, ela sabe conversar com um catálogo

E tem ainda o OpenCode Zen, que é o gateway de modelos do próprio projeto, pra quem não quer sair caçando chave de API por aí

Como o OpenCode funciona no terminal, passo a passo:

Esse é o caminho do primeiro contato, sem pular etapa

1. Instalar a ferramenta

O script oficial roda com um comando só:

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

Se tu prefere pelo npm, dá na mesma:

npm install -g opencode-ai

E no macOS ou Linux, pelo Homebrew, usando o tap anomalyco:

brew install anomalyco/tap/opencode

O erro comum deste passo: tentar tocar tudo no Windows nativo

A documentação recomenda usar o WSL (Windows Subsystem for Linux) pra melhor experiência no Windows, e mantém uma página só sobre isso, então não adianta brigar com o terminal padrão

2. Rodar e entender o que subiu

Quando tu executa o OpenCode, ele sobe uma TUI e um servidor

"Que servidor?", tu deve estar pensando

A TUI é o cliente, e quem faz o trabalho pesado é esse servidor, que inclusive expõe uma especificação OpenAPI 3.1

Ou seja: aquilo que parece só uma telinha bonita no terminal é, na real, uma arquitetura cliente-servidor rodando na tua máquina, o que abre porta pra integração de outros clientes depois

3. Conectar um provedor de modelo

A chave de API do provedor entra pelo comando /connect, digitado dentro da própria interface

O erro comum deste passo: sair procurando arquivo de configuração pra colar a chave na mão

O caminho previsto é o /connect mesmo, dentro do OpenCode

4. Usar os comandos da TUI

Na interface, os comandos são acionados digitando / seguido do nome do comando

A maioria também tem atalho de teclado, com ctrl+x como leader key padrão

O erro comum deste passo: tentar decorar atalho de cabeça no primeiro dia

Começa pelo /, vê a lista, e os atalhos entram no automático depois, beleza?

Agentes Build e Plan: quando usar cada um?

Aqui mora uma das partes mais massa da ferramenta

O OpenCode traz dois agentes primários embutidos, o Build e o Plan, além de três subagentes embutidos

A troca entre os primários é feita com a tecla Tab (ou pela keybind switch_agent, se tu configurar outra)

Já os subagentes são chamados com @ na própria mensagem

Na prática, como eu penso essa divisão:

Base de código desconhecida, aquele projeto que tu pegou pra manter e não sabe nem onde fica a lógica principal? Plan

Ele analisa e planeja sem tocar em arquivo, e isso é MUITO mais tranquilo do que soltar um agente com todas as ferramentas num terreno que tu não conhece

Depois que o plano está de pé e tu concordou com ele, aí sim tu passa o bastão pro Build

Configuração, regras do projeto e integrações:

Uma dúvida que sempre aparece: onde essa coisa vive no disco?

A configuração global fica em ~/.config/opencode/opencode.json, e a configuração de projeto num opencode.json na raiz do projeto

O modelo é indicado no formato provider/model-id, nas opções provider, model e small_model

E as regras do projeto?

As regras do projeto ficam num arquivo AGENTS.md na raiz, e as regras globais em ~/.config/opencode/AGENTS.md

É ali que tu escreve o que o agente precisa saber antes de encostar no código: convenção do time, o que nunca mexer, como rodar os testes, por aí vai

Integrações que valem o clique:

O OpenCode se integra a servidores LSP e usa os diagnósticos como feedback pro agente, com ativação e ajuste na seção lsp da configuração

Isso muda o jogo, porque o agente para de escrever no escuro e passa a receber o mesmo erro que o teu editor mostraria, tema que rende um papo à parte sobre o LSP dentro do OpenCode

Além disso ele suporta servidores MCP, que têm página própria na documentação, e permite compartilhar um link de qualquer sessão pra referência ou depuração

Esse share link é ULTRA útil quando tu quer mostrar pra outra pessoa exatamente o que aconteceu naquela conversa com o agente

Quanto custa usar o OpenCode na prática?

A ferramenta em si é MIT, então o custo não está no software: está no modelo que tu pluga nele

Duas opções saem do próprio projeto:

• OpenCode Zen: o gateway de modelos do projeto, com cobrança pay-as-you-go, por 1 milhão de tokens
• OpenCode Go: plano que custa US$ 5 no primeiro mês e US$ 10 por mês depois, com acesso a modelos de código

E tem o caminho de conectar um provedor externo com a tua própria chave, que é justamente o que eu fiz pra testar

O que aconteceu quando eu testei com provedor externo:

No vídeo abaixo eu mostro esse caminho inteiro: rodei o comando de conexão dentro do OpenCode, escolhi o provedor na lista e colei a chave de API criada na plataforma

Tome cuidado aqui! A chave precisa ser colada EXATAMENTE como está: um caractere ou até um espaço a mais já deixa a conexão inválida

Depois de conectar, escolhi o modelo dentro do próprio OpenCode entre as opções gratuitas que apareceram, e pra ter certeza que estava valendo eu perguntei ao modelo qual modelo ele era, conferindo a resposta ali no terminal mesmo hehe

Pra habilitar o uso via API eu carreguei 5 dólares de créditos na plataforma (na real, acho que talvez desse pra colocar até menos)

E o que apareceu no painel de uso depois foi interessante: nenhum desconto pelos modelos gratuitos, e o único gasto registrado veio de um modelo pago que eu usei só pra checar se a API respondia

O teste real: uma calculadora de churrasco

Com o OpenCode no terminal eu pedi um projeto completo: uma calculadora de churrasco em React com Vite, com estrutura de pastas, arquivo de lógica de cálculo, tela de resultado, lista de compras, tema escuro e sem backend

Deu pra acompanhar a criação passo a passo na tela, e no fim o agente listou o que fez (regras de cálculo, componentes criados, tema visual) e explicou como rodar o projeto

Aí veio o tranco: quando pedi que o próprio agente executasse o projeto, bati no limite de requisições do modelo gratuito e a tarefa parou no meio

Esperei pra ver se liberava, não rolou, e troquei pra outro modelo gratuito dentro do próprio OpenCode

Daí seguiu adiante e a aplicação abriu com o cálculo funcionando 🙂

Olhando os registros de uso da plataforma, o motivo ficou claro: uma única solicitação minha virou MUITAS requisições, porque o agente segue conversando sozinho com o modelo até terminar a tarefa

É isso que estoura cota gratuita rápido, e é bom saber disso antes de se frustrar

Ah, e notei um modelo diferente do que eu tinha escolhido aparecendo no meio das chamadas

Se existe algum fallback configurado ali eu não sei dizer, fica o registro do que eu vi

A estratégia que funcionou pra mim foi essa: alternar entre modelos gratuitos dentro do OpenCode em vez de depender de um só

Resumo do estudo de caso: projeto completo gerado e rodando no fim, sim, mas com uma troca de modelo no meio do caminho pra conseguir chegar lá

Gratuito serve bem pra tarefa pequena, mas não dá pra construir a rotina de trabalho em cima dele, porque a cota estoura no meio do serviço

Conclusão: vale a pena começar pelo OpenCode?

Pra quem quer um agente rodando no terminal sem ficar amarrado a um provedor único, o OpenCode é uma porta de entrada barata de testar

O código é MIT, a instalação sai num comando, e o suporte a mais de 75 provedores (incluindo modelo local) te deixa trocar de motor sem trocar de ferramenta

Se a tua dúvida é entre ele e outro agente de linha de comando, dá pra comparar o OpenCode com o Codex com calma antes de decidir

O próximo passo concreto, se tu quer sentir a coisa funcionando hoje: instala, roda o /connect com um provedor e começa pelo agente Plan

Deixa o Build entrar só depois que o plano fizer sentido pra ti

É menos empolgante que soltar o agente correndo solto no repositório, mas é MUITO mais seguro pro teu código…

até o próximo post! =)