OpenCode + Ollama: um agente de código no seu terminal

#OpenCode com Ollama: quem faz o quê

OpenCode é um agente de código open source que é executado no terminal: ele lê seu projeto, modifica arquivos e executa comandos. Ele não fornece um modelo por si só. Ollama, por sua vez, baixa e executa modelos na sua máquina e expõe uma API local. Os dois se complementam: OpenCode envia suas requisições para Ollama, que responde com um modelo local. Portanto, a pergunta “OpenCode ou Ollama” não se aplica: usamos os dois.

O interesse pelo uso local não é ideológico. Um agente de código vê tudo: a estrutura de arquivos, os arquivos de configuração, a lógica de negócio. Com um modelo local, esse contexto permanece na máquina, sem cobrança por token nem dependência de rede. O preço a pagar é a capacidade: um modelo local com algumas dezenas de bilhões de parâmetros não se iguala aos maiores modelos hospedados, e as tarefas longas são executadas mais lentamente.

#Pré-requisitos: máquina, terminal e Ollama

Ollama em operação

Verifique se um modelo responde antes de configurar qualquer coisa: ollama list, depois ollama run com um modelo de código. Se funcionar, resta apenas a configuração do OpenCode.

Um terminal moderno

A documentação do OpenCode menciona WezTerm, Alacritty, Ghostty e Kitty. No Windows, ela recomenda usar WSL para obter melhor desempenho e compatibilidade completa.

Memória para contexto

Um agente lê arquivos e acumula o histórico. Ollama indica que o OpenCode exige um comprimento de contexto de pelo menos 64.000 tokens, o que aumenta a memória necessária além dos pesos do modelo.

Um repositório Git

Opcional, mas recomendado: um git diff ou um git restore anula corretamente uma sessão falha.

#Instalar OpenCode e conectá-lo ao Ollama

OpenCode instala-se por meio de um script ou dos gerenciadores de pacotes. A documentação lista o script oficial, npm, bun, pnpm, yarn, Homebrew, Arch, Chocolatey, Scoop, Mise e Docker. Para macOS e Linux com Homebrew, recomenda o tap oficial em vez da fórmula básica, que é atualizada com menos frequência.

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

npm install -g opencode-ai

brew install anomalyco/tap/opencode

choco install opencode
scoop install opencode

#Método rápido: ollama launch opencode

Ollama sabe iniciar o OpenCode com um modelo escolhido. O comando ollama launch opencode inicia o OpenCode com uma configuração passada por linha de comando, sem sobrescrever seu arquivo ~/.config/opencode/opencode.json; as configurações existentes do OpenCode continuam em vigor. Com a opção --config, Ollama configura o OpenCode sem abrir uma sessão interativa. Modelos definidos apenas no opencode.json não aparecem no seletor do comando ollama launch.

ollama launch opencode

#Método manual: declarar Ollama como fornecedor

Se você prefere manter o controle, adicione um provedor ao arquivo opencode.json, seja o global (~/.config/opencode/opencode.json), seja o da raiz do projeto. O endpoint do Ollama compatível com OpenAI é http://localhost:11434/v1. Cada chave em models deve reproduzir exatamente o nome do modelo como exibido por ollama list.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3-coder:30b": { "name": "Qwen3-Coder 30B" },
        "devstral-small-2:24b": { "name": "Devstral Small 2" }
      }
    }
  }
}

Reinicie o OpenCode: o seletor de modelos apresenta os modelos declarados na configuração do provedor Ollama.

#A armadilha número um: o comprimento do contexto

Muitos dos primeiros testes falham porque o contexto é muito curto: o agente perde o início da tarefa, repete leituras de arquivos ou produz modificações incoerentes. Ollama não define um contexto único: o documento indica 4k tokens abaixo de 24 GB de VRAM, 32k entre 24 e 48 GB e 256k a partir de 48 GB. Ele especifica que tarefas que exigem um grande contexto, como agentes e ferramentas de código, devem ser configuradas para pelo menos 64.000 tokens.

Para alterar o valor, existem duas opções. No aplicativo Ollama, um controle deslizante nas configurações define o contexto. Na linha de comando, a variável OLLAMA_CONTEXT_LENGTH se aplica ao iniciar o servidor. Um contexto maior consome mais memória: verifique com ollama ps se o modelo cabe inteiramente na GPU, pois um modelo que passa a usar também a CPU fica muito lento.

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

#Qual modelo local para um agente de código

Um agente deve chamar ferramentas de forma confiável: ler, escrever, executar. Escolha um modelo que exiba a capacidade tools na biblioteca Ollama. Aqui estão candidatos cujas tags e tamanhos foram registrados em ollama.com.

