Como usar a API do OpenCode nas suas integrações?

Fala aí, beleza? O OpenCode no terminal é massa, mas em algum momento tu quer que ELE trabalhe sem você ficar olhando a tela

E é aí que a coisa fica interessante: existe um servidor HTTP headless que roda sem TUI nenhuma, publica a própria spec OpenAPI e ainda tem SDK oficial em JavaScript/TypeScript e em Go

Ou seja, dá pra plugar o agente dentro do teu fluxo, do teu script, do teu backend

Neste post eu te mostro o caminho até a primeira chamada, o que a API realmente expõe, e onde tem pedra no meio do caminho 🙂

O que você precisa antes de fazer a primeira chamada

A lista é curta, e boa parte disso tu provavelmente já tem

• OpenCode instalado e funcionando na máquina, com provedor e modelo já configurados (se ele não responde na TUI, também não vai responder via API)
• Acesso ao terminal onde o servidor vai ficar de pé
• Um ambiente de cliente, que pode ser Node pro SDK JavaScript/TypeScript, ou Go 1.22+ pro SDK Go

Agora a parte que confunde muita gente: o SDK é opcional, o servidor no ar não é

A API é HTTP. Tu pode falar com ela de qualquer linguagem, com curl mesmo, sem instalar SDK nenhum

O SDK entra quando você quer um cliente type-safe, com as definições TypeScript geradas a partir da spec OpenAPI do servidor. É conveniência, não requisito

Se você conhece qualquer serviço REST documentado com OpenAPI, é exatamente essa sensação: sobe o serviço, lê a spec, chama

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

Como usar a API do OpenCode passo a passo

Bora ver na prática? Cada passo aqui vem com o erro comum que trava a galera

1. Suba o servidor headless com opencode serve

Esse é o comando que roda um servidor HTTP sem TUI e expõe o endpoint OpenAPI que um cliente opencode consegue consumir

opencode serve

Ele aceita duas flags que você vai usar bastante: --port (porta a escutar) e --hostname (host a escutar)

opencode serve --port 4096 --hostname 127.0.0.1

O erro comum deste passo: deixar a porta implícita e depois ficar caçando onde o servidor subiu. Fixe a porta com --port desde o começo e você sabe exatamente pra onde apontar o cliente

2. Abra /doc e leia a spec OpenAPI

O próprio servidor publica uma spec OpenAPI 3.1 no endpoint /doc, por exemplo em http://localhost:4096/doc

Ela é navegável e serve pra duas coisas: inspecionar os tipos de request e response, e gerar clientes

curl http://localhost:4096/doc

Esse é o teu mapa. Em vez de adivinhar caminho de endpoint por tutorial de terceiro, você lê a referência viva que o SEU servidor está publicando, na versão que você está rodando

O erro comum deste passo: pular ele. Aí a pessoa copia um caminho de endpoint de algum lugar aleatório da internet, toma 404 e acha que a API está quebrada

3. Faça a primeira chamada apontando o cliente pro servidor

Com o servidor de pé, o cliente é só um HTTP client apontando pra base URL local

A documentação do SDK usa http://localhost:4096 como baseUrl no exemplo, então é um valor confortável pra padronizar com o --port 4096 do passo 1

Comece por algo de leitura, só pra confirmar que a conexão responde antes de mandar o agente mexer em arquivo

O erro comum deste passo: assumir que o servidor está acessível de outra máquina. Não está. Por padrão ele faz bind em 127.0.0.1, ou seja, somente localhost

4. Use o SDK JavaScript/TypeScript, se quiser cliente type-safe

Instalação:

npm install @opencode-ai/sdk

Aqui existem dois caminhos, e vale entender a diferença antes de escolher

O primeiro conecta a um servidor que JÁ está rodando:

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096"
})

O segundo sobe servidor e cliente juntos, aceitando opções como hostname, port e modelo:

import { createOpencode } from "@opencode-ai/sdk"

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096
})

