Como usar o Ollama com seu agente de código

O que você está a configurar

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

O Ollama escuta na porta 11434 e disponibiliza dois formatos de pedido em simultâneo. /v1/chat/completions é o formato compatível com a OpenAI, e a documentação do Ollama descreve a chave nesse formato como obrigatória, mas ignorada. /v1/messages é o formato compatível com a Anthropic, que é o formato usado pelo Claude Code. O seu agente já usa um dos dois formatos, portanto não é necessário alterar mais nada.

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

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

O teste consiste numa pergunta: a ferramenta expõe uma configuraçã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 próprio suporte para Ollama. Isto abrange a maioria das ferramentas que as pessoas entendem como agentes de programação em agosto de 2026. Estas ferramentas não usam todas o mesmo formato, e é nessa diferença que as configurações falham.

• A maioria dos agentes requer um endpoint compatível com OpenAI. Indique-lhes a URL base http://localhost:11434/v1 e qualquer string de chave de API não vazia.
• O Claude Code não aceita uma URL base OpenAI. Utiliza a API Anthropic Messages, por isso requer que ANTHROPIC_BASE_URL seja definido como http://localhost:11434, onde o Ollama disponibiliza /v1/messages.
• O Codex utiliza a API OpenAI Responses. O Ollama também disponibiliza /v1/responses, adicionado na versão 0.13.3.
• Um agente sem configuração de URL base não pode ser redirecionado, porque o endpoint está definido no cliente. Coloque antes dele uma camada de tradução, como um gateway LiteLLM self-hosted, 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 transfira 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 consiga emitir uma chamada de ferramenta descreve a alteração em prosa em vez de a executar, e o agente entra num ciclo ou para. Procure o rótulo tools na página do modelo em ollama.com antes de o transferir. qwen3-coder:30b tem esse rótulo e, em agosto 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 da memória para a tag Qwen 27B numa VPS mostra o que cabe efetivamente em 8 a 64 GB antes de iniciar o download. Depois de o transferir, esses gigabytes ocupam o disco raiz do servidor, que é a parte de uma VPS com menos espaço disponível, por isso vale a pena ler onde o Ollama guarda os ficheiros dos modelos e como movê-los para outro local antes de o disco ficar cheio.

Agora confirme quais os nomes que o servidor disponibiliza efetivamente:

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

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

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. Uma chave real deixada no ambiente envia os seus pedidos para a API alojada, o que gera custos e impede a inferência local. ollama launch claude configura tudo isto por si.

Saiba o que a camada de compatibilidade não suporta. 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 grande e um conjunto extenso de ferramentas, pelo que precisa de mais contexto do que um cliente de chat. A questão mais ampla sobre o que é transferido e o que não é está coberta em se pode alojar o Claude por conta própria.

Aponte 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/. 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 que importa. O Ollama escolhe um comprimento de contexto predefinido com base na VRAM (memória de vídeo da GPU) que consegue detetar, e esses valores predefinidos estão publicados:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

A maioria dos planos VPS, assim como todos os servidores apenas com CPU, fica na primeira linha: 4,096 tokens. Apenas uma GPU grande obtém os 262,144 tokens da última linha.

Um agente passa 4096 tokens antes de começar qualquer trabalho. O prompt de sistema, as definições das ferramentas, a listagem do repositório e o primeiro ficheiro que abre já ultrapassam esse valor. O que acontece a seguir é o problema principal: não ocorre nenhum erro. A documentação do Aider afirma que o Ollama descarta silenciosamente o contexto que excede a janela. Os tokens mais antigos desaparecem, por isso o modelo responde com confiança sobre um ficheiro que já não consegue ver ou esquece uma instrução que recebeu dois passos antes. Esse mecanismo está por trás da maioria dos relatos de que um modelo local é demasiado limitado para escrever código. Escolher o valor é uma decisão própria, e o custo de num_ctx na memória de cache KV em cada tamanho merece ser lido 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. Defina 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

ollama ps é a verificação. Imprime 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

Defina o valor no servidor, e não no agente, por dois motivos. O esquema OpenAI chat completions não tem um campo para o comprimento de contexto, por isso um cliente compatível com OpenAI não pode solicitar esse valor. Além disso, a configuração é feita por servidor, por isso todos os agentes que apontar para esse servidor herdam-na. A saída tem o seu próprio limite máximo e, ao contrário do comprimento de contexto, é transmitida pelo endpoint de compatibilidade. Por isso, num_predict e o campo max_tokens que é convertido nesse parâmetro são as opções a usar quando uma resposta termina a meio de um patch. Se um modelo precisar de uma janela diferente, incorpore essa definiçã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 usa mais memória, por isso monitorize a coluna PROCESSOR. 100% GPU é o valor pretendido. Quando parte do modelo passa a ser processada pela CPU, a taxa de tokens diminui o suficiente para tornar inutilizável um ciclo de agente, e medir tokens por segundo num LLM local é a forma de encontrar o limite real do 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 após o último pedido. Isto é adequado para uma caixa de chat, mas não para o trabalho de agentes. Pode pausar para analisar um diff, o temporizador termina e o pedido seguinte volta a carregar dezenas de gigabytes de pesos a partir do disco antes de apresentar o primeiro token. Isto parece uma suspensão.