Esses tamanhos são os dos arquivos; acrescente o cache de contexto, que cresce com os 64.000 tokens solicitados. O modelo de 15 GB (Devstral Small 2) é o mais acessível em uma máquina de 24 GB; o de 19 GB (Qwen3-Coder 30B) exige mais margem. Em uma máquina mais modesta, um modelo menor executa tarefas simples e específicas, mas perde desempenho mais rapidamente em uma refatoração que afeta vários arquivos.

#Um workflow real: adicionar uma rota e seu teste

Caso prático: adicionar uma rota GET /health a uma pequena API Express e cobri-la com um teste. A documentação do OpenCode recomenda começar com /init, que analisa o projeto e cria um arquivo AGENTS.md na raiz, a ser commitado no git para ajudar o agente a entender a estrutura.

1. 01
   Abrir o projeto

   Acesse a raiz do repositório, execute opencode e, na primeira vez, execute /init em seguida. Verifique na parte inferior se o modelo selecionado é realmente um modelo Ollama.
2. 02
   Mudar para o modo Plan

   A tecla Tab alterna entre os modos Plan e Build. O modo Plan desativa as alterações: o agente sugere apenas como procederia. Peça a ele um plano antes de qualquer mudança.
3. 03
   Descrever a tarefa

   Dê o contexto como se estivesse falando com um desenvolvedor iniciante: «Adicione uma rota GET /health em src/server.js que retorne status ok, depois um teste em test/health.test.js.» O caractere @ permite buscar um arquivo no projeto.
4. 04
   Mudar para o modo Build

   Quando o plano atender às suas necessidades, pressione Tab novamente e peça que as alterações sejam aplicadas.
5. 05
   Executar e iterar

   O agente pode executar npm test, ler a saída e corrigir o problema. Esse ciclo de executar, observar e corrigir é o núcleo da abordagem agêntica.
6. 06
   Verificar e commitar

   Revise o git diff antes de fazer o commit. Se a sessão saiu do rumo, git restore restaura os arquivos ao estado anterior.

Com um modelo local, cada etapa é mais lenta do que com um modelo hospedado, e uma instrução ambígua às vezes exige reformulação. O ganho é o controle: o código e o contexto permanecem na sua máquina, e você escolhe o modelo, sua quantização e o tamanho do contexto de acordo com seu hardware.

#Permissões: o que o agente pode fazer sem pedir sua autorização

Uma ideia comum é que o agente não modifica nada sem seu consentimento. Esse não é o comportamento padrão. A documentação do OpenCode indica que, sem configuração, a maioria das permissões tem o valor allow, ou seja, as ações correspondentes são executadas sem pedir autorização; apenas algumas, como external_directory e doom_loop, têm o valor ask. A leitura de arquivos .env é bloqueada por padrão, exceto a de .env.example.

Para um agente que controla um modelo local menos confiável, é prudente adotar uma configuração mais rigorosa. O arquivo opencode.json aceita uma seção permission em que cada ação recebe o valor allow, ask ou deny, inclusive com uma regra global * definida como ask.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": { "*": "ask" }
}

#OpenCode, Cline ou Aider: qual escolher?

Os três usam a API do Ollama; experimentar os dois mais próximos dos seus hábitos leva uma hora e vale mais do que um comparativo. Para autocompletar diretamente na linha de código em vez de usar um agente, veja o Tabby.

#Solução de problemas

O modelo não aparece

O nome no opencode.json não corresponde ao nome listado por ollama list. Copie o nome exato, incluindo a tag. Com ollama launch, um modelo definido apenas no opencode.json não aparece no seu seletor.

O agente esquece o que acabou de ler

O contexto é muito curto: passe para 64.000 tokens (OLLAMA_CONTEXT_LENGTH) e verifique com ollama ps.

Conexão recusada

O servidor Ollama não está rodando ou não está ouvindo na porta padrão 11434. Teste o comando ollama list, depois a URL de baseURL.

Chamadas de ferramentas que falham

O modelo não lida bem com ferramentas. Escolha um modelo marcado com tools na biblioteca Ollama.

Respostas muito lentas

O modelo e seu contexto ultrapassam a VRAM e parte do processamento é feito no processador. Reduza o contexto, o tamanho do modelo ou a quantização.

#Para se aprofundar

• Cline + Ollama no VS Code
• Aider + Ollama no terminal
• Tabby: autocompletação local de código
• Escolher sua quantização
• Compreender a janela de contexto
• Instalar Ollama em 5 minutos

• Fonte: Ollama, integração OpenCode
• Fonte: Ollama, comprimento de contexto
• Fonte: documentação OpenCode
• Fonte: permissões OpenCode