Regrinha prática: se o servidor é um processo separado que já vive na máquina (systemd, container, aba do terminal), use createOpencodeClient. Se o teu script é dono do ciclo de vida inteiro, createOpencode te poupa a dança de subir e derrubar na mão

Tem também SDK Go oficial pra API REST, no repositório github.com/anomalyco/opencode-sdk-go (historicamente importado como github.com/sst/opencode-sdk-go). Ele pede Go 1.22+, foi gerado com Stainless e o cliente sai de um opencode.NewClient()

5. Consuma o stream de eventos em /event

Esse é o endpoint que muda o jogo pra automação de verdade

O /event entrega um stream SSE (Server-Sent Events) com os eventos do servidor, e dá pra consumir com EventSource

const events = new EventSource("http://localhost:4096/event")

events.onmessage = (e) => {
  console.log(e.data)
}

A sacada: em vez de ficar batendo em loop perguntando "já terminou? já terminou?", tu escuta e REAGE

O erro comum deste passo: tratar SSE como uma requisição normal que termina. Ela não termina, é um stream aberto, e o teu código precisa lidar com reconexão

6. Proteja o servidor ANTES de expor pra fora

Esse passo não é opcional, tome cuidado!

O servidor pode ser protegido com HTTP basic auth por variável de ambiente: defina OPENCODE_SERVER_PASSWORD e ele passa a exigir autenticação. O usuário padrão é opencode, e dá pra trocar com OPENCODE_SERVER_USERNAME

export OPENCODE_SERVER_PASSWORD="uma-senha-de-verdade"
export OPENCODE_SERVER_USERNAME="meu-usuario"

opencode serve --hostname 0.0.0.0 --port 4096

A própria documentação é explícita nisso: ao usar --hostname 0.0.0.0, defina OPENCODE_SERVER_PASSWORD pra proteger o servidor

E faz todo sentido, né? Você está expondo na rede um processo que lê e escreve arquivos do teu projeto e executa trabalho de agente

O erro comum deste passo: trocar o hostname pra 0.0.0.0 "só pra testar rapidinho da outra máquina" e deixar assim. Pensar em guardrails de IA nas suas automações vale pro n8n e vale aqui do mesmo jeito: limite primeiro, expõe depois

O que dá para automatizar com a API do OpenCode

A melhor forma de saber o que a API entrega é olhar como os clientes oficiais organizam ela

O cliente Go separa a API em serviços, e essa lista é praticamente um inventário dos recursos que o servidor expõe:

• Event
• Path
• App
• Agent
• Find
• File
• Config
• Command
• Project
• Session
• Tui

Só de ler os nomes já dá pra imaginar bastante coisa: sessão, arquivo, busca, comando, projeto, agente

O formato exato de cada request e response está na spec publicada em /doc, na versão que tu está rodando

Agora, o que dá pra montar com isso:

• Reagir a eventos em tempo real com o stream do /event, disparando teu próprio fluxo quando algo acontece do lado do agente
• Dirigir a interface de terminal pelo servidor com o endpoint /tui, que permite por exemplo pré-preencher ou executar um prompt. E se liga nisso: é exatamente o mecanismo usado pelos plugins de IDE do OpenCode. Ou seja, o caminho já é usado em produção pelo próprio projeto
• Gerar um cliente type-safe direto da spec OpenAPI, em vez de escrever wrapper na mão e ficar sincronizando tipo toda vez que a API muda

Quem já monta fluxo em ferramenta visual pega a ideia rápido: é o mesmo raciocínio de expandir integrações com nodes do n8n, só que aqui o bloco novo é um agente de código com acesso ao teu repositório

E se eu só quero rodar um prompt em um script?

Aí talvez você nem precise de API, hehe

A CLI do OpenCode também tem modo não interativo, passando um prompt direto, sem abrir a TUI. É pensado justamente pra scripting e automação

Regrinha honesta pra escolher:

Montar servidor HTTP pra fazer o que uma linha de CLI resolve é overengineering, e você vai se arrepender na hora de dar manutenção

OpenCode 2.0 em beta: o que isso significa para quem integra

Antes de você fincar bandeira nessa integração, um contexto importante

