Usando Ollama com Claude Code: Guia de Configuração de Modelos Locais

Claude Code é o agente oficial de codificação em terminal da Anthropic e, por padrão, se comunica com a API em nuvem da Anthropic. Ollama é um executor local de modelos que expõe uma API HTTP compatível com OpenAI. Os dois não falam o mesmo protocolo nativamente, portanto, conectá-los exige uma camada de proxy simples que traduza a API Messages da Anthropic na API de chat do Ollama. Este guia explica como isso funciona, quais modelos valem a pena executar e onde essa configuração apresenta limitações.

Por que Ollama e Claude Code não se conectam diretamente

Claude Code envia requisições no formato da API Messages da Anthropic (/v1/messages), com campos específicos da Anthropic para uso de ferramentas, controle de cache e prompts de sistema. Ollama expõe /api/chat e um endpoint compatível com OpenAI. /v1/chat/completions Nenhum dos dois fala o dialeto da Anthropic. Para interligá-los, é necessário um proxy que:

• Aceite requisições no formato Anthropic em um endpoint HTTPS.
• As reescreva como conclusões de chat compatíveis com OpenAI.
• As encaminhe ao Ollama e, em seguida, traduza respostas em streaming e chamadas de ferramentas de volta para o fluxo de eventos Anthropic esperado pelo Claude Code.

Dois projetos realizam essa tarefa de forma confiável em 2026: claude-code-router (um roteador desenvolvido especificamente para o Claude Code, com suporte a Ollama, OpenRouter e outros backends) e LiteLLM (um proxy de propósito geral com um modo de anthropic passagem direta). Ambos funcionam; o claude-code-router tem menos componentes se o Ollama for seu único backend.

Pré-requisitos

• Ollama instalado e em execução. Consulte como instalar o Ollama caso ainda não o tenha instalado.
• Claude Code instalado (npm install -g @anthropic-ai/claude-code).
• Pelo menos um modelo com capacidade de programação baixado localmente.
• Node.js 18+ para o claude-code-router ou Python 3.10+ para o LiteLLM.

Verifique se o Ollama está acessível:

curl http://localhost:11434/api/tags

Escolhendo um Modelo Local

Claude Code depende fortemente do uso de ferramentas, edições estruturadas e raciocínio em contextos longos. Modelos menores voltados para conversação geral lidam mal com essas tarefas. Prefira modelos ajustados especificamente para programação ou modelos instrucionais grandes.

O nível de quantização, o comprimento do contexto e o tamanho do cache KV afetam todos os requisitos de VRAM. Use a Calculadora de VRAM calculadora para dimensionar uma configuração específica e consulte melhores LLMs locais para Ollama para uma comparação mais abrangente.

Baixe um modelo antes de configurar o proxy:

ollama pull qwen3-coder:30b
ollama pull deepseek-coder-v2:16b

Opção 1: claude-code-router

O claude-code-router é o caminho mais direto. Instale-o globalmente:

npm install -g @musistudio/claude-code-router

Crie ~/.claude-code-router/config.json:

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

Inicie o Claude Code por meio do roteador:

ccr code

O roteador inicia um endpoint local compatível com Anthropic, define automaticamente as variáveis de ambiente para o Claude Code e redireciona o tráfego para o Ollama. Os nomes exatos dos campos de configuração mudaram entre versões menores — verifique o README do projeto caso alguma chave seja rejeitada.

Opção 2: Proxy LiteLLM

Se você já executa o LiteLLM para outros serviços, reutilize-o. Crie config.yaml:

model_list:
  - model_name: claude-sonnet-4
    litellm_params:
      model: ollama_chat/qwen3-coder:30b
      api_base: http://localhost:11434
  - model_name: claude-haiku-4
    litellm_params:
      model: ollama_chat/deepseek-coder-v2:16b
      api_base: http://localhost:11434

Execute-o:

litellm --config config.yaml --port 4000

Em seguida, aponte o Claude Code para o proxy (veja a próxima seção). O LiteLLM realiza a tradução de Anthropic para Ollama na rota /anthropic .

Apontando o Claude Code para o Proxy

O Claude Code lê duas variáveis de ambiente para redirecionar seu tráfego de API. Defina-as no seu shell antes de executar: claude.

macOS e Linux

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-anything"
claude

Adicione estas linhas ao ~/.zshrc ou ~/.bashrc para que persistam. O valor da chave não é usado pelo proxy local, mas o Claude Code se recusa a iniciar sem que ela esteja definida.

Windows (PowerShell)

$env:ANTHROPIC_BASE_URL="http://localhost:4000"
$env:ANTHROPIC_API_KEY="sk-anything"
claude

Para persistir entre sessões, use [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "http://localhost:4000", "User"). Se o Claude Code estiver instalado via WSL, configure as variáveis dentro do shell do WSL em vez disso — o Ollama executando no Windows é acessível a partir do WSL em http://host.docker.internal:11434 ou no endereço IP do host Windows.

Windows (nativo, sem WSL)

O Claude Code tem suporte oficial para macOS, Linux e WSL. Historicamente, o suporte nativo para Windows foi instável; execute-o sob WSL2, a menos que você tenha confirmado que a versão atual funciona perfeitamente na sua configuração.

Configurando Contexto e Tempos Limite

O Claude Code pressupõe um contexto de 200K tokens e um tempo rápido até o primeiro token. Modelos locais não atenderão a nenhum desses critérios. Dois parâmetros de ajuste são fundamentais:

