Usar um modelo local no Claude Code com Ollama e voltar à nuvem

O Claude Code pode usar um modelo local pela API compatível com Anthropic do Ollama, mas receber uma resposta de chat não prova que o modelo esteja pronto para agir como agente de programação. Antes de confiar trabalho real a ele, verifique três condições: suporte a chamadas de ferramentas, capacidade da máquina para manter pelo menos 64k de contexto e uma tarefa pequena o suficiente para ser validada por comandos e diff.

Este guia mantém a mudança reversível. Você conectará o Claude Code ao qwen3.5 pela rota oficial do Ollama, executará um teste de aceitação com um único arquivo, verificará se a inferência realmente acontece localmente, revisará os limites de API e dados e removerá a configuração local antes de voltar a um endpoint em nuvem. Os comandos usam Bash no macOS, Linux ou WSL. São procedimentos para você executar, não resultados que este artigo afirma ter obtido no seu hardware.

Decida primeiro: local, nuvem ou um fluxo híbrido

Modelos locais funcionam melhor quando a tarefa tem limites claros e o resultado pode ser verificado mecanicamente. Um repositório grande, uma migração entre serviços ou uma depuração difícil costuma se beneficiar mais de um modelo em nuvem do que de um modelo local pequeno com grande offload para CPU.

Tipo de trabalho	Ponto de partida recomendado	Motivo
Correção de um arquivo, um novo teste ou explicação de uma função local	Testar local primeiro	O contexto é limitado e o resultado pode ser conferido por comando e diff
Módulo pequeno ou médio com dependências claras	Local ou híbrido	Passe primeiro pelo smoke test e aumente o escopo aos poucos
Monorepo grande, refatoração entre serviços ou investigação complexa	Nuvem primeiro	Exige mais contexto efetivo e planejamento de ferramentas mais confiável
O modelo não sustenta 64k sem grande offload para CPU	Nuvem primeiro	Latência e travamentos anulam boa parte da vantagem local
O fluxo exige prompt caching, Batches API, blocos PDF ou contagem exata de tokens	Nuvem primeiro	O Ollama implementa hoje apenas parte da Anthropic Messages API
O código não pode ser enviado a um modelo remoto	Local, com recursos cloud desativados	Ainda é necessário auditar web tools, servidores MCP e comandos de shell

Uma política híbrida útil mantém localmente alterações pequenas e repetíveis e muda de forma explícita para a nuvem em raciocínio sobre todo o repositório, recursos de API não compatíveis ou falhas locais recorrentes. Assim você preserva uma única interface do Claude Code sem fingir que os dois backends se comportam da mesma forma.

Etapa 1: escolha um modelo com ferramentas e reserve 64k de contexto

O Claude Code precisa de mais do que geração de texto. O modelo deve produzir chamadas de ferramentas com estabilidade para que o cliente leia arquivos, aplique alterações e execute comandos. A página do Qwen3.5 no Ollama informa suporte a tools e inclui o comando de inicialização do Claude Code. Também é possível inspecionar o modelo exato baixado pela API de detalhes do Ollama.

Baixe o modelo e examine capabilities:

ollama pull qwen3.5

curl http://localhost:11434/api/show \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5"}'

Antes de continuar, confirme que capabilities contém tools. Se não contiver, uma conversa normal não substitui a validação do agente. Escolha na biblioteca atual do Ollama um modelo explicitamente marcado para ferramentas, baixe-o e repita a verificação.

O contexto é o segundo filtro. A documentação de context length do Ollama recomenda pelo menos 64.000 tokens para web search, agentes e ferramentas de programação e informa que um contexto maior consome mais memória. No aplicativo Ollama, ajuste o controle de context length para 64000 ou mais. Ao iniciar o serviço por shell, pare primeiro a instância existente e rode isto em um terminal dedicado:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Mantenha esse terminal aberto. Aguarde o servidor iniciar e continue em um segundo terminal. Se a porta já estiver em uso, uma instância do Ollama já está ativa; altere a configuração de contexto dela em vez de iniciar outra.

Etapa 2: inicie o Claude Code pela integração oficial do Ollama

A rota oficial mais curta é:

ollama launch claude --model qwen3.5

Essa é a forma mais simples de estabelecer a integração. Depois que o Claude Code abrir, execute /status e anote as fontes de configuração ativas. Essa informação ajuda se uma camada persistente continuar redirecionando o cliente ao Ollama quando você tentar voltar à nuvem.

Para que a mudança dure apenas no terminal atual, configure as variáveis manualmente. O exemplo abaixo continua em Bash:

read -rs ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL="http://localhost:11434"
claude --model qwen3.5

read -rs recebe a entrada sem exibi-la. Digite ollama e pressione Enter. O endpoint compatível do Ollama exige que a variável de autenticação exista, mas o servidor local ignora o valor. ANTHROPIC_BASE_URL direciona as solicitações ao endpoint local, enquanto --model qwen3.5 torna o modelo de teste explícito e evita depender de um ANTHROPIC_MODEL antigo ou de um padrão salvo.

