Usar Ollama no Claude Code e no Cursor (modelos locaux)

#Por que usar Ollama em Claude Code ou Cursor?

Três razões que sempre se repetem. Primeiro, a confidencialidade: um projeto de cliente sob NDA, código proprietário, segredos em texto claro nos arquivos — nada disso deveria ser enviado a terceiros. Depois, o custo: o Cursor Pro custa US$ 20 por mês, e o Claude Code consome tokens da Anthropic cujo custo rapidamente chega a US$ 50–100 por mês em uso intenso. Com Ollama, o custo é zero após a compra da GPU. Por fim, a resiliência: seu assistente não para quando a API da Anthropic tem um incidente ou quando sua conexão ADSL cai.

A relação entre vantagens e limitações é honesta: um Qwen3-Coder 30B rodando localmente não se equipara ao Claude Sonnet 4.6 ou ao GPT-5 em tarefas complexas de agentes que envolvem vários arquivos. Mas, para 80% dos usos cotidianos — completar código, refatorar, escrever um teste, explicar um bloco, gerar um commit — um modelo de programação de 9 a 30B em Q4 dá conta do trabalho com folga. E você sempre pode manter a nuvem em paralelo para as tarefas mais exigentes.

#O endpoint compatível com OpenAI do Ollama

Desde a versão 0.1.24, o Ollama expõe, além de sua API nativa, um endpoint compatível com a API OpenAI ChatCompletions. É isso que torna todo o restante possível: qualquer cliente OpenAI (SDK Python, SDK Node, Cursor, Cline, Aider, Continue, etc.) pode acessar o Ollama sem modificações, apenas alterando a URL base.

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-coder:30b",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

O formato da resposta é idêntico ao da OpenAI: choices[0].message.content, usage com prompt_tokens e completion_tokens, suporte a streaming via stream: true. A chave de API é ignorada — você pode enviar qualquer coisa no cabeçalho Authorization, e o Ollama aceita. Muitos clientes, porém, recusam um campo vazio: coloque ollama ou anything para agradá-los.

#Pré-requisitos

Ollama 0.5+

ollama --version deve responder. No Windows, o ícone na bandeja do sistema deve estar ativo. Se você estiver começando do zero, veja o guia de instalação do Ollama para seu sistema operacional.

GPU com 12 GB de VRAM ou Mac da série M com 16 GB ou mais

Um Qwen 3.5 9B Q4 = ~6,6 GB, um Devstral 24B Q4 = ~14 GB, um Qwen3-Coder 30B-A3B Q4 = ~19 GB. RTX 3060 12 GB = mínimo útil (Qwen 3.5 9B); RTX 4070/4080 16 GB ou Mac M3/M4 = Devstral 24B e Qwen3-Coder 30B completos.

Cursor 0.40+ ou Claude Code CLI

Cursor a partir de cursor.com (modo OpenAI personalizado integrado). Claude Code via npm install -g @anthropic-ai/claude-code.

Conhecimento mínimo sobre variáveis de ambiente

Para Claude Code, vamos usar ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN.

#1. Conectar o Cursor ao Ollama

O Cursor tem uma opção oficial para apontar para um endpoint compatível com a OpenAI. Isso funciona muito bem para o chat (Ctrl+L) e a edição inline (Ctrl+K). O agente Composer e o preenchimento automático Tab, por sua vez, continuam restritos aos modelos do Cursor na nuvem — é uma limitação do produto assumida pela Anthysphere.

1. 01
   Baixar um modelo de código

   Com 12 GB de VRAM, Qwen 3.5 9B (qwen3.5:9b) é um ótimo ponto de partida: desempenho razoável em francês, chamada de ferramentas, 256k de contexto. Com 16 GB, passe para Devstral 24B (devstral:24b); com 24 GB, para Qwen3-Coder 30B-A3B (qwen3-coder:30b), o MoE de código de referência.
2. 02
   Abrir as configurações do Cursor

   Ctrl+Shift+J (Cmd+, no Mac) → aba Models. Você vê a lista de modelos do Cursor (claude-3.5-sonnet, gpt-5, etc.) com controles de ativação.
3. 03
   Adicionar um modelo personalizado

   Clique em Add Model na parte inferior. Insira o nome exato do modelo Ollama: qwen3-coder:30b. Marque a caixa para ativá-lo.
4. 04
   Configurar a URL base

   Na seção OpenAI API Key, expanda Override OpenAI Base URL. Insira http://localhost:11434/v1 e clique em Save. No campo API Key, insira qualquer valor (ollama basta), pois o Cursor não aceita um campo vazio.
5. 05
   Verificar a conexão

   Clique em Verify. O Cursor envia uma requisição de teste ao seu Ollama. Se ele retornar 200, o botão fica verde e o modelo aparece no seletor do chat.

