🦙 Motor Local com Ollama

Ollama é uma aplicação open-source que funciona como servidor local para rodar modelos de linguagem (LLM) diretamente na sua máquina, sem depender de nenhuma nuvem.

Com Ollama você usa Claude Code de graça, com privacidade total dos seus dados e sem depender de internet para cada requisição.

Roda como daemon em background; expõe API REST local; compatível com OpenAI API; suporta 100+ modelos open-source.

Usar modelos locais significa rodar inferência na sua própria máquina — nenhum dado sai do seu ambiente, nenhum custo por token é cobrado.

Para projetos confidenciais, desenvolvimento sem internet ou simplesmente para eliminar custos de API ao usar Claude Code no dia a dia.

Privacidade por design (dados não saem da máquina); custo zero após download do modelo; funciona 100% offline; latência depende do hardware local.

Ollama sobe um servidor HTTP na porta 11434 com endpoints compatíveis com a API da OpenAI, o que permite que ferramentas como Claude Code se conectem sem modificações.

Entender a arquitetura interna facilita a configuração, o debug e a substituição por outras soluções (vLLM, LM Studio) quando necessário.

Porta padrão 11434; endpoints /api/generate (nativo) e /v1/chat/completions (compatível OpenAI); modelos carregados sob demanda; descarrega da memória após inatividade.

Os requisitos variam pelo tamanho do modelo: modelos 7B precisam de ~8GB RAM, 14B exigem ~16GB, e modelos 30B+ requerem 32GB ou GPU dedicada.

Escolher o modelo errado para seu hardware resulta em performance inaceitável ou falha ao carregar. Conhecer os limites poupa tempo e frustração.

RAM é o gargalo principal; GPU NVIDIA (CUDA) ou AMD (ROCm) acelera muito; Apple Silicon unifica RAM/VRAM permitindo modelos maiores; CPU funciona mas é lento.

A instalação do Ollama é simples: no Linux/Mac basta um curl; no Windows há um instalador .exe; no Mac existe opção via Homebrew também.

Instalar corretamente garante que o serviço suba automaticamente no boot e seja acessível na porta padrão sem configurações adicionais.

Linux: curl -fsSL https://ollama.com/install.sh | sh; Windows/Mac: baixar de ollama.com; após instalar, ollama serve inicia o servidor; no Linux fica como systemd service.

O CLI do Ollama tem comandos simples para gerenciar modelos: baixar, listar, executar, mostrar informações e remover.

Dominar o CLI permite gerenciar o ciclo de vida dos modelos, verificar o que está instalado e fazer testes rápidos antes de conectar ao Claude Code.

ollama pull [modelo] — baixa; ollama list — lista instalados; ollama run [modelo] — chat interativo; ollama show [modelo] — info; ollama rm [modelo] — remove; ollama serve — inicia servidor.

O número (7B, 14B, 30B) representa a quantidade de parâmetros do modelo em bilhões. Mais parâmetros geralmente significa maior qualidade mas exige mais memória.

Escolher um modelo maior do que seu hardware suporta resulta em travamentos ou swap excessivo. A escolha certa equilibra qualidade e performance.

7B ≈ 4-6GB RAM (quantizado); 14B ≈ 8-10GB; 30B ≈ 18-22GB; 70B ≈ 40GB+. Quantização reduz tamanho com pequena perda de qualidade.

Guia de referência rápida para mapear sua RAM disponível ao tamanho de modelo suportado, incluindo casos especiais como Apple Silicon com memória unificada.

Essa tabela economiza horas de tentativa e erro — você sabe antes de baixar se o modelo vai caber e rodar de forma satisfatória.

8GB → 7B/8B (q4); 16GB → 14B/20B; 32GB → 30B; Apple Silicon 24GB → 24B; GPU 8GB VRAM → acelera 7B; GPU 24GB VRAM → 30B com velocidade.