Etapa 3: valide leitura, edição e execução em um único arquivo

Não use um repositório de produção como primeiro teste. Crie um diretório isolado em que cada resultado possa ser conferido pelo arquivo, código de saída e diff.

mkdir -p claude-ollama-smoke
cd claude-ollama-smoke
git init
cat > total.py <<'PY'
def total(values):
    return sum(values)

if __name__ == "__main__":
    assert total([2, 3]) == 5
PY
git add total.py
python3 total.py

python3 total.py deve terminar com código 0 e sem saída. Inicie o Claude Code local nesse diretório e envie esta tarefa:

Altere somente total.py.
Se algum item de values não for int nem float, faça total lançar TypeError com a mensagem exata numbers only.
Em __main__, adicione uma verificação para [2, "3"] que confirme o mesmo TypeError e a mesma mensagem.
Execute python3 total.py.
Não altere nenhum outro arquivo. Mostre o diff ao terminar.

A tarefa é pequena de propósito, mas percorre o ciclo essencial do agente: ler o arquivo, planejar a alteração, chamar a ferramenta de edição, solicitar um comando Bash, observar o resultado e apresentar a mudança final. Mantenha os pedidos de permissão do Claude Code ativos. Um modelo local não torna seguro um shell sem restrições.

Depois da tarefa, execute você mesmo:

python3 total.py
git status --short
git diff -- total.py
ollama ps

Critérios de aceitação:

1. python3 total.py termina com código 0.
2. git status --short menciona apenas total.py, e git diff -- total.py contém somente a verificação de tipo e a asserção solicitadas.
3. A conversa do Claude Code mostra chamadas de ferramentas de arquivo e Bash, ou pedidos de permissão, em vez de apenas uma sugestão de código em texto.
4. Enquanto a tarefa está ativa, ollama ps lista qwen3.5, CONTEXT é de pelo menos 64000 e PROCESSOR mostra se o modelo está totalmente na GPU, parcialmente em offload ou principalmente na CPU.

Se algum item falhar, ainda não aumente o escopo para um repositório real. Diagnostique primeiro e depois decida entre trocar de modelo, reduzir a tarefa ou usar a nuvem.

Etapa 4: verifique o limite de execução, não só a URL localhost

ANTHROPIC_BASE_URL=http://localhost:11434 mostra que o Claude Code envia solicitações do modelo para uma porta local, mas não prova que todo o fluxo esteja offline. Evidência mais forte combina um tag sem :cloud, o modelo aparecendo em ollama ps durante a tarefa e valores locais de PROCESSOR e CONTEXT coerentes com os recursos da máquina.

A FAQ do Ollama afirma que o Ollama não vê prompts nem dados quando um modelo roda localmente, enquanto prompts e respostas de modelos hospedados na nuvem são processados pelo serviço cloud. A página atual do Qwen3.5 inicia o Claude Code com a tag local qwen3.5. Não deduza o nome de um modelo cloud apenas acrescentando um sufixo à tag local; para verificar esse limite, use uma tag explicitamente listada no catálogo Cloud ou no guia de integração oficial atual, como gemma4:cloud. Determine onde a execução ocorre por uma tag válida, por ollama ps e pela alocação local de recursos.

Audite separadamente as outras rotas de rede:

• Um comando chamado via Bash pode acessar a rede, enviar arquivos ou executar outro CLI.
• Um servidor MCP tem seu próprio processo, permissões e caminho de dados.
• Web search, web fetch e modelos cloud do Ollama não são inferência local.
• Hooks, scripts de teste e gerenciadores de pacotes do repositório também podem acessar serviços externos.

Para um modo Ollama mais estrito e somente local, mescle esta chave no ~/.ollama/server.json existente sem apagar outras opções:

{
  "disable_ollama_cloud": true
}

Reinicie o Ollama e confira se os logs contêm Ollama cloud disabled: true. O Ollama documenta que isso desativa seus modelos cloud e web search. Ainda assim, não audita outras conexões feitas pelo Claude Code, servidores MCP ou comandos de shell.

Etapa 5: entenda o que a camada compatível não garante

O Ollama oferece uma camada compatível com Anthropic Messages API, não uma reimplementação completa da Anthropic API. A documentação atual inclui messages, streaming, system prompts, imagens, tool calls, tool results e thinking entre os recursos compatíveis, o suficiente para formar o ciclo básico do Claude Code.

Compatibilidade de protocolo não significa paridade de comportamento. A qualidade da escolha de ferramentas, a precisão do patch, a estabilidade em tarefas longas e o cumprimento das instruções dependem do modelo, quantização, contexto alocado e hardware. Passar no teste de um arquivo prova que o caminho mínimo funciona no seu ambiente; não prova que o modelo local igualará um modelo Claude em um repositório grande.

Atualmente, o Ollama lista como não compatíveis /v1/messages/count_tokens, prompt caching, Batches API, citations, blocos PDF document e erros server-sent durante streaming. Ele também descreve a contagem de tokens como aproximação baseada no tokenizer do modelo. Se o fluxo depender de um desses recursos, mantenha uma rota cloud pronta em vez de descobrir a limitação no meio da tarefa.

