Como usar OpenCode com Ollama para rodar um modelo local no seu agente de código?

Fala aí, beleza? Dá pra tirar o agente de código da API paga e colocar ele pra rodar em cima de um modelo que vive na sua máquina, sem nenhuma linha de código saindo dali

O OpenCode é um agente de código open source feito pro terminal, mantido no repo sst/opencode

Ele é provider agnostic: roda com Claude, OpenAI, Google ou modelo local, do mesmo jeito

Isso acontece porque ele usa o AI SDK junto com o Models.dev pra suportar mais de 75 provedores de LLM, e os mais populares já vêm pré-carregados por padrão

Além da nuvem, a documentação cobre três rotas locais: Ollama, LM Studio e llama.cpp (o utilitário llama-server)

Aqui a gente vai na do Ollama

O post entrega duas coisas: as duas formas de ligar OpenCode e Ollama (a rápida e a manual) e o checklist do que conferir ANTES, que é onde a maioria trava 🙂

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 checar antes de rodar um modelo local no OpenCode

Instalar é a parte fácil

O que decide se a experiência vai ser boa ou frustrante é o que vem antes, então bora pela lista honesta:

• Versão do Ollama: pra usar o comando ollama launch a orientação oficial é baixar o Ollama v0.15 ou superior
• Modelo baixado: modelos entram com ollama pull seguido do nome do modelo
• Janela de contexto: esse é o ponto crítico, o OpenCode exige janela de 64k ou mais, e por padrão o Ollama usa 4096 tokens
• RAM: a memória exigida pelo Ollama escala com OLLAMA_NUM_PARALLEL multiplicado por OLLAMA_CONTEXT_LENGTH, ou seja, subir contexto cobra o preço na conta de memória
• VRAM: ao carregar o modelo, o Ollama compara a VRAM necessária com a disponível, se couber inteiro em uma GPU ele carrega nela (melhor desempenho), se não couber ele espalha o modelo entre as GPUs disponíveis

Quantização: a saída quando a memória aperta

Se o modelo não cabe, a saída clássica é usar uma versão quantizada

A ideia é simples: menos bits por peso, menos memória, um pouco menos de precisão

Tem ainda o Flash Attention, que reduz significativamente o uso de memória conforme o contexto cresce, e o Ollama aplica ele automaticamente quando o backend e os dispositivos suportam

Se tu ainda não tem o Ollama rodando na máquina, vale passar antes por um guia de modelo local com Ollama pra deixar a base de pé

E fecho o checklist com o aviso que a própria documentação do OpenCode dá: poucos modelos são bons ao mesmo tempo em gerar código E em fazer tool calling

Ou seja, um modelo que escreve código lindo pode simplesmente não conseguir chamar as ferramentas do agente

Tome cuidado com isso na hora de escolher!

Rota rápida: usar OpenCode com Ollama pelo comando ollama launch

Essa é a rota de quem quer ver funcionando hoje, sem editar arquivo nenhum

O Ollama tem o comando ollama launch, que configura e roda ferramentas de código como Claude Code, OpenCode e Codex com modelos locais ou da nuvem, sem variáveis de ambiente nem arquivos de config

1. Atualize o Ollama pra v0.15 ou superior

O comando só existe a partir dessa versão

O erro comum deste passo: tentar o ollama launch numa instalação antiga e achar que o comando não existe no seu sistema operacional

2. Baixe o modelo que tu quer usar

ollama pull <modelo>

O erro comum deste passo: escolher qualquer modelo bonito de benchmark e esquecer do tool calling, que é o que o agente usa pra ler e escrever arquivo

3. Suba o OpenCode já apontado pro Ollama

ollama launch opencode

O comando inicia o OpenCode com uma config inline do modelo Ollama selecionado

E aqui vai o detalhe que tranquiliza quem já usa a ferramenta todo dia: ele NÃO sobrescreve o ~/.config/opencode/opencode.json

Suas configurações existentes continuam valendo, beleza?

Rota manual: configurar o Ollama como provider no opencode.json

A rota rápida é ótima pra validar

Mas se tu quer o modelo local fixo, sempre disponível na lista, o caminho é declarar o provider no opencode.json

"E como o OpenCode fala com o Ollama?" Pelo adaptador OpenAI-compatible, apontando pra baseURL local