Lista curada dos melhores modelos open-source para codificação em 2026, com foco em janela de contexto grande e performance em tarefas reais de desenvolvimento.

Com centenas de modelos disponíveis, escolher sem orientação é perdido. Essa lista prioriza modelos testados especificamente para uso com Claude Code.

qwen3-coder:30b (top performance); devstral-2-small:24b (especializado em código); granite3.3:8b (eficiente, bom para hardware limitado); glm-4.7-flash:9b (rápido, contexto longo).

A janela de contexto define quantos tokens (palavras/código) o modelo consegue processar de uma vez. Para Claude Code é crítico ter contexto grande para analisar arquivos completos.

Modelos com contexto pequeno truncam arquivos grandes, gerando respostas incompletas ou erradas. Contexto mínimo de 64K é requisito prático para uso real.

Contexto mínimo: 64K tokens; ideal: 128K+; verificar: ollama show qwen3-coder --modelfile; campo context_length no modelfile; contexto maior consome mais RAM durante inferência.

O comando ollama pull baixa o modelo da biblioteca oficial do Ollama (ollama.com/library), mostrando progresso em tempo real por camada.

Entender o processo de download (que pode demorar horas para modelos grandes) ajuda a planejar e evitar interrupções que corrompem o download parcial.

ollama pull qwen3-coder (tag padrão = latest); ollama pull qwen3-coder:30b (tag específica); download retomável se interrompido; modelos ficam em ~/.ollama/models/.

Antes de conectar ao Claude Code, testar o modelo diretamente pelo CLI garante que está funcionando e permite avaliar qualidade e velocidade de resposta.

Isolar o teste do modelo facilita diagnosticar problemas — se falha no CLI, o problema é no Ollama; se falha no CC, o problema é na configuração de conexão.

ollama run qwen3-coder; testar com "escreva um hello world em Python"; /bye para sair; medir tokens/segundo; verificar se contexto responde corretamente a instruções.

Claude Code usa a variável ANTHROPIC_BASE_URL para saber para onde enviar as requisições. Apontando para o Ollama local, todas as chamadas vão para seu modelo em vez da Anthropic.

Entender o mecanismo de redirecionamento permite configurar qualquer backend compatível com OpenAI API, não só Ollama.

ANTHROPIC_BASE_URL="http://localhost:11434"; Ollama expõe /v1/chat/completions; ANTHROPIC_AUTH_TOKEN="ollama" (pode ser qualquer valor); ANTHROPIC_API_KEY="" (limpar para não conflitar).

O comando ollama launch claude configura automaticamente todas as variáveis de ambiente e inicia o Claude Code apontando para o Ollama local.

É a forma mais rápida para quem quer usar Ollama sem se preocupar com configurações manuais. Ideal para uso ocasional.

Comando único; configura todas as vars automaticamente; inicia CC imediatamente; configuração não persiste entre sessões; requer Ollama rodando.

Definir as variáveis manualmente via export no terminal antes de executar o claude. Funciona na sessão atual do shell.

Controle granular para trocar entre Ollama e Anthropic na mesma sessão sem modificar arquivos de configuração.

export ANTHROPIC_BASE_URL="http://localhost:11434"; export ANTHROPIC_AUTH_TOKEN="ollama"; export ANTHROPIC_API_KEY=""; válido apenas na sessão atual do terminal.

Configurar as variáveis no arquivo ~/.claude/settings.json faz com que Claude Code sempre use Ollama ao ser iniciado, sem precisar de exports manuais.

Para quem usa Ollama como backend padrão, essa é a configuração mais conveniente — define uma vez e esquece.

Arquivo: ~/.claude/settings.json; bloco "env" define variáveis; persiste entre reinicializações; pode ser versionado; para voltar ao Anthropic: remover bloco env do arquivo.

Na primeira execução com as vars configuradas, Claude Code apresenta opções de autenticação. Para uso com Ollama, selecione "Anthropic Console account" e forneça qualquer API key válida ou use a que já tem.

