Claude Code de graça pelo Ollama é uma combinação que permite usar o ambiente de programação assistida por IA da Anthropic com modelos de linguagem rodando 100% localmente na sua máquina, sem custos de assinatura. A técnica ganhou destaque em maio de 2026, quando o portal Remessa Online publicou um guia detalhado sobre o método, confirmando que a abordagem já funciona de forma estável para desenvolvedores e entusiastas brasileiros.
O interesse por essa solução cresceu porque o Claude Code, ferramenta oficial da Anthropic para geração e edição de código via terminal, normalmente exige uma assinatura paga. Com o Ollama — plataforma open-source que executa Large Language Models (LLMs) localmente, sem enviar dados para servidores externos — é possível redirecionar o motor do Claude Code para modelos gratuitos como o Gemma 4 do Google ou o Llama da Meta, eliminando o custo mensal.
Neste tutorial, você vai aprender a instalar o Ollama, configurar o Claude Code para apontar para o servidor local e rodar o ambiente completo sem pagar nada. O procedimento foi validado com Ollama versão estável disponível em 2026 e Claude Code na versão de linha de comando distribuída pela Anthropic.
O que você precisa antes de começar
Para usar Claude Code de graça pelo Ollama, você precisa de um computador com pelo menos 8 GB de RAM (16 GB recomendado para modelos maiores), sistema operacional Windows 10+, macOS 12+ ou Linux Ubuntu 20.04+, e conexão com a internet apenas para o download inicial dos modelos.
Também é necessário ter o Node.js instalado (versão 18 ou superior), pois o Claude Code é distribuído como pacote npm. Verifique com node --version no terminal antes de continuar.
Passo 1 — Instale o Ollama na sua máquina
Acesse o site oficial do Ollama (ollama.com) e baixe o instalador para o seu sistema operacional. No macOS e Windows, basta executar o instalador gráfico; no Linux, o comando oficial é:
curl -fsSL https://ollama.com/install.sh | shApós a instalação, o Ollama sobe automaticamente um servidor local na porta 11434. Confirme que está rodando com ollama --version no terminal.
Passo 2 — Baixe um modelo de linguagem compatível
O Ollama suporta dezenas de LLMs gratuitos. Para geração de código, os mais indicados são o Gemma 4 (Google) e o Llama 3 (Meta), ambos com bom desempenho em tarefas de programação.
Para baixar o Gemma 4 (versão de 12 bilhões de parâmetros, que exige cerca de 8 GB de RAM), execute:
ollama pull gemma2:12bSe sua máquina tiver menos memória, use uma versão menor: ollama pull gemma2:2b. O download pode levar alguns minutos dependendo da sua conexão.
Passo 3 — Instale o Claude Code via npm
Com o Node.js já instalado, execute o seguinte comando no terminal para instalar o Claude Code globalmente:
npm install -g @anthropic-ai/claude-codeAguarde a instalação concluir. Você pode confirmar o sucesso com claude --version. Segundo a documentação oficial da Anthropic, o Claude Code é a interface de linha de comando projetada para interagir com modelos de linguagem diretamente no ambiente de desenvolvimento.
Passo 4 — Configure as variáveis de ambiente para apontar ao Ollama
Este é o passo central do tutorial. O Claude Code precisa ser redirecionado do servidor da Anthropic para o servidor local do Ollama. Faça isso definindo as variáveis de ambiente abaixo antes de iniciar o Claude Code:
No Linux/macOS, adicione ao seu ~/.bashrc ou ~/.zshrc:
export ANTHROPIC_BASE_URL=http://localhost:11434/v1
export ANTHROPIC_API_KEY=ollamaNo Windows (PowerShell), use:
$env:ANTHROPIC_BASE_URL = “http://localhost:11434/v1”
$env:ANTHROPIC_API_KEY = “ollama”A variável ANTHROPIC_API_KEY pode ter qualquer valor quando usada localmente — o Ollama não valida chaves reais, mas o campo precisa estar preenchido para o Claude Code não retornar erro de autenticação.
Passo 5 — Especifique o modelo local no Claude Code
Após configurar as variáveis, inicie o Claude Code informando qual modelo do Ollama usar. O parâmetro --model aceita o nome exato do modelo que você baixou:
claude --model gemma2:12bSe preferir o Llama 3, substitua por llama3:8b ou a variante que você baixou. O terminal vai abrir a interface interativa do Claude Code conectada ao seu modelo local.
Passo 6 — Teste a integração com um prompt de código
Dentro da interface do Claude Code, faça um teste simples para confirmar que tudo está funcionando. Digite um pedido como:
Crie uma função Python que lê um arquivo CSV e retorna as 5 primeiras linhas como lista de dicionários.O modelo local vai processar a requisição e retornar o código diretamente no terminal, sem enviar nada para servidores externos. O tempo de resposta depende do hardware: em um notebook com CPU Intel Core i7 de 12ª geração e 16 GB de RAM, o Gemma 2 de 12B leva entre 15 e 40 segundos por resposta — mais lento que a versão em nuvem, mas completamente gratuito e privado.
Passo 7 — Use dentro de um projeto real
Para aproveitar o Claude Code de graça pelo Ollama em um projeto existente, navegue até a pasta do projeto no terminal antes de iniciar:
cd /caminho/do/seu/projeto
claude --model gemma2:12bO Claude Code vai indexar os arquivos do diretório atual e permitir que você peça edições, refatorações e geração de novos arquivos diretamente no contexto do seu projeto. Comandos como /add arquivo.py incluem arquivos específicos no contexto da conversa.
Método alternativo: usando o Antigravity como proxy
Alguns tutoriais brasileiros, como o publicado pelo canal Robson Oliveira no YouTube, mencionam o uso de uma ferramenta chamada Antigravity como camada intermediária entre o Claude Code e o Ollama. Esse proxy facilita a compatibilidade de API em casos onde o Ollama apresenta erros de formato de resposta.
Para instalar o Antigravity, siga a documentação do repositório oficial no GitHub. A configuração substitui a variável ANTHROPIC_BASE_URL pela porta do Antigravity (geralmente 8976), que por sua vez encaminha as requisições ao Ollama. Esse método adiciona uma camada extra, mas resolve problemas de compatibilidade em versões mais antigas do Ollama.
Limitações reais que você precisa conhecer
Usar Claude Code de graça pelo Ollama tem desvantagens concretas em relação à versão paga com o modelo Claude 3.5 Sonnet da Anthropic. A principal é a qualidade das respostas: modelos locais como Gemma 2 e Llama 3 são significativamente menos precisos em tarefas complexas de programação, especialmente em debugging de código legado e arquiteturas multi-arquivo.
Outra limitação é o consumo de hardware: rodar um modelo de 12 bilhões de parâmetros localmente aquece o processador e pode deixar o computador lento para outras tarefas. Em máquinas com menos de 8 GB de RAM, os modelos menores (2B ou 3B parâmetros) entregam respostas de qualidade inferior, com mais erros de lógica.
Por fim, segundo reportagem do TecMundo publicada em janeiro de 2026, há riscos de segurança ao expor servidores de IA locais sem proteção adequada — mantenha o Ollama rodando apenas em localhost e nunca exponha a porta 11434 para redes externas.
Dicas avançadas para melhorar os resultados
Para extrair mais qualidade dos modelos locais, use prompts mais detalhados e específicos do que usaria com o Claude oficial. Quanto mais contexto você fornecer — linguagem, framework, padrão de código esperado — melhor será a resposta do modelo local.
Outra dica é experimentar o modelo Qwen2.5-Coder, disponível no Ollama com o comando ollama pull qwen2.5-coder:7b. Esse modelo foi treinado especificamente para geração de código e tende a superar o Gemma 2 genérico em tarefas de programação, segundo comparativos da comunidade open-source no HuggingFace.
Se o Claude Code retornar erros de formato de resposta, adicione a variável OLLAMA_ORIGINS=* ao ambiente antes de iniciar o Ollama. Isso resolve problemas de CORS (Cross-Origin Resource Sharing — política de segurança que pode bloquear requisições entre origens diferentes) que aparecem em algumas configurações.
Troubleshooting: erros mais comuns
Erro “Connection refused”: o Ollama não está rodando. Inicie com ollama serve em um terminal separado antes de abrir o Claude Code.
Erro “Model not found”: o nome do modelo na variável ou no parâmetro --model está diferente do que foi baixado. Confirme os modelos disponíveis com ollama list.
Respostas muito lentas ou travamento: o modelo escolhido é grande demais para a RAM disponível. Troque por uma versão menor (ex: de 12b para 7b ou 3b).
Erro de autenticação mesmo com Ollama local: verifique se a variável ANTHROPIC_BASE_URL foi exportada corretamente. No terminal, rode echo $ANTHROPIC_BASE_URL para confirmar o valor.
Usar Claude Code de graça pelo Ollama é uma alternativa viável para quem quer experimentar o ambiente de programação assistida por IA sem custos, especialmente em projetos pessoais e aprendizado. A configuração leva menos de 20 minutos e funciona de forma estável com modelos como Gemma 2 e Qwen2.5-Coder. Para uso profissional intenso, a versão paga com Claude 3.5 Sonnet ainda entrega resultados muito superiores — mas para estudar, prototipar e explorar IA no desenvolvimento, a combinação gratuita cumpre bem o papel.
Você já testou o Ollama com o Claude Code ou usa outra combinação de ferramentas locais para programação com IA? Conta nos comentários qual modelo deu os melhores resultados na sua máquina — a experiência da comunidade ajuda muito quem está começando.
[…] Claude Code de graça com Ollama: passo a passo completo para rodar local […]