Agente de código com LLM local: Ollama e LM Studio

Um agente de código com LLM local é uma CLI de código, como opencode, Aider, Goose, Qwen Code, Crush ou Codex, apontada para um modelo rodando na sua própria máquina pelo Ollama ou LM Studio em vez de uma API hospedada. Você sobe um servidor local (o Ollama escuta em http://localhost:11434, o LM Studio em http://127.0.0.1:1234), escolhe um modelo que suporte tool calling, aumenta bem o tamanho do contexto acima do padrão e diz à CLI para usar esse endpoint. Funciona, mantém seu código na sua máquina e não custa nada por token. Também é mais lento e menos capaz que os melhores modelos hospedados, então a maioria das pessoas acaba com uma configuração híbrida.

O que “local” significa aqui de verdade

Um agente de código tem duas partes: a CLI que lê arquivos, roda comandos e edita código, e o modelo que decide o que fazer em seguida. Ir para o local substitui só a segunda parte. A CLI continua rodando o mesmo loop; ela só envia as requisições para um servidor em localhost em vez da API de um provedor.

Os dois servidores locais mais comuns falam uma API compatível com OpenAI:

A documentação do Ollama observa que clientes OpenAI exigem um valor de chave de API, mas o Ollama o ignora, então qualquer placeholder serve para um servidor local.

A configuração que todo mundo esquece: tamanho do contexto

Antes de escolher uma CLI, resolva isto. Agentes enviam muito contexto: um system prompt, definições de ferramentas, conteúdo de arquivos e saída de comandos. Um servidor local com uma janela pequena corta a maior parte disso sem avisar.

A janela de contexto padrão do Ollama depende da sua VRAM: 4k tokens abaixo de 24 GiB, 32k entre 24 e 48 GiB e 256k a partir de 48 GiB. A documentação do Aider acrescenta que o Ollama descarta sem avisar o contexto que passa da janela. A documentação do Goose chama o padrão de 4096 tokens de baixo demais, e o próprio guia do Ollama para o Codex pede pelo menos 64k.

Aumente ao iniciar o servidor e depois confira:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve
ollama ps   # CONTEXT column shows the allocated length

O app do Ollama tem um controle deslizante de tamanho de contexto nas configurações que faz o mesmo. Se o ollama ps mostrar o modelo parcialmente na CPU na coluna PROCESSOR, o contexto ou o modelo é grande demais para a sua GPU e tudo vai ficar lento.

Quais CLIs suportam modelos locais

Aqui está o que a própria documentação de cada ferramenta confirma. Listamos só configurações que conseguimos verificar.

Codex

O Codex tem o caminho mais curto. A documentação diz que ele pode rodar com um provedor local de modelos abertos (“OSS”), como Ollama ou LM Studio quando você passa --oss:

codex --oss                     # default local model
codex --oss -m gpt-oss:120b     # a specific model

Defina o provedor padrão em ~/.codex/config.toml com oss_provider = "ollama" (ou "lmstudio"). O Ollama também oferece ollama launch codex, que monta um perfil para você. Dentro do Codex, /model alterna entre os modelos instalados que suportam ferramentas.

opencode

O opencode aceita qualquer servidor compatível com OpenAI como provedor personalizado 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": { "qwen3": { "name": "Qwen3 (local)" } }
    }
  }
}

Para o LM Studio, use http://127.0.0.1:1234/v1 como URL base e o identificador de modelo mostrado no LM Studio. A documentação do opencode traz uma dica útil: se as tool calls não funcionarem, aumente o num_ctx no Ollama, começando por volta de 16k a 32k.

Aider

O Aider conversa direto com o Ollama. A documentação recomenda o prefixo ollama_chat/:

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/<model>

Para o LM Studio ou qualquer outro servidor compatível com OpenAI, defina OPENAI_API_BASE e OPENAI_API_KEY e use aider --model openai/<model-name>. Um tamanho de contexto fixo vai no .aider.model.settings.yml como num_ctx dentro de extra_params.

Goose

O Goose lista Ollama e LM Studio como provedores. Rode goose configure, escolha Ollama e digite o nome de um modelo. Ele usa localhost:11434, a não ser que OLLAMA_HOST diga outra coisa; o LM Studio usa localhost:1234 por padrão, sem chave de API. A documentação do Goose é direta sobre a principal limitação: ele usa tool calling o tempo todo, então um modelo sem esse recurso só consegue conversar.

Qwen Code

O Qwen Code suporta qualquer endpoint compatível com OpenAI, e o README cita modelos locais via Ollama ou vLLM. Aponte as variáveis padrão para o seu servidor:

export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_API_KEY=ollama   # any placeholder for a local server
export OPENAI_MODEL=<model>
qwen

O mesmo pode ficar em ~/.qwen/settings.json dentro de modelProviders, ou você pode configurar de forma interativa com /auth.

Crush

O Crush suporta ollama e lmstudio como tipos de provedor. O README mostra o Ollama adicionado com a URL base http://localhost:11434/v1. Escolha o modelo dentro do Crush com Ctrl+L.

Quando o agente local se comporta mal

A maioria dos problemas com um agente de código local se resume a poucas causas. Confira nesta ordem:

• Ele esquece arquivos ou instruções no meio da tarefa. O contexto é pequeno demais e o servidor está cortando. Aumente OLLAMA_CONTEXT_LENGTH (ou num_ctx) e confirme com ollama ps.
• As tool calls falham ou voltam como texto puro. O modelo talvez não suporte tool calling, ou o contexto é curto demais para as definições de ferramentas. Tente um modelo com suporte a ferramentas e uma janela maior; a documentação do opencode sugere começar por volta de 16k a 32k.
• A CLI diz que o modelo não existe. O nome na CLI precisa bater exatamente com o identificador do servidor: a tag do ollama list ou o identificador no painel de servidor do LM Studio.
• Conexão recusada. O servidor não está rodando, ou a CLI espera outro endereço. O Ollama é 11434, o LM Studio é 1234, e algumas CLIs querem o sufixo /v1, enquanto o OLLAMA_API_BASE do Aider não.
• Tudo está muito lento. O modelo ou o contexto não cabe na GPU. O ollama ps mostra a parcela na CPU; escolha um modelo menor ou um contexto mais curto.

A realidade do hardware

É aqui que as expectativas costumam quebrar. Um agente de código local é um trabalho mais pesado que um chat local:

• O modelo precisa caber na memória. VRAM da GPU em um PC, memória unificada no Apple Silicon. Quando não cabe, camadas vão para a CPU e a geração fica bem mais lenta.
• Contexto também custa memória. Uma janela de 64k em cima dos pesos do modelo precisa de muito mais espaço que um chat de 4k. É por isso que o Ollama amarra o tamanho de contexto padrão à VRAM.
• Modelos pequenos sofrem com ferramentas. Agentes dependem de tool calls confiáveis e de seguir um system prompt longo. Modelos pequenos tendem a gerar chamadas malformadas, entrar em loop ou parar cedo. O Goose observa que alguns modelos, como o DeepSeek-R1 nativo, nem suportam tool calling.
• A velocidade se acumula. Um agente faz muitas requisições por tarefa, cada uma com um prompt grande. Um modelo que parece ok no chat pode fazer uma tarefa de dez passos demorar muito.

Um jeito prático de começar: pegue o maior modelo de código com suporte a ferramentas que rode inteiro na sua GPU com pelo menos 32k a 64k de contexto, confirme com ollama ps e teste numa tarefa pequena e real antes de confiar a ele algo maior.

Por que ir para o local: privacidade e controle

O principal motivo é que a inferência fica na sua máquina:

• Seus prompts e seu código não são enviados a um provedor de modelo.
• Funciona offline e em ambientes isolados.
• Sem conta por token e sem limites de uso para esbarrar.
• O modelo não muda debaixo de você; você decide quando atualizar.

Duas ressalvas mantêm isso honesto. Primeiro, a CLI ainda pode usar a rede: o Codex com o perfil de launch do Ollama tem busca na web, e algumas CLIs têm telemetria. Confira as configurações de cada ferramenta se absolutamente nada puder sair da máquina. Segundo, rodar localmente não torna o agente em si mais seguro. Ele continua rodando comandos e editando arquivos, então as boas práticas de segurança para agentes de código de sempre se aplicam.

Prós e contras frente a modelos hospedados

A diferença é menor em tarefas contidas: escrever um teste, explicar uma função, uma refatoração pequena, uma mensagem de commit. É maior em trabalhos longos de vários passos em muitos arquivos, onde o agente precisa manter um plano e se recuperar dos próprios erros.

Uma configuração híbrida que funciona

Dividir costuma funcionar melhor que uma troca tudo ou nada:

1. Trabalho sensível ou offline vai para o local. Código que não pode sair da máquina, repositórios de clientes com termos rígidos, trabalho no avião.
2. Tarefas rotineiras e contidas vão para o local. Testes, documentação, correções pequenas e explicações.
3. Tarefas difíceis vão para um modelo hospedado. Mudanças de arquitetura, bugs complicados, refatorações grandes.
4. Revise em um contexto novo. Deixe um segundo agente conferir o diff do primeiro, seja qual for o modelo que o escreveu.

O jeito mais simples de rodar isso é ter dois ou mais agentes ao mesmo tempo: um em um endpoint local, outro em um modelo hospedado, cada um na sua pasta ou git worktree para que não editem os mesmos arquivos.

Rodando agentes locais e hospedados lado a lado no AgentVera

O AgentVera é um app desktop que roda muitos agentes de CLI lado a lado em um só workspace, o que se encaixa na configuração híbrida acima. Para deixar claro o que ele faz e o que não faz:

• Ele não tem integração embutida com Ollama ou LM Studio. Cada agente usa sua própria configuração de provedor: goose configure para o Goose, a configuração do próprio opencode e /connect, as variáveis de ambiente ou o .aider.conf.yml do Aider, o login ou a chave de API do Qwen Code, as configurações do Crush (Ctrl+L).
• O campo “Model” é repassado à CLI. Para agentes como Qwen Code, Goose e Aider, o que você digita ali vai para a CLI como --model. Para o Goose, a dica diz: “If left empty, the model chosen with goose configure is used.” (se ficar vazio, usa o modelo escolhido com goose configure).
• Agentes podem levar variáveis de ambiente. Em Settings → Accounts → Accounts of other agents, uma conta adicionada “With an API key” guarda um “Variable name” e seu valor. Para o Qwen Code, OPENAI_BASE_URL é um dos nomes sugeridos, e qualquer outro nome pode ser digitado. Isso faz parte da troca de contas nos planos Pro e Team.
• As ferramentas de contexto vão além do Claude Code. O tamanho do contexto é medido a partir do histórico de cada CLI, e o auto-compact usa o próprio comando de compactação da CLI quando ela tem um. Com uma janela local pequena, isso importa ainda mais.

Então o quadro realista é: você configura o modelo local na CLI do jeito que a documentação dela descreve, e o AgentVera permite rodar esse agente ao lado de um hospedado, acompanhar os dois e manter o trabalho deles separado.