Como usar o Ollama com seu agente de código

O que está a configurar

Pode usar o Ollama com o seu agente de programação, e a ligação é mais simples do que parece. Altere um URL base e escolha um nome de modelo. O campo da chave da API continua a exigir um valor, mas o servidor local ignora-o, por isso qualquer cadeia de texto funciona.

O Ollama escuta na porta 11434 e disponibiliza três interfaces de API ao mesmo tempo. /api é a API nativa do Ollama. /v1 é a camada compatível com OpenAI, que abrange várias estruturas: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models e /v1/embeddings. A documentação do Ollama indica que a chave é obrigatória, mas ignorada. A terceira interface é compatível com Anthropic: o cliente usa http://localhost:11434 como URL base e acrescenta /v1/messages, que é o formato usado pelo Claude Code. A maioria dos agentes usa /v1/chat/completions, o Codex usa /v1/responses e o Claude Code usa /v1/messages. O seu agente já usa uma destas interfaces, por isso nada mais muda na configuração.

Esta parte demora cinco minutos. A utilidade do resultado depende de duas definições que quase ninguém altera: o comprimento do contexto e o keep-alive. Também depende de atribuir ao modelo o tipo de trabalho para o qual ele é adequado. Cada definição tem a sua própria secção, e as limitações reais são apresentadas no fim.

Quais agentes de programação aceitam um URL base local

O teste consiste numa pergunta: a ferramenta expõe uma definição de URL base? Se expuser, pode comunicar com o seu servidor.

Ollama publica páginas de integração para Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs e VS Code. O Aider documenta separadamente o seu suporte para Ollama. Isto abrange a maioria das ferramentas que as pessoas consideram agentes de programação em outubro de 2026. Nem todas usam o mesmo formato, e é nessa diferença que as configurações falham.

• A maioria dos agentes espera um endpoint compatível com OpenAI. Defina o URL base http://localhost:11434/v1 e qualquer cadeia não vazia como chave API.
• O Claude Code não aceita um URL base OpenAI. Usa a API Anthropic Messages, por isso precisa de ANTHROPIC_BASE_URL definido como http://localhost:11434, onde o Ollama disponibiliza /v1/messages.
• O Codex usa a API OpenAI Responses. O Ollama também disponibiliza /v1/responses, adicionado na versão 0.13.3.
• Um agente sem definição de URL base não pode ser redirecionado, porque o endpoint está incorporado no cliente. Se o agente aceitar um URL personalizado, mas precisar de outro formato de API, coloque antes dele uma camada de tradução, como um gateway LiteLLM autoalojado, e disponibilize novamente o seu modelo no formato exigido pelo cliente.

O Ollama pode escrever estas configurações por si. ollama launch opencode inicia o OpenCode com uma configuração inline para o modelo escolhido, ollama launch claude faz o mesmo para o Claude Code e ollama launch droid --config escreve a configuração sem iniciar a ferramenta.

Instale o Ollama e descarregue um modelo que possa chamar ferramentas

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

O instalador adiciona uma unidade systemd e inicia-a, por isso systemctl status ollama deve apresentar active (running). Se isso não acontecer, journalctl -e -u ollama apresenta o motivo.

O modelo tem de suportar chamadas de ferramentas, porque é assim que um agente funciona. Lê um ficheiro, escreve um patch, executa o teste, lê a falha e tenta novamente. Um modelo que não consegue emitir uma chamada de ferramenta descreve a alteração em texto em vez de a fazer, e o agente entra num ciclo ou para. Procure o rótulo tools na página do modelo em ollama.com antes de o descarregar. qwen3-coder:30b tem esse rótulo e, em outubro de 2026, essa tag corresponde a um download de 19 GB com uma janela de contexto de 256K. Se o seu servidor usar apenas CPU ou tiver pouca RAM, a aritmética de memória da tag Qwen 27B numa VPS mostra o que cabe efetivamente em 8 a 64 GB antes de iniciar o download. Depois de o descarregar, esses gigabytes ficam no disco root do servidor, que é a parte de uma VPS com menos espaço disponível. Por isso, vale a pena ler onde o Ollama mantém os ficheiros dos modelos e como movê-los para outro local antes de o disco ficar cheio.

Agora confirme que nomes o servidor serve efetivamente:

curl http://localhost:11434/v1/models

As strings nessa resposta são as que a configuração do seu agente tem de conter, carácter por carácter. Verificar primeiro resolve a maioria dos erros de modelo não encontrado. Se o Ollama ainda não estiver instalado, consulte o guia mais detalhado em alojar um LLM com Ollama numa VPS.

Aponte o OpenCode para o Ollama

Edite ~/.config/opencode/opencode.json:

{
  "$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"
        }
      }
    }
  }
}

A chave em models é o nome do modelo enviado ao Ollama, por isso tem de corresponder exatamente a ollama ls. O campo name é apenas o rótulo apresentado no seletor de modelos. Inicie opencode, mude para o fornecedor Ollama e monitorize journalctl -e -u ollama para confirmar que o pedido chegou ao seu servidor, e não a outro local. A configuração do próprio agente é abordada em executar o OpenCode numa VPS.

Aponte o Claude Code para o Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY é definido como uma string vazia de propósito. A URL base controla para onde os pedidos são enviados; limpar esta chave impede que as credenciais alojadas sejam usadas nesta configuração local. ollama launch claude configura tudo isto por si.

Saiba o que a camada de compatibilidade não inclui. Ela não implementa tool_choice nem o armazenamento em cache de prompts e não tem um endpoint de contagem de tokens. Por isso, os números de tokens apresentados são aproximações baseadas no tokenizador do próprio modelo. O Claude Code também inclui um prompt de sistema extenso e um conjunto amplo de ferramentas, por isso precisa de mais contexto do que um cliente de chat. A questão mais abrangente sobre o que é transferido e o que não é está explicada em se pode alojar o Claude por conta própria.

Apontar o Aider para o Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

A documentação do Aider recomenda o prefixo ollama_chat/ em vez de ollama/. Por predefinição, o Aider solicita contexto suficiente para cada pedido, mais 8k tokens para a resposta. Também permite fixar a janela de contexto por modelo em .aider.model.settings.yml, o que é útil quando um modelo precisa de uma janela diferente da predefinida no servidor:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Por que uma configuração funcional ainda produz resultados sem sentido

Esta é a secção mais importante. O Ollama escolhe o tamanho de contexto predefinido a partir da VRAM agregada (memória de vídeo das GPUs) que consegue detetar, subtraindo OLLAMA_GPU_OVERHEAD por cada GPU detetada. A implementação usa estes limiares:

[
  {
    "label": "Under 23 GiB aggregate VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "23 to under 47 GiB aggregate VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "47 GiB aggregate VRAM or more",
    "default_context_tokens": "262,144"
  }
]

A maioria dos planos VPS, e todos os servidores apenas com CPU, fica na primeira linha: 4,096 tokens. Várias GPUs menores podem, em conjunto, atingir o limiar de 47 GiB correspondente aos 262,144 tokens da última linha.

Um agente envia 4096 tokens antes de executar qualquer tarefa. O prompt do sistema, as definições das ferramentas, a listagem do repositório e o primeiro ficheiro que abre já são maiores do que isso. É aqui que surge o problema: não ocorre nenhum erro. A documentação do Aider indica que o Ollama descarta silenciosamente o contexto que excede a janela. Os tokens mais antigos deixam de fazer parte do contexto. Assim, o modelo responde com confiança sobre um ficheiro que já não consegue consultar ou esquece uma instrução dada duas etapas antes. Este mecanismo está por trás da maioria dos relatos de que um modelo local é demasiado limitado para escrever código. Escolher o número em si é uma decisão independente, e vale a pena ler quanto custa num_ctx em memória de cache KV em cada tamanho antes de escolher um valor.

A documentação do Ollama indica que tarefas como agentes e ferramentas de programação devem usar pelo menos 64000 tokens. Configure esse valor no servidor:

sudo systemctl edit ollama.service

Adicione estas linhas ao ficheiro de override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Depois, recarregue a configuração e reinicie o serviço:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

Envie um pedido a partir do seu agente depois do reinício. Em seguida, execute ollama ps novamente para que exista um modelo carregado para inspeção. ollama ps é a verificação. Mostra uma coluna CONTEXT, e esse número é o valor que o modelo recebeu efetivamente. Os valores de ID e SIZE serão diferentes:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Configure o valor no servidor, e não no agente, por duas razões. O esquema OpenAI chat completions não tem um campo para o tamanho do contexto. Por isso, um cliente compatível com OpenAI não pode solicitar esse valor. Além disso, a configuração é aplicada por servidor. Todos os agentes que apontarem para esse servidor herdam o valor. O lado da saída tem o seu próprio limite. Ao contrário do tamanho do contexto, esse limite é transmitido pelo endpoint de compatibilidade. Por isso, num_predict e o campo max_tokens que corresponde a esse parâmetro são as opções a usar quando uma resposta fica incompleta a meio de um patch. Se um modelo precisar de uma janela diferente, incorpore essa configuração numa cópia usando um Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