O projeto é mantido pela Anomaly, o time que antes assinava como SST. O repositório oficial é o anomalyco/opencode, escrito em TypeScript e sob licença MIT (o antigo sst/opencode redireciona pra lá)

E não é projetinho: são 193 mil stars, 24,6 mil forks e 944 contribuidores

Agora o aviso que interessa pra quem integra: o OpenCode 2.0 está em beta

O beta saiu no início de julho de 2026, instala com npm install -g @opencode-ai/cli@next e roda como opencode2, lado a lado com o binário opencode da v1. Ele NÃO substitui a versão 1, os dois convivem

A documentação é bem direta sobre o risco: dados podem ser apagados, coisas podem quebrar, e as APIs de servidor, de configuração e de plugins ainda podem mudar

Plugins da v1 não funcionam na v2 durante o beta

A boa notícia: arquivos de config de servidor, definições de agentes, comandos, skills e o resto do que mora em .opencode/ continuam funcionando sem mudanças na v2

Tradução prática pra tua integração: se ela é crítica, construa em cima da v1 por enquanto, e trate a v2 como campo de experimentação. Contrato de API que pode mudar no meio do beta é péssima base pra automação que você depende…

Custo e limite de uso na prática

Aqui eu preciso separar duas coisas que costumam se misturar na cabeça de quem começa

A API do OpenCode é local, sobe na tua máquina e não te cobra nada por isso. Mas o agente atrás dela consome MODELO, e modelo tem custo e tem limite

No vídeo eu mostro esse lado na prática, conectando um provedor externo de modelos por chave de API dentro do OpenCode

Pra liberar o uso via API, tive que carregar crédito na conta da plataforma mesmo pretendendo usar modelos gratuitos. Coloquei 5 dólares e, olhando depois, acho que talvez desse pra colocar menos

O detalhe interessante veio no painel de uso: o gasto registrado foi só do modelo PAGO que usei pra checar se a API respondia mesmo. Os modelos gratuitos não descontaram nada

Aí veio a pedra. Quando pedi pro agente executar o projeto pra testar, bati no rate limit do modelo gratuito

E se liga num ponto que muita gente esquece na hora de automatizar: a conta de consumo não é só o teu prompt. As idas e voltas entre o agente e o modelo também consomem, e um agente trabalhando sozinho conversa MUITO

Esperei pra ver quanto tempo o bloqueio duraria, fiquei um tempo tentando e não consegui retomar naquele modelo. O tempo de liberação não é informado em lugar nenhum

O que resolveu foi rotacionar: troquei pra outro modelo gratuito da lista e segui o trabalho

Pra quem vai automatizar, ficam dois aprendizados que valem ouro:

• Orçamento: teste com crédito baixo primeiro, porque o painel de uso vai te contar a verdade rapidinho
• Tolerância a falha: a tua integração PRECISA lidar com rate limit sem morrer. Retry com espera, fallback pra outro modelo, log do que falhou. Automação que assume que o modelo sempre responde é automação que quebra no primeiro dia útil

É nesse vídeo que o crédito, o modelo pago e o rate limit aparecem acontecendo na tela, do jeito que foi 🙂

Conclusão

O caminho mínimo pra sair do uso interativo é bem mais curto do que parece

Sobe o servidor headless com opencode serve, lê a spec OpenAPI em /doc, faz a primeira chamada apontando pro localhost, e SÓ DEPOIS pensa em expor, já com OPENCODE_SERVER_PASSWORD no lugar

O resto é escolha de ferramenta: SDK JavaScript/TypeScript, SDK Go, ou HTTP puro se você prefere ficar leve

Teu próximo passo concreto: sobe o servidor agora, abre o /doc dele e gera o cliente a partir da spec

E começa por um endpoint de LEITURA antes de automatizar qualquer escrita. Deixar um agente mexer em arquivo por integração que você ainda não entendeu direito é o tipo de coisa que a gente só faz uma vez na vida, haha

Depois que a leitura estiver redonda, aí sim você solta a escrita

até o próximo post!