ollama pull qwen3-coder:30b

Uma vez configurado, o chat do Cursor (Ctrl+L) e a edição inline (Ctrl+K) funcionam com seu modelo local. O seletor de modelo no topo do painel de chat lista qwen3-coder:30b; os modelos do Cursor na nuvem continuam acessíveis se você quiser alternar ocasionalmente.

#2. Conectar o Claude Code ao Ollama

O Claude Code (a CLI da Anthropic) usa nativamente a API Messages da Anthropic, não a API Chat Completions da OpenAI. Os dois protocolos diferem em papéis, formato das chamadas de ferramentas e streaming. Para fazer o Claude Code se comunicar com o Ollama, é necessário um pequeno tradutor — um proxy que recebe dados no protocolo Anthropic Messages de um lado e envia dados no protocolo OpenAI Chat Completions do outro.

O projeto de referência para isso chama-se claude-code-router (musistudio/claude-code-router no GitHub). Instala-se com um único comando, roda localmente em uma porta e aceita regras de roteamento por modelo (ex.: enviar haiku para Ollama, sonnet para o verdadeiro Claude).

1. 01
   Instalar o Claude Code

   npm install -g @anthropic-ai/claude-code se ainda não tiver sido feito. claude --version deve responder.
2. 02
   Instalar claude-code-router

   npm install -g @musistudio/claude-code-router. Le binaire ccr est ajouté au PATH.
3. 03
   Baixar o modelo no Ollama

   Prefira um modelo que suporte chamadas de ferramentas: qwen3-coder:30b, devstral:24b ou glm-4.7-flash. Sem suporte a chamadas de ferramentas, o Claude Code não poderá chamar suas ferramentas internas (Read, Edit, Bash, etc.) e perderá 90% da sua utilidade.
4. 04
   Configurar o roteador

   Crie ~/.claude-code-router/config.json com uma entrada Providers apontando para Ollama, e uma regra Router que mapeia os modelos Claude para o seu modelo local.
5. 05
   Iniciar via ccr

   ccr code no lugar de claude. O wrapper inicia o proxy em segundo plano, exporta ANTHROPIC_BASE_URL apontando para ele e então inicia o Claude Code. Dentro do Claude Code, /model permite alternar entre rotas.

ollama pull qwen3-coder:30b
# ou pour du pur agent de code
ollama pull devstral:24b

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3-coder:30b", "devstral:24b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3-coder:30b",
    "background": "ollama,qwen3-coder:30b",
    "think": "ollama,devstral:24b",
    "longContext": "ollama,qwen3-coder:30b"
  }
}

ccr code
# Claude Code démarre, mais les requêtes filent vers Ollama
# Vérifier : /model affiche qwen3-coder:30b

Abordagem minimalista sem roteador: você também pode exportar diretamente ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN para um proxy compatível com Anthropic (como LiteLLM no modo --anthropic ou y-router). É uma opção mais leve, mas sem a flexibilidade de regras por tarefa.

#3. Qual modelo de código escolher: Qwen3-Coder vs Devstral localmente

No Ollama, algumas famílias se destacam para programação no verão de 2026: Qwen3-Coder (Alibaba), Devstral (Mistral AI) e os modelos MoE versáteis como GLM 4.7 Flash (Z.ai) ou gpt-oss (OpenAI). Todas têm pesos abertos e funcionam em Q4 em hardware de uso comum.

Qwen3-Coder 30B-A3B (Alibaba, Apache 2.0)

Referência versátil em 2026. Suporte sólido a chamadas de ferramentas, multilíngue (francês correto), bom em Python/JS/Go/Rust, 256k de contexto. É um modelo MoE com 3B ativos: rápido como um modelo denso de 14B, com qualidade de 30B. ≈ 19 GB em Q4. Pull: qwen3-coder:30b.

Devstral 24B (Mistral AI, Apache 2.0)

Desenvolvido especificamente para agentes SWE (edição de vários arquivos, navegação pela base de código). Excelente no Aider, no OpenHands e, por extensão, no Claude Code. Modelo denso de 24B ≈ 14 GB em Q4, cabe em 16 GB. Pull: devstral:24b.

GLM 4.7 Flash (Z.ai, MIT) / gpt-oss 20B (OpenAI)

Dois modelos MoE muito à vontade no modo agente. GLM 4.7 Flash (30B-A3B, ≈ 19 GB) é um excelente orquestrador de chamadas de ferramentas; gpt-oss 20B (≈ 14 GB, MXFP4, 131k de contexto) é mais rápido e cabe em 16 GB. Pull: glm-4.7-flash ou gpt-oss:20b.

Qwen 3.5 9B (alternativa para GPUs de 8–12 GB)