O contexto não é gratuito. Uma janela maior consome mais memória, por isso monitorize a coluna PROCESSOR. 100% GPU é o valor que deve procurar. Quando parte do modelo passa a ser processada pela CPU, a taxa de tokens diminui o suficiente para tornar um ciclo de agente inutilizável. Medir tokens por segundo num LLM local permite encontrar o limite real do seu servidor. O dimensionamento da máquina antes da compra é explicado em quanta RAM e CPU um VPS para um agente de programação precisa.

Manter o modelo carregado entre pedidos

Por predefinição, o Ollama descarrega um modelo 5 minutos depois do último pedido. Isto é adequado para uma caixa de conversação, mas não para o trabalho de agentes. Pode pausar para ler um diff, o temporizador termina e o pedido seguinte volta a carregar dezenas de gigabytes de pesos a partir do disco antes de surgir o primeiro token. O resultado parece um bloqueio.

OLLAMA_KEEP_ALIVE aceita uma cadeia de duração, como 10m ou 24h, um número simples de segundos, -1 para manter o modelo carregado indefinidamente ou 0 para o descarregar imediatamente. Defina-o junto do comprimento do contexto:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

O campo de pedido keep_alive existe nos endpoints nativos /api/generate e /api/chat do Ollama e como extensão do Ollama em /v1/chat/completions. Um agente que exponha campos de pedido adicionais pode enviá-lo nesse campo; caso contrário, use a variável de ambiente. Quando precisar de libertar a memória, ollama stop qwen3-coder:30b descarrega o modelo sem parar o servidor. Se quiser que a definição sobreviva a um reboot, ou quiser comparar manter os pesos na memória durante todo o dia com recuperar essa memória, manter um modelo Ollama carregado na memória funciona através de ambos.

Executar o Ollama num servidor separado

O Ollama associa-se a localhost. Para lhe aceder a partir de outra máquina, defina OLLAMA_HOST=0.0.0.0:11434 na mesma substituição do systemd e reinicie o serviço.

Faça isto apenas numa rede privada. A documentação do Ollama indica que a API local não exige autenticação. Por isso, deixar a porta 11434 acessível pela Internet permite que qualquer pessoa use o seu hardware. Existem duas opções seguras. Mantenha a associação em localhost e encaminhe a porta por SSH a partir do seu portátil:

ssh -N -L 11434:localhost:11434 you@your-vps

O seu agente continua a apontar para http://localhost:11434/v1 e não percebe a diferença. A outra opção é usar uma VPN, com o Ollama associado ao endereço da VPN em vez de 0.0.0.0. Se várias pessoas ou vários agentes partilharem o mesmo servidor, o Ollama suporta pedidos em paralelo quando houver memória suficiente, e a comparação entre o Ollama e o vLLM mostra a partir de que ponto a diferença de throughput começa a ser um problema.

Onde um modelo de programação local é melhor e onde não é

Um agente orientado por um modelo alojado por si não substitui uma API de ponta em todas as tarefas. É claramente melhor em quatro tipos de trabalho.

• Edições mecânicas em grande escala, quando cada alteração é pequena e pode ser verificada. Renomear elementos num repositório, adicionar indicações de tipo, escrever docstrings e traduzir comentários. O modelo pode funcionar durante horas sem aumentar a fatura.
• Trabalho que não pode sair do seu hardware. Código de cliente abrangido por um acordo de confidencialidade ou um repositório interno que não está autorizado a enviar para terceiros.
• Máquinas offline e isoladas, sem qualquer API alojada para chamar.
• Custo previsível. Depois de pagar o servidor, um agente que consome tokens num ciclo não tem custos adicionais, ao contrário de uma API com tarifação por utilização. Quando um GPU VPS atinge o ponto de equilíbrio face aos tokens de uma API apresenta os cálculos.

É pior em tarefas longas com várias etapas. "Descobrir por que este teste falha, corrigir a causa e atualizar os chamadores" exige muitas chamadas corretas a ferramentas em sequência, mantendo todo o histórico no contexto. Um modelo na faixa de 8B a 14B num servidor modesto produzirá uma chamada de ferramenta malformada ou perderá o plano após algumas interações. Poderá gastar mais tempo a orientá-lo do que a executar a tarefa. Isto não é um problema de prompt que possa resolver escrevendo melhor o prompt. É uma limitação de capacidade.

Também é pior quando errar tem custos elevados e não vai ler todas as linhas. Dê ao modelo local tarefas restritas cujo resultado possa verificar. Reserve o modelo alojado para o trabalho que não verificaria passo a passo.

Modos de falha e as mensagens que verá

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. O servidor não está em execução ou o agente está apontado para um host diferente. Execute systemctl status ollama e, em seguida, journalctl -e -u ollama.

