Como usar o Ollama com seu agente de código

O que você está conectando

Você pode usar o Ollama com o seu agente de programação, e a ligação é mais simples do que parece. Basta alterar uma URL base e escolher um nome de modelo. O campo da chave da API continua a exigir um valor, mas o servidor local ignora-o, portanto qualquer sequência funciona.

O Ollama escuta na porta 11434 e disponibiliza dois formatos de pedido ao mesmo tempo. /v1/chat/completions é o formato compatível com a OpenAI, e a documentação do Ollama descreve a chave nesse formato como obrigatória, embora seja ignorada. /v1/messages é o formato compatível com a Anthropic, que é o utilizado pelo Claude Code. O seu agente já utiliza 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 em que ele é bom. Cada definição tem a sua própria secção, e as limitações reais são apresentadas no final.

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

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

Ollama disponibiliza 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, em agosto de 2026, são consideradas agentes de programação. Nem todas usam o mesmo formato, e é aí que as configurações falham.

• A maioria dos agentes requer um endpoint compatível com OpenAI. Indique o URL base http://localhost:11434/v1 e qualquer string de chave API não vazia.
• O Claude Code não aceita um URL base OpenAI. Usa a API Anthropic Messages, por isso requer 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, desde a versão 0.13.3.
• Um agente sem uma definição de URL base não pode ser redirecionado, porque o endpoint está integrado no cliente. Coloque uma camada de tradução à frente, como um gateway LiteLLM autoalojado, e volte a expor o seu modelo no formato exigido pelo cliente.

O Ollama pode criar 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 faça pull de 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 fazer pull. 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.

Agora confirme quais os nomes que o servidor disponibiliza efetivamente:

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

As strings dessa resposta são as que a configuração do 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, o guia mais detalhado está em alojar um LLM com Ollama num VPS.

Apontar 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 para o Ollama, por isso tem de corresponder exatamente a ollama ls. O campo name é apenas a etiqueta apresentada 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 é explicada 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 intencionalmente como uma cadeia vazia. Uma chave real presente no ambiente envia os seus pedidos para a API alojada, o que gera uma cobrança e impede a inferência local. ollama launch claude configura tudo isto por si.

Saiba o que a camada de compatibilidade não implementa. Ela não implementa tool_choice nem o armazenamento em cache de prompts. Também 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 ampla sobre o que é transferido e o que não é está explicada 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 continua a produzir resultados sem sentido

Esta é a secção importante. 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 sã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, e todos os servidores apenas com CPU, fica na primeira linha: 4,096 tokens. Apenas uma GPU de grandes dimensões obtém os 262,144 tokens da última linha.

Um agente envia 4096 tokens antes de fazer qualquer trabalho. 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. O que acontece a seguir é todo 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 estar disponíveis, pelo que o modelo responde com confiança sobre um ficheiro que já não consegue ver ou esquece uma instrução dada duas etapas antes. Esse mecanismo está por trás da maioria dos relatos de que um modelo local é demasiado limitado para escrever código.

A documentação do Ollama indica que tarefas como agentes e ferramentas de programação devem ser configuradas com 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:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps é a verificação. Apresenta uma coluna CONTEXT, e esse número é o 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 2 motivos. O esquema de conclusões de chat da OpenAI não tem um campo para o comprimento do contexto, pelo que um cliente compatível com OpenAI não pode solicitar esse valor. Além disso, a configuração é feita por servidor, pelo que todos os agentes que apontar para esse servidor a herdam. Se um modelo precisar de uma janela diferente, incorpore-a numa cópia com 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 pretendido. Quando parte do modelo passa para a CPU, a taxa de tokens diminui o suficiente para tornar inutilizável um ciclo de agente, e medir os tokens por segundo num LLM local é a forma de encontrar o limite real do seu servidor. O dimensionamento da máquina antes da compra é abordado em quanta RAM e CPU um VPS precisa para um agente de programação.

Mantenha 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 fazer uma pausa 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 o primeiro token aparecer. Isto 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 tamanho 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 é a única opção disponível. Quando precisar de libertar a memória, ollama stop qwen3-coder:30b descarrega o modelo sem parar o servidor.

Executar Ollama num servidor separado

Ollama fica associado a localhost. Para o 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 aberta à Internet permite que qualquer pessoa use 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 é usar 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 partilharem o mesmo servidor, o escalonador 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 throughput começa a causar problemas.

Onde um modelo de código local é vantajoso e onde não é

Um agente baseado num modelo que aloja não substitui uma API de fronteira em todas as tarefas. É claramente vantajoso em quatro tipos de trabalho.

• Edições mecânicas em massa, em que cada alteração é pequena e pode ser verificada. Renomear elementos num repositório, adicionar type hints, escrever docstrings e traduzir comentários. O modelo pode executar durante horas sem aumentar a fatura.
• Trabalho que não pode sair do seu hardware. Por exemplo, código de cliente abrangido por um acordo de confidencialidade ou um repositório interno que não está autorizado a enviar a terceiros.
• Máquinas offline e isoladas, onde não existe qualquer API alojada para contactar.
• Custo previsível. Depois de o servidor estar pago, um agente que consome tokens num ciclo não tem custo adicional. Numa API com tarifação por utilização, acontece o contrário. Quando uma GPU VPS compensa face aos tokens de API apresenta os cálculos.

É menos eficaz 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 pode gerar uma chamada de ferramenta malformada ou perder o plano após algumas interações. Nesse caso, passa mais tempo a orientá-lo do que a executar a tarefa manualmente. Isto não é um problema de prompt que possa resolver apenas escrevendo melhor o prompt. É uma limitação de capacidade.

Também é menos eficaz quando errar tem consequências elevadas e não vai ler cada linha. Dê ao modelo local tarefas restritas cujo resultado possa verificar e reserve um 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 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 um 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 ter suporte a ferramentas ou o pedido, juntamente com as definições das ferramentas, pode já ocupar toda a janela de contexto. Verifique o rótulo tools na página do modelo e, depois, a coluna CONTEXT em ollama ps.

Há um longo silêncio 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 apresenta um valor CONTEXT inferior ao que pensa ter definido, porque a variável de ambiente foi aplicada à sua shell em vez de ser aplicada à unidade systemd.

Tudo funciona, mas lentamente, e PROCESSOR não é 100% GPU. O modelo e o respetivo contexto não cabem na VRAM. Reduza o tamanho do contexto ou mude para um modelo menor ou para uma quantização menor.

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 Anthropic Messages API, 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 de contagem de tokens, pelo que as contagens de tokens apresentadas são aproximadas.

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 com base na VRAM que encontra. Abaixo de 24 GiB, esse valor predefinido é de 4,096 tokens, e o prompt de sistema e as definições das ferramentas de um agente excedem 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 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. 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 é especialmente afetado por 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 relê um histórico longo em cada pedido. Assim, 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.