O processo de login pode confundir iniciantes — entender que a API key é necessária apenas para autenticar o Claude Code, não para as chamadas ao Ollama, evita erros.

Selecionar "Anthropic Console account" no menu de auth; a API key da Anthropic ainda é usada para autenticar o app CC; chamadas de modelo vão para Ollama; sem custo por token.

Reverter para o backend Anthropic é simples: fazer unset das variáveis de ambiente ou remover o bloco env do settings.json.

Alternar entre Ollama (tarefas internas/offline) e Anthropic (tarefas que exigem máxima qualidade) é um fluxo comum no dia a dia.

unset ANTHROPIC_BASE_URL; unset ANTHROPIC_AUTH_TOKEN; unset ANTHROPIC_API_KEY; depois: claude inicia com Anthropic; alternativa permanente: remover bloco "env" do settings.json.

vLLM é um framework de serving de modelos open-source desenvolvido pela UC Berkeley, usando a técnica PagedAttention para maximizar throughput com GPU.

Para usuários com GPU dedicada, vLLM entrega 2-10x mais tokens por segundo que Ollama, ideal para uso intensivo ou múltiplos usuários simultâneos.

PagedAttention gerencia memória KV-cache eficientemente; API compatível com OpenAI; suporta continuous batching; melhor throughput com GPU; requer CUDA para máxima performance.

Comparação prática: Ollama é mais fácil de instalar e funciona sem GPU; vLLM é mais complexo mas entrega performance superior em hardware com GPU dedicada.

Escolher a ferramenta errada resulta em sub-utilização do hardware (usando Ollama em servidor GPU) ou complexidade desnecessária (vLLM sem GPU).

Ollama: fácil, sem GPU, uso pessoal; vLLM: GPU obrigatória, multi-usuário, alta performance; ambos têm API OpenAI compatível; vLLM consome mais RAM de sistema; Ollama tem interface web embutida.

vLLM é instalado via pip como pacote Python. Requer Python 3.9+, CUDA 11.8+ (para GPU NVIDIA) e PyTorch compatível.

A instalação tem dependências específicas de versão — errar na versão do CUDA ou PyTorch causa erros difíceis de diagnosticar.

pip install vllm; recomendado usar venv ou conda; verificar compatibilidade CUDA com nvidia-smi; instalação demora (compila extensões C++); pip install vllm[flash-attn] para máxima performance.

O servidor vLLM é iniciado via Python com o módulo api_server, especificando modelo, porta e parâmetros de GPU.

Os parâmetros de inicialização determinam performance e estabilidade — ajustar gpu-memory-utilization e max-model-len evita OOM e maximiza throughput.

python -m vllm.entrypoints.openai.api_server --model [HF_ID] --port 8000; --gpu-memory-utilization 0.9; --max-model-len para limitar contexto; modelos baixados do HuggingFace automaticamente.

O processo de conexão é idêntico ao Ollama: apontar ANTHROPIC_BASE_URL para a porta do vLLM (padrão 8000) e definir o token de autenticação.

Por compartilhar o mesmo mecanismo de conexão do Ollama, trocar entre os dois backends é questão de mudar apenas a URL e a porta.

ANTHROPIC_BASE_URL="http://localhost:8000"; ANTHROPIC_AUTH_TOKEN="vllm-token" (qualquer valor); --model deve usar nome do modelo HuggingFace no CC; vLLM deve estar rodando antes do CC.

vLLM oferece vários parâmetros de otimização: quantização AWQ/GPTQ para modelos menores, ajuste de batch size e controle de utilização de VRAM.

Sem otimização, vLLM pode não entregar a performance esperada. Cada GPU tem um sweet spot de configuração que precisa ser ajustado.

--quantization awq (modelos AWQ); --gpu-memory-utilization 0.85-0.95; --max-num-seqs (concurrent requests); Flash Attention 2 para GPUs Ampere+; tensor parallelism (--tensor-parallel-size) para multi-GPU.