O agente informa que o modelo não existe. O nome na sua configuração não corresponde a um nome que o servidor disponibiliza. Compare-o com curl http://localhost:11434/v1/models e copie a string a partir daí. A tag faz parte do nome, portanto, uma configuração que nomeia uma tag que nunca foi baixada falhará, mesmo que um modelo semelhante esteja instalado.

O agente responde em prosa e nunca edita um ficheiro. Ou o modelo não tem suporte a ferramentas, ou o pedido somado às definições das suas ferramentas já preenche a janela de contexto. Verifique o rótulo tools na página do modelo e, em seguida, verifique a coluna CONTEXT em ollama ps.

Um longo silêncio antes do primeiro token, seguido de velocidade normal. O keep-alive expirou e os pesos estão a ser lidos do disco novamente. Defina OLLAMA_KEEP_ALIVE.

O modelo contradiz um ficheiro que acabou de ler. Truncamento de contexto. ollama ps mostra geralmente um valor de CONTEXT menor do que aquele que pensa ter definido, porque a variável de ambiente foi para a sua shell em vez de para a unidade do systemd.

Tudo funciona, lentamente, e PROCESSOR não é 100% GPU. Normalmente, o modelo somado ao seu contexto não cabe na VRAM. Se PROCESSOR indicar 100% CPU numa máquina que possui uma GPU, descarte primeiro a outra causa: o Ollama pode não ter encontrado a GPU de todo. A documentação do Ollama observa que, no Linux, após um ciclo de suspensão/retoma, por vezes falha a deteção de uma GPU NVIDIA e recorre ao CPU, e que recarregar o controlador com sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm pode contornar o problema. Se a GPU for encontrada e a divisão persistir, reduza o comprimento do contexto ou mude para um modelo mais pequeno ou uma quantização menor. Antes de voltar a fazer o pull, quanto custam em memória q4_K_M, q8_0 e fp16, e onde a qualidade realmente cai indica-lhe quanto espaço ganha ao descer um nível e o que perde com isso.

FAQ

Posso apontar o Claude Code para o Ollama?

Sim, mas não com um URL compatível com OpenAI. O Claude Code usa a API Anthropic Messages, e o Ollama disponibiliza esse formato em /v1/messages, na mesma porta 11434. Exporte ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama e um ANTHROPIC_API_KEY vazio e, em seguida, inicie-o com claude --model qwen3-coder:30b. ollama launch claude grava essas definições por si. A camada de compatibilidade não implementa tool_choice nem o armazenamento em cache de prompts e não tem um endpoint de contagem de tokens. Por isso, as contagens de tokens apresentadas são aproximações.

Porque é que o meu modelo local responde sobre código que não consegue ver?

Porque o pedido já não cabe na janela de contexto e a parte mais antiga foi descartada sem erro. O Ollama define o contexto predefinido a partir da VRAM total detetada, depois de subtrair a sobrecarga configurada por GPU: abaixo de 23 GiB, o valor predefinido é 4,096 tokens; de 23 até menos de 47 GiB, é 32,768 tokens; e com 47 GiB ou mais, é 262,144 tokens. Defina OLLAMA_CONTEXT_LENGTH=64000 na unidade systemd, reinicie o Ollama e confirme se a coluna CONTEXT em ollama ps mostra o novo valor.

Que modelo devo executar para um agente de programação numa VPS?

Escolha o maior modelo com a etiqueta tools que ainda caiba na memória com uma janela de contexto de 64k e prefira um modelo otimizado para código. qwen3-coder:30b é a escolha habitual num servidor com GPU e VRAM suficiente. Se essa etiqueta for demasiado grande para o seu servidor, os valores de RAM e as velocidades apenas com CPU do Nemotron 3.5 Lightning são uma comparação útil antes de iniciar a transferência. Abaixo de aproximadamente 14B parâmetros, um modelo ainda pode responder bem a perguntas sobre código e falhar em edições com várias etapas, porque o trabalho de agente penaliza pequenos erros de formatação nas chamadas de ferramentas. Teste com uma tarefa real do seu próprio repositório, em vez de usar um prompt de exemplo.

Preciso de uma GPU para executar um agente de programação no meu próprio modelo?

Na prática, sim. A inferência apenas com CPU funciona e é adequada para perguntas isoladas, mas um agente envia muitos pedidos por tarefa e volta a ler um histórico longo em cada pedido. Por isso, uma taxa baixa de tokens pode transformar uma tarefa de dois minutos numa tarefa de uma hora. Verifique a coluna PROCESSOR em ollama ps: qualquer valor diferente de 100% GPU significa que parte do modelo está a ser executada na CPU, e a taxa de tokens diminui acentuadamente.