Guia de campo do Claude Code em português

Claude Code com Ollama: dá para usar de graça com modelo local? Sim, mas não é o Claude

O Claude Code não tem plano grátis, e por isso a busca por "claude code com ollama" cresce: o Ollama roda modelos abertos no seu computador e conversa com o Claude Code. Funciona, e a própria doc do Ollama ensina. Abaixo, o passo a passo no Windows, o ajuste que quase todo mundo esquece e o que se perde, só pelo que as docs oficiais diziam em 18/10/2026.

Primeiro, o que você está trocando

Com o Ollama, o programa é o Claude Code, mas o modelo que pensa não é o Claude. É um modelo aberto, como o Qwen, o Gemma ou o Kimi, rodando na sua máquina ou na nuvem do Ollama. A doc do Ollama descreve assim: "Ollama connects Claude Code to local and cloud models through its Anthropic-compatible API". Ou seja, o Ollama finge ser a API da Anthropic, e o Claude Code manda os pedidos para ele.

A Anthropic é clara sobre o próprio lado: ela "doesn't support routing Claude Code to non-Claude models through any gateway". Funciona, mas sem suporte dela: se algo quebrar, quem responde é o Ollama, não a Anthropic.

O jeito curto: um comando

Com o Ollama e o Claude Code instalados, a doc do Ollama manda rodar:

ollama launch claude

Ele abre o seletor de modelo e já chama o Claude Code apontado para o Ollama. Para script ou CI, há a opção --yes, que "skips selectors, pulls the model when needed, and requires --model".

O jeito manual, no PowerShell

A doc do Ollama mostra as variáveis em bash (export). No PowerShell do Windows, o equivalente, só para a janela aberta, é:

irm https://claude.ai/install.ps1 | iex     # se ainda não tem o Claude Code
ollama pull qwen3-coder                      # baixa um modelo local
$env:ANTHROPIC_AUTH_TOKEN = "ollama"
$env:ANTHROPIC_API_KEY = ""
$env:ANTHROPIC_BASE_URL = "http://localhost:11434"
claude --model qwen3-coder

O que cada linha faz, pela doc:

ANTHROPIC_BASE_URL troca o endereço da API. Na doc do Claude Code, ela serve para "route requests through a proxy or gateway".
ANTHROPIC_AUTH_TOKEN=ollama é obrigatória, mas o valor não importa: "required but ignored", diz a doc do Ollama, porque o servidor local "does not validate API keys".
ANTHROPIC_API_KEY vazia segue a doc do Ollama. Na ordem de autenticação do Claude Code, o ANTHROPIC_AUTH_TOKEN já fica acima da chave (p. 10 do guia), então essa linha é só uma garantia a mais. No PowerShell 5.1, atribuir "" apaga a variável da janela, e o efeito é o mesmo.

Para conferir para onde o Claude Code está falando, rode /status dentro dele. A doc do Ollama lembra que "Claude settings can override shell variables": se um settings.json seu define outra URL, é ela que vale.

O ajuste que quase todo mundo esquece: o contexto

O Claude Code manda muito texto a cada pedido: instruções, ferramentas, arquivos lidos. A doc do Ollama pede no mínimo 64 mil tokens para "agents, and coding tools". Só que o padrão do Ollama depende da memória da placa de vídeo (VRAM):

VRAM da placa	Contexto padrão do Ollama
menos de 24 GiB	4 mil tokens
de 24 a 48 GiB	32 mil tokens
48 GiB ou mais	256 mil tokens

Se a sua placa tem menos de 24 GiB de VRAM, o padrão é 4 mil tokens, um dezesseis avos dos 64 mil que a doc pede. Suba o contexto no app do Ollama (o controle deslizante nas configurações) ou ao servir. A doc mostra em bash (OLLAMA_CONTEXT_LENGTH=64000 ollama serve); no PowerShell fica $env:OLLAMA_CONTEXT_LENGTH = "64000"; ollama serve. A doc avisa que mais contexto pede mais memória; se a placa não tiver, o modelo fica lento ou não carrega.

Modelos de nuvem do Ollama, os de nome terminado em :cloud, já vêm "set to their maximum context length by default", e não pesam na sua placa.

O que deixa de funcionar

O Ollama implementa "a subset of the Anthropic Messages API". Pela tabela de compatibilidade dele, ficam de fora, entre outros:

Prompt caching: sem cache, cada pedido reprocessa tudo, o que pesa no PC.
PDF: "document content blocks with PDF files" não são aceitos. Receitas que leem PDF direto pelo modelo não funcionam assim.
Imagem por URL: só imagem em base64.
Escolha forçada de ferramenta e busca na web hospedada: "Tool-choice controls, deferred tools, and hosted web search are not fully supported".

E o principal: o modelo precisa saber usar ferramentas. A doc pede um modelo "that supports tools"; com um modelo que não sabe, o Claude Code conversa, mas não edita arquivo nem roda comando.

Então, vale a pena?

Quer testar o Claude Code sem pagar a Anthropic? Com modelo local, só se a placa aguentar 64 mil tokens de contexto. Os modelos de nuvem do Ollama não pesam na placa; o que o plano grátis do Ollama cobre está em ollama.com/pricing, e muda.
Quer o resultado do Claude? Aí é o modelo da Anthropic: Pro, US$ 20 por mês no mensal ou US$ 17 por mês no anual (US$ 200 de uma vez), ou a API por token (p. 10).
Em qualquer dos dois: hooks e permissões são do Claude Code e valem igual. Skills, CLAUDE.md e subagentes dependem de o modelo seguir instruções e usar ferramentas, e um modelo aberto pequeno segue pior. É isso que o guia ensina, com o Windows primeiro.

Fora do livro: docs.ollama.com/integrations/claude-code, /api/anthropic-compatibility e /context-length, lidas em 18/10/2026; code.claude.com/docs/en/llm-gateway e /en/env-vars, lidas em 15/10/2026.