Como Conectar o Claude Code a um LLM Local com o Ollama

     Este post é uma tradução de jeanvitor.com/connect-claude-code-local-llm-ollama/.

     Este post explica como conectar o Claude Code a um LLM local usando o Ollama, redirecionando as chamadas de API dos servidores da Anthropic para o seu próprio hardware. Cada vez mais desenvolvedores estão fazendo isso à medida que os modelos de código aberto e o hardware consumer melhoram. Os motivos variam: reduzir custos de API, manter o código fora de servidores externos por privacidade ou conformidade, ou simplesmente trabalhar offline.

O Que Vamos Usar

     O Claude Code é o assistente de programação agêntico da Anthropic, amplamente adotado no mercado. Ele lê e escreve arquivos, executa comandos e raciocina sobre toda a sua base de código. Por padrão, ele se comunica com a API da Anthropic, mas em essência é apenas um cliente HTTP seguindo um contrato de API específico, e é exatamente isso que vamos explorar.

     O Ollama é um runtime local para servir modelos de código aberto no seu próprio hardware. Existem outras opções que vale conhecer: o llama.cpp oferece controle de baixo nível, e o LM Studio tem uma experiência voltada para interface gráfica. Para este post, o Ollama é a escolha certa pela sua simplicidade.

Local vs. Nuvem

     Com a API da Anthropic você paga por token por um modelo rodando em infraestrutura enterprise level, e cada prompt sai da sua máquina. Rodar localmente dá a você custo zero por token e total controle sobre os seus dados, mas com menor qualidade e desempenho dependente do hardware. Os modelos de código aberto disponíveis hoje são até bem capazes, mas não são o Claude, e a diferença aparece em tarefas complexas com múltiplos arquivos. A aceleração por GPU é o que torna a inferência local prática: sem ela, o Ollama dá um fallback para CPU, e para uma ferramenta agêntica que gera grandes volumes de texto por turno, isso é lento o suficiente para ser um problema real.

Pré-requisitos

     Se você usa uma GPU NVIDIA, verifique que seus drivers, o nvidia-smi e o CUDA toolkit estão funcionando antes de qualquer outra coisa. Se o Ollama não conseguir acessar sua GPU, ele volta para CPU silenciosamente, e dependendo do tamanho do modelo isso pode significar inferência extremamente lenta ou o modelo se tornando completamente inutilizável. Você não vai receber nenhum aviso, então vale confirmar antes de começar.

     O nvidia-smi é uma ferramenta de linha de comando que consulta sua GPU NVIDIA e reporta seu estado atual. Quando ela é executada com sucesso, você deve ver uma tabela mostrando o modelo da GPU, versão do driver, versão do CUDA, VRAM total e uso atual de memória. Se o comando não for encontrado ou retornar erro, seus drivers não estão instalados corretamente. Se rodar mas não mostrar a GPU, o CUDA não está enxergando o dispositivo. De qualquer forma, resolva isso antes de continuar.

Instalando o Claude Code

     Se você ainda não tem o Claude Code instalado, o processo leva cerca de um minuto. No Linux ou macOS:

     No Windows (requer Node.js):

Escolhendo um Modelo

     Um requisito obrigatório: o modelo precisa suportar tool calling nativamente. O Claude Code simplesmente não vai funcionar com um modelo que não implemente isso. Ele depende inteiramente do uso de ferramentas para ler arquivos, executar comandos e interagir com o seu ambiente, então isso não é opcional.

     A biblioteca de modelos do Ollama vale a pena explorar. Mesmo um modelo de 8B pode produzir resultados úteis em tarefas bem delimitadas, mas para trabalhos mais exigentes, a partir de 27B é onde as coisas se tornam consistentemente confiáveis. Dois modelos que funcionam bem na prática são o qwen3.6:27b e o qwen3.6:35b. Para hardware mais limitado, o qwen3.5:9b também vale considerar: é menor, mas ainda suporta tool calling e performa relativamente bem. Sua página no Ollama é ollama.com/library/qwen3.5.

     Minha máquina tem um Intel Xeon W-11955M (16 núcleos @ 4.9GHz), uma NVIDIA RTX A3000 Mobile com 6GB de VRAM e 64GB de RAM. Com apenas 6GB de VRAM, os modelos maiores não são uma opção realista sem muito offloading para CPU, então optei pelo qwen3.5:9b. Vamos baixá-lo executando:

     Antes de se comprometer com um download grande, verifique se o modelo vai caber no seu hardware. Escrevi um post sobre uma ferramenta chamada llmfit que faz exatamente isso em um post anterior: ela analisa seu hardware e estima a viabilidade antes de você baixar qualquer coisa.

     Após o download, confirme o nome do modelo exatamente como o Ollama reporta:

     Esse nome é o que você vai usar na etapa de conexão. Copie com precisão, pois capitalização e sufixos importam.