É o mesmo princípio de qualquer cliente que fala o dialeto da API da OpenAI: muda o endereço, o resto da conversa continua igual

4. Declare o provider no opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "nome-do-modelo:tag": {}
      }
    }
  }
}

O baseURL é o endpoint OpenAI-compatible do Ollama: http://localhost:11434/v1

5. Confira a chave dentro de models

Essa é a pegadinha da rota manual

A chave JSON dentro de models precisa bater EXATAMENTE com o nome do modelo no Ollama, incluindo os dois pontos

O erro comum deste passo: trocar os dois pontos por hífen na chave, o que gera erro de modelo não encontrado

Copiar e colar o nome direto do Ollama resolve

6. Lembre que provider não é tudo

Os provedores mais populares já vêm pré-carregados por padrão, então nem sempre tu precisa declarar algo na mão

E credenciais de provedor no OpenCode entram pelo comando /connect, ficando salvas em ~/.local/share/opencode/auth.json

Deu erro? Os problemas mais comuns do OpenCode com modelo local

Sintoma: as chamadas de ferramenta não funcionam

O modelo responde, conversa, mas não lê nem escreve arquivo

Causa provável: contexto curto demais pro agente operar

Solução: aumentar o num_ctx, respeitando a janela de 64k ou mais que o OpenCode exige

Sintoma: o contexto está abaixo do exigido

O OpenCode pede janela de 64k ou mais

Causa provável: o Ollama vem com 4096 tokens por padrão, então o valor de fábrica não atende

Solução: subir o context length pelo slider de context length nas configurações do app Ollama, ou definir isso na hora de servir o Ollama

Sintoma: modelo não encontrado

A config está lá, o modelo está baixado, e mesmo assim ele some

Causa provável: divergência entre a chave declarada em models e o nome real do modelo no Ollama

Solução: deixar a chave idêntica ao nome do Ollama, com os dois pontos no lugar

Como prevenir tudo isso? Conferir o nome do modelo e o contexto ANTES de abrir o OpenCode

E dimensionar memória pela conta que já vimos: OLLAMA_NUM_PARALLEL x OLLAMA_CONTEXT_LENGTH

Contexto grande é ótimo pro agente e caro pra sua RAM, os dois são verdade ao mesmo tempo

Quando vale rodar local e quando é melhor continuar na nuvem

Rodar local não é melhor por definição, é melhor pra certos cenários

Vale local quando o código é sensível

A página oficial do OpenCode afirma que ele não armazena código nem dados de contexto do usuário, justamente pra poder operar em ambientes sensíveis à privacidade

Com modelo local, tu fecha o ciclo: nada sai da máquina

Vale local quando o uso é contínuo

Agente de código roda o dia inteiro, e uso contínuo é exatamente onde a conta de API começa a doer

É o mesmo raciocínio de quando a gente olha o custo real de rodar IA por API: o preço por chamada parece pequeno até virar rotina

A nuvem ainda ganha quando a máquina não ajuda

Se não tem VRAM suficiente, ou se o modelo que cabe na sua máquina é fraco em tool calling, insistir no local é trocar economia por frustração

E tem a saída do meio: o Ollama também oferece serviço de nuvem com modelos hospedados, com contexto completo e limites generosos mesmo no nível gratuito, pensado justamente pra quem tem dificuldade de rodar localmente

Como o OpenCode é provider agnostic, a troca entre esses cenários é de configuração, não de ferramenta

Tu não abandona o agente, só muda quem está do outro lado 😀

Conclusão

A ponte entre OpenCode e Ollama é curta: ou ollama launch opencode, ou um bloco de provider no opencode.json apontando pro endpoint local

O que decide o resultado não é o passo de instalação, é contexto e escolha de modelo

Sugestão de caminho: começa pela rota ollama launch opencode só pra validar se o modelo se comporta, sobe o contexto pra 64k ou mais e só então migra pro provider fixo no opencode.json

E se tu quiser comparar especificações e recursos antes de escolher o modelo, o Models.dev é um banco de dados open source de modelos de IA e é justamente a base do catálogo de provedores do OpenCode

Massa demais ter esse nível de escolha em ferramenta open source, né?

até o próximo post!