• Comprimento do contexto do Ollama. Defina-o explicitamente por modelo usando um Modelfile (PARAMETER num_ctx 32768) ou a variável de ambiente OLLAMA_CONTEXT_LENGTH no servidor Ollama. O contexto padrão é pequeno e truncará silenciosamente conversas longas.
• VRAM do cache KV. Um contexto de 32K em um modelo de 30B consome vários GB apenas para o cache KV. Verifique o uso total de memória com ollama ps.

Para uma análise detalhada das necessidades de memória em diversos tamanhos de contexto, consulte Requisitos de VRAM por modelo.

Limitações Conhecidas

• O uso de ferramentas é frágil. As ferramentas de edição de arquivos, bash e busca do Claude Code dependem de saídas estritas em JSON para chamadas de ferramentas. Modelos locais falham com mais frequência nesse requisito, gerando chamadas malformadas ou alucinando conteúdos de arquivos. O qwen3-coder e o deepseek-coder-v2 estão entre os mais confiáveis, mas nenhum deles iguala o desempenho do Claude Sonnet.
• O cache de prompts é ignorado. da Anthropic campos cache_control são ignorados pelo proxy. Prompts de sistema longos são reenviados a cada rodada.
• Velocidade. Mesmo em uma GPU de 24 GB, um modelo de 30B com contexto de 32K gera entre 15 e 40 tokens/segundo. O loop agente do Claude Code faz muitas chamadas por tarefa, tornando o tempo real até a conclusão 5–10× maior que o da API em nuvem.
• Subagentes e MCP. Recursos avançados do Claude Code (agentes em segundo plano, servidores MCP) geralmente ainda funcionam, pois roteiam pelo mesmo proxy, mas qualquer recurso que dependa de comportamentos específicos do servidor Anthropic pode falhar silenciosamente.

Quando Usar Essa Configuração em vez da API

O uso local do Claude Code faz sentido quando: o código não pode sair de sua rede, você opera com orçamento limitado de API e realiza refatorações em massa, ou está experimentando autohospedagem. Ele faz menos sentido para codificação agente diária, onde o raciocínio de classe Sonnet é justamente o objetivo.

Para decidir numericamente, calcule os números de ambos os lados. A Calculadora de custos de API estima o custo mensal com a Anthropic, e a calculadora de ponto de equilíbrio entre hospedagem local e uso de API compara esse valor com a amortização da GPU. Para a maioria dos desenvolvedores individuais, a API é vantajosa; para equipes que utilizam intensivamente a API, um servidor local compartilhado pode se pagar em menos de um ano. Se você estiver especificando esse servidor, o guia melhores GPUs para LLMs locais aborda a faixa atual.

Alternativas ao Ollama para Este Fluxo de Trabalho

Se o desempenho do Ollama estiver limitando, outros executores com APIs compatíveis com a OpenAI funcionam de maneira idêntica por trás do mesmo proxy: LM Studio, vLLM e o servidor do llama.cpp se encaixam perfeitamente. Consulte o guia do LM Studio para uma opção voltada prioritariamente para interface gráfica (GUI), ou o Guia completo do Ollama para uma análise mais aprofundada do próprio Ollama.

Perguntas frequentes

O Claude Code pode usar o Ollama sem um proxy?

Não. O Claude Code comunica-se por meio da API Messages da Anthropic, e o Ollama não implementa esse padrão. É necessário uma camada de tradução, como o claude-code-router ou o LiteLLM. Configurar ANTHROPIC_BASE_URL diretamente como http://localhost:11434 falhará na primeira solicitação.

Qual modelo local se aproxima mais do Claude Sonnet para tarefas de programação?

Nas dimensões que a maioria das pessoas consegue executar efetivamente, o qwen3-coder (30B MoE) e o deepseek-coder-v2 (16B lite) são atualmente as melhores opções. Nenhum deles iguala o desempenho do Sonnet em tarefas agênticas envolvendo múltiplos arquivos, mas ambos são utilizáveis para edições em único arquivo, conclusões de código e revisão de código. Compare os índices de inteligência no Ranking de LLMs.

O cache de prompts funciona com o Ollama por trás do Claude Code?

Não. O cache de prompts da Anthropic é um recurso implementado no lado do servidor de sua API. Os proxies removem ou ignoram os campos campos cache_control ; portanto, cada solicitação processa novamente integralmente o prompt do sistema e o histórico da conversa. Essa é uma das razões pelas quais configurações locais parecem mais lentas por turno do que a API em nuvem, mesmo com uma taxa bruta de tokens semelhante.

Quanta VRAM é necessária para uma experiência satisfatória?

Uma única GPU de 24 GB (classe RTX 3090/4090/5090) executa um modelo codificador de 30B na quantização Q4 com cerca de 32K de contexto. Para modelos da classe 70B ou contextos mais longos, planeje utilizar 48 GB (RTX 6000 Ada, duas RTX 3090) ou mais. Use o Calculadora de VRAM para obter números exatos por modelo e quantização.

É possível misturar modelos locais e em nuvem na mesma sessão do Claude Code?

Sim, por meio de um roteador. O claude-code-router permite atribuir diferentes modelos a diferentes papéis — por exemplo, o Sonnet em nuvem para o agente principal e um modelo local para tarefas secundárias ou conclusões de código. Isso pode reduzir substancialmente os custos da API, mantendo alta qualidade no caminho crítico.

Existe uma forma oficial suportada pela Anthropic para executar o Claude Code localmente?

Não. A Anthropic distribui o Claude Code como um cliente para sua API e não disponibiliza os pesos do Claude. Todas as configurações locais são proxies comunitários apontando para modelos de terceiros. Caso a Anthropic altere a API Messages, os proxies poderão exigir atualizações antes que o Claude Code volte a funcionar com eles.