Etapa 6: volte à nuvem de forma explícita

Se as variáveis locais existirem apenas na sessão Bash atual, saia do Claude Code e execute:

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY ANTHROPIC_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_OPUS_MODEL
claude

O novo processo poderá seguir o login normal da sua conta ou a configuração do provedor cloud. Depois de iniciar, consulte /status e faça uma pergunta pequena e somente de leitura. O cliente abrir não prova, por si só, que uma solicitação cloud foi concluída.

Se o Claude Code continuar acessando o Ollama, o redirecionamento provavelmente está salvo em settings, não na shell atual. A referência oficial de variáveis do Claude Code informa que um valor env em arquivo de settings substitui a mesma variável herdada da shell. Use /status para identificar as fontes ativas e remova ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY e overrides de modelo da camada aplicável:

• ~/.claude/settings.json
• .claude/settings.json
• .claude/settings.local.json
• settings gerenciados pela organização

Feche completamente e reinicie o Claude Code após a alteração. Um valor gerenciado não pode ser anulado por uma camada inferior; o administrador precisa alterá-lo.

Quando o modelo local não serve para a tarefa, mas você ainda quer uma API cloud compatível com Anthropic no mesmo Claude Code, siga o guia atual do BetterToken para Claude Code. O Base URL atual é https://bettertoken.ai: sem www e sem /v1. Primeiro copie o Model ID exato do model plaza. A configuração manual atual usa ANTHROPIC_MODEL para o modelo principal e as três variáveis ANTHROPIC_DEFAULT_*_MODEL para os aliases Haiku, Sonnet e Opus. Em um teste controlado, você pode apontar as quatro variáveis para o mesmo ID exato. Esta sessão temporária de Bash evita gravar a API Key no histórico:

read -rsp "BetterToken API Key: " ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
read -rp $'\nBetterToken Model ID: ' ANTHROPIC_MODEL
export ANTHROPIC_MODEL
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
export API_TIMEOUT_MS="3000000"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
claude

O primeiro prompt oculta a entrada da API Key; no segundo, cole o Model ID exato copiado do model plaza. Este smoke test aponta o modelo principal e os três aliases para o mesmo ID. Se você realmente precisar de modelos diferentes por função, defina em cada variável padrão o respectivo ID exato. Não acrescente /v1 ao Base URL. Depois de alterar settings persistentes, encerre completamente e reinicie o Claude Code; em uma sessão temporária, feche também o processo antigo antes de executar este bloco. Por fim, envie uma solicitação curta e somente leitura. Considere a troca concluída apenas se houver resposta normal, sem erro 401, de conexão ou de modelo, e se /status mostrar a fonte ativa esperada; isso não implica paridade total entre os caminhos local e cloud.

Solução dos problemas mais comuns

ConnectionRefused ou ausência de resposta de localhost:11434

Confirme que o processo do Ollama está ativo e que o endpoint usa a porta esperada. Inicie com ollama serve quando necessário. Se a porta estiver ocupada, encontre a instância existente em vez de criar outra. Antes de reabrir o Claude Code, verifique se curl http://localhost:11434/api/ps retorna JSON.

O chat responde, mas o Claude Code não lê nem edita arquivos

Chame /api/show novamente e confirme que o modelo anuncia tools. Depois observe os pedidos de permissão do Claude Code. Se o modelo apenas escreve “você poderia alterar assim” e nunca emite uma chamada de ferramenta, mude para um modelo explicitamente marcado para tools. O campo ser aceito pelo protocolo não garante planejamento confiável de ferramentas em todo modelo.

A sessão é muito lenta ou perde contexto em tarefas maiores

Execute ollama ps e confira PROCESSOR e CONTEXT. Grande offload para CPU, contexto abaixo de 64k ou pressão de memória recorrente são motivos para reduzir a tarefa, escolher um modelo menor com tools ou usar a nuvem. Não remova permissões e verificações apenas para a interação parecer mais rápida.

Alterar a shell não muda endpoint ou modelo

Execute /status no Claude Code. Um valor env de settings pode substituir a shell, enquanto --model e /model têm prioridade sobre ANTHROPIC_MODEL. Limpe a fonte que realmente vence, reinicie por completo e repita uma solicitação somente de leitura.

Regra prática de decisão

Trate o Claude Code local como um caminho de execução que precisa merecer um escopo maior, não como um simples botão. Confirme tools, reserve pelo menos 64k de contexto e use a tarefa de um arquivo para revisar chamadas de ferramentas, código de saída, diff e ollama ps. Só aumente o trabalho quando esses sinais estiverem estáveis.

Quando a tarefa ultrapassar a máquina, depender de um recurso Anthropic não compatível ou derrotar repetidamente o modelo local em código real, remova o endpoint local e volte à nuvem deliberadamente. Um caminho de retorno confiável vale mais do que forçar toda tarefa de programação a permanecer local.