OLLAMA_KEEP_ALIVE aceita uma 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 juntamente com o comprimento do contexto:

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

O campo de pedido keep_alive existe apenas nos endpoints nativos /api/generate e /api/chat do Ollama, não nos endpoints de compatibilidade. Por isso, um agente não pode defini-lo por pedido. A variável de ambiente é o único mecanismo disponível. Quando precisar de libertar a memória, ollama stop qwen3-coder:30b descarrega o modelo sem parar o servidor. Se quiser manter a definição após um reboot, ou comparar a retenção dos pesos na memória durante todo o dia com a recuperação dessa memória, manter um modelo Ollama carregado na memória funciona nas duas situações.

Executar o Ollama num servidor separado

O Ollama fica associado a localhost. Para aceder a ele 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 informa que a API local não exige autenticação. Por isso, deixar a porta 11434 aberta à Internet permite que qualquer pessoa utilize o seu hardware e leia tudo o que o seu agente enviar. Existem duas opções seguras. Mantenha a associação a 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 deteta a diferença. A outra opção é utilizar uma VPN, associando o Ollama ao endereço da VPN em vez de 0.0.0.0. Se várias pessoas ou vários agentes forem partilhar o mesmo servidor, o agendador do Ollama não foi concebido para essa carga. A comparação entre Ollama e vLLM mostra a partir de que ponto a diferença de rendimento começa a ser significativa.

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 aponta para outro host. Execute systemctl status ollama e depois journalctl -e -u ollama.

O agente informa que o modelo não existe. O nome na configuração não corresponde a nenhum nome disponibilizado pelo servidor. Compare-o com curl http://localhost:11434/v1/models e copie a string apresentada. A tag faz parte do nome. Por isso, uma configuração que indique uma tag que nunca foi obtida falha, mesmo que esteja instalado um modelo semelhante.

O agente responde em prosa e nunca edita um ficheiro. O modelo pode não suportar ferramentas ou o pedido, juntamente com as definições das ferramentas, pode já preencher a janela de contexto. Verifique o rótulo tools na página do modelo e depois a coluna CONTEXT em ollama ps.

Há um silêncio prolongado antes do primeiro token e depois a velocidade é normal. O keep-alive expirou e os pesos estão a ser lidos novamente do disco. Defina OLLAMA_KEEP_ALIVE.

O modelo contradiz um ficheiro que acabou de ler. O contexto foi truncado. ollama ps normalmente mostra um valor CONTEXT inferior ao que pensa ter definido, porque a variável de ambiente foi aplicada à sua shell em vez de à unidade systemd.

Tudo funciona lentamente e PROCESSOR não é 100% GPU. O modelo, juntamente com o contexto, não cabe na VRAM. Reduza o comprimento do contexto ou mude para um modelo menor ou para uma quantização menor. Antes de voltar a obter o modelo, este texto explica quanto q4_K_M, q8_0 e fp16 ocupam na memória, onde a qualidade diminui e quanto espaço uma redução de nível permite ganhar.

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 estas 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 para contagem de tokens. Por isso, as contagens de tokens apresentadas são aproximações.

Por que motivo o meu modelo local responde sobre código que não consegue ver?

Porque o pedido deixou de caber na janela de contexto, e a parte mais antiga foi descartada sem erro. O Ollama define o contexto predefinido com base na VRAM disponível. Com menos de 24 GiB, o valor predefinido é de 4,096 tokens, e o prompt do sistema e as definições das ferramentas de um agente ultrapassam esse valor por si só. Defina OLLAMA_CONTEXT_LENGTH=64000 na unidade systemd, reinicie o Ollama e confirme se a coluna CONTEXT em ollama ps apresenta o novo valor.

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

Escolha o maior modelo com a etiqueta tools que ainda caiba na memória com uma janela de contexto de 64k e dê preferência a um modelo otimizado para código. qwen3-coder:30b é a escolha habitual num servidor com GPU e VRAM suficiente. Se essa etiqueta exigir demasiados recursos 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 o download. Abaixo de aproximadamente 14B parâmetros, um modelo ainda pode responder bem a perguntas sobre código e, mesmo assim, falhar em edições com várias etapas, porque o trabalho de agente é sensível a 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 é suficiente para perguntas isoladas, mas um agente envia muitos pedidos por tarefa e relê um histórico extenso a cada pedido. Por isso, uma taxa de tokens baixa 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.