Como usar o Claude Code com modelos locais: guia completo para Ollama, LM Studio e llama.cpp

O Claude Code, da Anthropic, se tornou uma das ferramentas de desenvolvimento mais populares em 2026. Mas o que muita gente não sabe é que é possível executá-lo inteiramente com modelos locais, eliminando custos por token, limites de taxa e dependência de APIs externas.

Neste guia, você vai aprender a configurar o Claude Code para funcionar com três backends de inferência: Ollama, LM Studio e llama.cpp.

Como funciona

O Claude Code envia requisições no formato Anthropic Messages API. Ao redefinir a variável de ambiente ANTHROPIC_BASE_URL para apontar para um servidor local que "fale" o mesmo protocolo, o Claude Code passa a usar seu modelo local como se fosse o Claude oficial.

As variáveis de ambiente essenciais são:

• ANTHROPIC_BASE_URL — endereço do servidor local
• ANTHROPIC_API_KEY — placeholder (ex: "ollama"), servidores locais ignoram
• ANTHROPIC_DEFAULT_SONNET_MODEL / HAIKU_MODEL / OPUS_MODEL — mapeiam os tiers internos para o nome do seu modelo local

Importante: sem essas três variáveis de modelo, o Claude Code tenta usar claude-sonnet-4-20250514, que os servidores locais rejeitam.

Backend 1: Ollama (recomendado para começar)

O Ollama gerencia download, quantização e servidor de modelos com uma CLI simples.

Instalação e pull do modelo

# Instalar
curl -fsSL https://ollama.com/install.sh | sh

# Baixar um modelo recomendado (GLM-4.7 Flash)
ollama pull glm-4.7-flash:latest

Configuração temporária

export ANTHROPIC_BASE_URL="http://localhost:11434";
export ANTHROPIC_API_KEY="ollama"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7-flash:latest"
claude

Configuração permanente (~/.claude/settings.json)

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434";,
    "ANTHROPIC_API_KEY": "ollama",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7-flash:latest",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7-flash:latest",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7-flash:latest",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Backend 2: LM Studio

O LM Studio oferece interface gráfica e suporte nativo ao endpoint /v1/messages desde a versão 0.4.1.

1. Instale o app desktop ou CLI
2. Busque e baixe um modelo para código (ex: Qwen Coder)
3. Inicie o servidor local (porta padrão 1234)
4. Configure o contexto para ≥ 25.000 tokens

Configuração

export ANTHROPIC_BASE_URL="http://localhost:1234";
export ANTHROPIC_API_KEY="lm-studio"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen2.5-coder-32b-instruct"
# Repita para HAIKU e OPUS com o mesmo modelo

Backend 3: llama.cpp (controle total)

Para quem quer controle granular sobre parâmetros de inferência (quantização, contexto, camadas GPU).

Instalação

# Linux com CUDA
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Download do modelo GGUF
huggingface-cli download unsloth/GLM-4.7-Flash-GGUF \
  GLM-4.7-Flash-UD-Q4_K_XL.gguf --local-dir ./models/

Servidor

llama-server \
  --model ./models/GLM-4.7-Flash-UD-Q4_K_XL.gguf \
  --alias "glm-4.7-flash" \
  --port 8001 \
  --ctx-size 131072 \
  --flash-attn \
  --n-gpu-layers 99

Flags importantes:
- --alias deve corresponder ao nome do modelo nas variáveis de ambiente
- --ctx-size 131072 = 128K de contexto
- --flash-attn reduz uso de VRAM
- --n-gpu-layers 99 descarrega todas as camadas na GPU

Correção crítica: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS

O Claude Code adiciona cabeçalhos beta experimentais específicos da Anthropic que os servidores locais rejeitam. A variável CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS="1" remove esses cabeçalhos, evitando erros do tipo Unexpected value(s) for the anthropic-beta header.

Conclusão

Executar o Claude Code com modelos locais é surpreendentemente simples e elimina completamente os custos de API. O Ollama é a porta de entrada mais fácil, o LM Studio oferece a melhor experiência visual, e o llama.cpp dá controle total sobre a inferência.

Com esta configuração, você mantém toda a produtividade do Claude Code — edição de arquivos, execução de comandos, análise de código — rodando 100% offline e sem custo por requisição.

---

Fonte: KDnuggets