Configurando a Janela de Contexto

     O Ollama frequentemente usa como padrão uma janela de contexto de 4096 tokens, o que não é suficiente para programação agêntica. O Claude Code envia prompts longos que combinam conteúdo de arquivos, histórico de conversa e saídas de ferramentas, e um limite de 4096 tokens vai causar problemas. Para corrigir isso, vamos aumentar para 16k. Execute ollama no seu terminal, selecione “Chat with a model”, escolha seu modelo e, dentro da sessão, execute:

     Em seguida, salve uma cópia do modelo com essas configurações para que persistam entre as sessões:

     Use um nome que reflita o modelo base e o tamanho do contexto. Esse nome é o que você vai referenciar ao conectar.

Conectando o Claude Code a um LLM Local com o Ollama

     Duas variáveis de ambiente são tudo que é necessário. No Linux ou macOS:

     No Windows PowerShell:

     Essas variáveis vão ser resetadas quando você fechar o terminal. Adicione as duas linhas ao seu ~/.bashrc (ou ~/.zshrc) e recarregue com source ~/.bashrc para torná-las persistentes. No Windows, defina-as como variáveis de ambiente permanentes do sistema via Propriedades do Sistema.

     A string do campo token é arbitrária. O Ollama não autentica, então o conteúdo da string não tem efeito nenhum. A variável que importa é ANTHROPIC_BASE_URL, que redireciona as chamadas de API do Claude Code para sua instância local. O Ollama também tem um atalho embutido: execute o comando ollama e selecione “Launch Claude Code” para pular essa configuração inteiramente.

     Com as variáveis definidas, inicie o Claude Code com o nome do modelo salvo:

Conectando ao Ollama em Outro Computador

     Se sua GPU está em outro computador e você quer se conectar a ela a partir da sua máquina atual, você precisa expor o Ollama na rede. No Linux, edite o arquivo de serviço do systemd:

     Na seção [Service], adicione:

     Em seguida, recarregue e reinicie:

     No Windows, defina OLLAMA_HOST=0.0.0.0 como uma variável de ambiente permanente do sistema via Propriedades do Sistema e reinicie o aplicativo Ollama.

     Note que 0.0.0.0 aceita conexões de qualquer máquina na sua rede. Garanta que sua LAN esteja adequadamente protegida. Para acesso externo, uma VPN é uma abordagem mais segura do que redirecionamento de porta.

     Na máquina cliente, aponte o Claude Code para o IP local do host. Por exemplo, para um IP de LAN 192.168.0.225, no Linux ou macOS:

     No Windows PowerShell:

Teste no Mundo Real

     Para colocar números aqui, fiz um teste rápido usando o qwen3.5:9b com a janela de contexto de 16K. Pedi ao Claude Code para escrever uma calculadora HTML funcional do zero. Ele produziu 175 linhas de código em aproximadamente 2 minutos e 30 segundos. Não é instantâneo, mas para uma tarefa autocontida rodando em hardware consumer com divisão de memória entre GPU e CPU, é genuinamente utilizável.

     A captura de tela abaixo mostra a divisão de memória que o Ollama reportou durante essa sessão. Com apenas 6GB de VRAM disponíveis, o modelo foi distribuído entre a GPU e a RAM do sistema, o que é responsável pela geração mais lenta em comparação com um modelo que cabe inteiramente na VRAM.

Qwen3.5:9b com contexto de 16K em uma RTX A3000 Mobile (6GB de VRAM). O Ollama distribui o modelo entre a GPU e a RAM do sistema quando a VRAM sozinha não é suficiente.

O resultado da sessão, a calculadora que o Claude Code construiu:

Considerações Finais

     Essa configuração funciona, e funciona razoavelmente bem em hardware capaz. A janela de contexto e a VRAM são as restrições reais: mire em pelo menos 8K de contexto, e tenha em mente que os modelos da Anthropic operam em uma escala simplesmente incomparável com o que roda localmente. Atualmente seus models são estimados em mais de um trilhão de parâmetros em infraestrutura dedicada. A diferença aparece em tarefas complexas, mas para trabalho focado e bem delimitado, a inferência local é uma alternativa sólida e cada vez mais prática.

TL;DR

     Para uma máquina remota, troque localhost pelo IP local do host. Adicione os exports ao ~/.bashrc para torná-los persistentes.