Apenas 6,6 GB, um modelo generalista com bom desempenho em código, 256k de contexto e visão. Uma boa alternativa quando a VRAM é limitada, antes de passar para modelos de 24B ou mais. Pull: qwen3.5:9b.

VRAM por tamanho em Q4_K_M (quantização recomendada): 7B ≈ 5 GB, 14B ≈ 9 GB, 24B ≈ 14 GB, 32B ≈ 19 GB, 70B ≈ 40 GB. O contexto consome mais: adicione +2 a +4 GB para 32k tokens de contexto conforme o modelo.

#Limites em comparação com a nuvem: onde o local fica para trás

Sejamos honestos sobre o que os modelos locais não fazem tão bem quanto o Claude Sonnet 4.6 ou o GPT-5:

Janela de contexto

Por padrão, o Ollama limita num_ctx a 4096 tokens; é possível aumentar para 32k ou até 128k, dependendo do modelo, mas à custa de mais VRAM. O Cursor com Sonnet na nuvem lida com 200k tokens sem problemas. Em um grande monorepo, a solução na nuvem lê tudo, enquanto a solução local precisa escolher.

Raciocínio em múltiplas etapas

Um modelo de 9 a 14 bilhões de parâmetros se perde quando o agente encadeia 10 chamadas de ferramentas com dependências entre elas. O Sonnet mantém o fio do raciocínio. Para uma orquestração de agentes realmente complexa, a nuvem continua à frente — e de longe.

Conhecimento das APIs recentes

Modelos com pesos abertos têm uma data de corte de conhecimento (geralmente em 2025) e não conhecem as APIs lançadas depois disso. O Cursor na nuvem se beneficia de atualizações contínuas e de ferramentas de pesquisa na web.

Latência do primeiro token

Paradoxalmente, a nuvem pode ser mais rápida para iniciar (sem necessidade de carregar o modelo). Localmente, o modelo permanece carregado entre duas chamadas — a vantagem volta para a execução local após o primeiro prompt.

Custo de energia elétrica

Uma RTX 4090 sob carga consome 350 W. 8 horas por dia de programação intensa = ~70 kWh/mês = ~15 € na França. Esse custo fica muito abaixo de $20/mês pelo Cursor + $50/mês pelo Claude, mas não é gratuito.

#Dicas e solução de problemas

O Cursor retorna "OpenAI API key invalid"

O campo API Key deve conter um valor não vazio. Coloque ollama, sk-anything ou qualquer coisa plausível. É apenas cosmético: Ollama ignora o cabeçalho.

Cursor não vê o modelo

O nome do modelo no Cursor (Add Model) deve ser EXATAMENTE aquele retornado por ollama list (incluindo a tag, por exemplo, qwen3-coder:30b). Não apenas qwen3-coder, nem Qwen3 Coder.

Claude Code entra em loop ou pede a mesma coisa novamente

Muitas vezes, o modelo local falha nas chamadas de ferramentas. Verifique se o modelo suporta function calling (ollama show qwen3-coder:30b → procure a indicação tools em capabilities). Mude para um modelo maior ou simplifique a tarefa.

Respostas truncadas após 2-3 frases

num_ctx padrão = 4096. Para Claude Code e Cursor com contexto de base de código, aumente para 16384 ou 32768. Com Ollama: crie um arquivo Modelfile personalizado com PARAMETER num_ctx 32768 e faça ollama create coder-32k -f Modelfile. O custo de memória é real (+ 2-4 GB para o cache KV).

VRAM saturada, OOM

Verifique ollama ps durante o uso. Se você vir >100% loaded em GPU/CPU split, o modelo passa a usar também a RAM e fica muito lento. Soluções: quantização mais agressiva (Q3_K_M), modelo menor ou reduzir num_ctx.

Latência > 5 s por resposta

Ou o modelo está sendo parcialmente executado na CPU (ver o ponto anterior), ou o Ollama recarrega o modelo a cada requisição. Verifique OLLAMA_KEEP_ALIVE (por padrão, 5 minutos). Defina OLLAMA_KEEP_ALIVE=2h para manter o modelo carregado.

#Para se aprofundar

Você tem o Ollama fornecendo um modelo de código ao Cursor ou ao Claude Code. Os próximos passos naturais são:

Completar no editor (FIM inline)

O guia « Copilot gratuito em local » mostra como instalar Continue.dev / Tabby / CodeGeeX para completar código diretamente no editor, ao estilo do Copilot — um complemento natural ao chat no Cursor.

Escolher a quantização correta

Q4_K_M, Q5_K_M, Q8_0: o guia Escolher a quantização compara a perda real de qualidade nos modelos de código e explica quando um Q3 continua útil.

Personalizar um modelo de código

O guia Personalizar um modelo com Ollama Modelfile mostra como definir o num_ctx, o prompt de sistema e a temperatura para ter um modelo de programação adaptado à sua stack.