Como instalar o OpenCode e rodar seu primeiro projeto no terminal

Fala aí, beleza? O OpenCode é um agente de codificação open source que roda direto no terminal, e o repositório já estava em cerca de 191,9 mil estrelas no GitHub no começo de agosto de 2026

Estrela não escreve código, eu sei, mas dá bem o tamanho da onda 😀

A ideia aqui é te levar do zero até a primeira tarefa rodando dentro da pasta do seu projeto: instalar, conectar um provedor de modelo, criar o arquivo de regras e soltar o agente numa tarefa de verdade

E tem um detalhe que muda tudo: o OpenCode não te amarra numa empresa de modelo só, o catálogo dele vem do Models.dev, com mais de 75 provedores de LLM, incluindo modelos locais

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

O que você precisa antes de instalar o OpenCode

Checklist honesto, sem PC da Nasa na lista:

• Um terminal: no macOS e no Linux, o que você já usa. No Windows, a documentação recomenda o WSL, ou seja, instalar o WSL, abrir a distro Linux e rodar os comandos ali dentro (tem também a opção de baixar o binário na página de Releases)
• Um gerenciador de pacote Node, caso você escolha o caminho do npm, Bun, pnpm ou Yarn
• A pasta de um projeto pra abrir
• Acesso a um provedor de modelo, que é o que faz o agente pensar

Sobre o projeto: não precisa ser um monorepo monstro pra testar, viu? Serve qualquer coisa que já esteja na sua máquina, até aquele primeiro projeto em React que ficou parado na pasta de estudos

E o provedor de modelo, qual escolher?

Como o catálogo vem do Models.dev, você pluga o que quiser: provedor grande, provedor pequeno, modelo local rodando na sua máquina

Existe também o OpenCode Zen, que é o serviço de modelos curado pelo próprio time do OpenCode

Agora a parte que ninguém gosta de ler mas é a que dói no bolso: o Zen é pay as you go, com preço por 1 milhão de tokens e cobrança por requisição, e os créditos ficam na sua conta

Ou seja, não é assinatura fixa, é consumo

Passo a passo: instalar o OpenCode e rodar o primeiro projeto

Bora ver na prática?

1. Instale pelo script oficial, que é o caminho mais simples:

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

2. Ou use o gerenciador de pacote que você já tem na máquina. O pacote publicado no npm se chama opencode-ai:

npm install -g opencode-ai
bun install -g opencode-ai
pnpm install -g opencode-ai
yarn global add opencode-ai

No macOS e no Linux dá pra ir de Homebrew, e no Arch tem pacote próprio:

brew install anomalyco/tap/opencode
paru -S opencode-bin

O erro comum deste passo: rodar brew install opencode no automático. O caminho indicado pelo projeto é o do tap dele, anomalyco/tap/opencode, que é o comando do bloco acima

Resumão dos caminhos:

3. Conecte o provedor de modelo. Rode opencode e, dentro da TUI, use o /connect pra escolher o provedor e colar a API key

Fora da interface interativa, existe o comando de CLI pra gerenciar credencial:

opencode auth login

Que arquivo guarda isso? As credenciais dos provedores ficam gravadas em ~/.local/share/opencode/auth.json, no seu próprio computador

4. Se a escolha for o OpenCode Zen, o caminho é /connect > OpenCode Zen > entrar em opencode.ai/auth, adicionar os dados de cobrança e copiar a API key

Tome cuidado com um detalhe aqui: o Zen tem recarga automática, e saldo abaixo de US$ 5 dispara uma recarga de US$ 20 (dá pra mudar o valor ou desativar a recarga)

E a taxa de cartão é repassada pelo valor de custo: 4,4% + US$ 0,30 por transação

Sabendo disso antes, você configura do seu jeito no primeiro dia em vez de descobrir no extrato

5. Abra o projeto. Navegue até o diretório e execute:

cd meu-projeto
opencode

6. Rode o /init. Esse comando varre os arquivos importantes do repo, pode te fazer perguntas pontuais e cria ou atualiza o AGENTS.md do projeto

7. Dê a primeira tarefa e revise. Pede algo pequeno e verificável, tipo ajustar uma função ou escrever um teste, e lê o que ele propõe antes de aceitar

Se você já criou um app com o Antigravity, a lógica é a mesma: o agente lê o contexto, propõe, e quem dá o veredito é você

AGENTS.md: como deixar o agente com as regras do seu projeto

O AGENTS.md fica na raiz do projeto e vale pro diretório e pros subdiretórios

As instruções dele entram no contexto do modelo, então é ali que moram as combinações do tipo "neste repo o padrão é esse", "não mexe nessa pasta", "o comando de teste é esse"

A recomendação da documentação é commitar o arquivo no Git

Faz sentido: o time todo herda as mesmas regras em vez de cada um configurar o agente do seu jeito na própria máquina

O erro comum aqui é ter medo de rodar o /init num repositório que já está configurado, achando que vai varrer tudo

Não vai: se o arquivo já existir, o comando melhora ele no lugar em vez de substituir

Além da TUI: onde mais o OpenCode roda

Depois que o básico funciona, o OpenCode não fica preso na interface do terminal

Tem o opencode run, que executa fora da interface interativa (útil quando você quer chamar o agente de dentro de um script)

E tem também o app de desktop e a extensão de IDE, pra quem não quer viver no terminal

Agora o ponto que eu acho mais importante nessa história toda: a mesma configuração de permissões se aplica à TUI, ao opencode run, ao app de desktop e à GitHub Action

Ou seja, você define os guardrails (limites) uma vez e eles valem em todo lugar, não é cada interface com uma regra diferente

Versão 1 ou OpenCode 2? O que instalar hoje

Se você chegou agora, instala a versão 1 e segue a vida

A versão estável mais recente publicada no repositório é a v1.18.11, de 1 de agosto de 2026

O OpenCode 2 existe, sim, mas está em beta, e a própria documentação avisa que dados podem ser apagados e APIs podem mudar

Ele instala e roda como opencode2, convivendo com o opencode 1 na mesma máquina, e no beta não tem script curl, Homebrew nem Arch, só gerenciadores de pacote Node

Contexto pra você não se perder procurando o projeto: o repositório oficial fica em github.com/anomalyco/opencode (antes ficava em sst/opencode), e quem mantém é a Anomaly, o mesmo time por trás do SST

Se você tinha o link antigo salvo, é isso, mudou de casa

Conclusão

O caminho todo foi esse: instalar (script, Node, Homebrew, Arch ou WSL), conectar o provedor pelo /connect, rodar o /init pra nascer o AGENTS.md e soltar a primeira tarefa dentro da pasta do projeto

Os próximos passos que eu deixaria na lista:

• versionar o AGENTS.md no Git, pra regra do projeto virar coisa do time e não configuração pessoal
• testar um segundo provedor pelo /connect, já que o catálogo do Models.dev não te prende a uma empresa só
• acompanhar as releases do repositório antes de encostar no beta da v2

Dá pra montar isso tudo hoje, sem caçar documentação em dez abas

Até o próximo post! =)