Módulo 3.3: Configurando Claude Code + Ollama

🔌 Como Claude Code Conecta ao Ollama

Claude Code usa uma variável de ambiente chamada ANTHROPIC_BASE_URL para saber para qual servidor enviar as requisições. Por padrão, aponta para os servidores da Anthropic. Basta mudar essa URL para apontar para o Ollama local.

🔌 O Mecanismo de Redirecionamento

Quando você define ANTHROPIC_BASE_URL="http://localhost:11434", toda requisição do Claude Code vai para o Ollama em vez da Anthropic.

O Ollama finge ser a API da Anthropic (usando o formato OpenAI compatível) e retorna as respostas do modelo local no mesmo formato esperado.

📊 Variáveis de Ambiente Necessárias

ANTHROPIC_BASE_URL — URL do servidor local Ollama (http://localhost:11434)
ANTHROPIC_AUTH_TOKEN — token de autenticação (qualquer valor, ex: "ollama")
ANTHROPIC_API_KEY — deve ser limpa ("") para não conflitar

⚡ Opção A: ollama launch claude

A forma mais simples. Um único comando configura tudo automaticamente e inicia o Claude Code apontando para o Ollama. Ideal para uso rápido e ocasional.

⚡ Comando Completo

# Certifique-se que Ollama está rodando, então:
ollama launch claude

Este comando detecta o modelo instalado, configura as variáveis e inicia o Claude Code. O modelo padrão é o último baixado.

✓ Vantagens

✓ Comando único, sem configuração manual
✓ Detecta automaticamente o modelo disponível
✓ Não modifica arquivos de configuração permanentes

✗ Limitações

✗ Configuração não persiste — precisa repetir a cada sessão
✗ Menos controle sobre qual modelo específico usar
✗ Pode não estar disponível em versões antigas do Ollama

🔧 Opção B: Variáveis de Ambiente

Definir as variáveis manualmente via export no terminal antes de executar o claude. Oferece controle total sobre qual modelo usar e é fácil de alternar entre Ollama e Anthropic.

🔧 Configuração Completa

# Passo 1: Definir variáveis (sessão atual)
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_API_KEY=""

# Passo 2: Iniciar Claude Code com o modelo desejado
claude --model qwen3-coder

As variáveis ficam ativas apenas na sessão atual do terminal. Fechar o terminal e abrir outro requer repetir os exports.

💡 Dica: Criar um Alias

Para não repetir os exports toda vez, adicione um alias no seu ~/.bashrc ou ~/.zshrc:

alias cc-ollama='ANTHROPIC_BASE_URL="http://localhost:11434" \
  ANTHROPIC_AUTH_TOKEN="ollama" \
  ANTHROPIC_API_KEY="" \
  claude --model qwen3-coder'

Depois: cc-ollama inicia o Claude Code com Ollama em um único comando.

💾 Opção C: settings.json Permanente

A opção mais conveniente para quem usa Ollama como backend padrão. Configurar uma vez no ~/.claude/settings.json e o Claude Code sempre vai usar Ollama ao iniciar.

💾 Arquivo de Configuração

Caminho: ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_API_KEY": ""
  }
}

O bloco "env" define variáveis que Claude Code carrega automaticamente ao iniciar.

Criar ou Editar o Arquivo

Se o arquivo não existe, crie-o

mkdir -p ~/.claude && nano ~/.claude/settings.json

Adicionar o Bloco env

Colar o JSON de configuração

{ "env": { "ANTHROPIC_BASE_URL": "http://localhost:11434",
  "ANTHROPIC_AUTH_TOKEN": "ollama", "ANTHROPIC_API_KEY": "" } }

Iniciar Claude Code Normalmente

Sem nenhuma variável extra — a config é carregada automaticamente

claude --model qwen3-coder

🔑 Primeiro Login com Ollama

Na primeira execução com as variáveis configuradas, o Claude Code pode apresentar o fluxo de autenticação. Selecione "Anthropic Console account" e use a sua API key normal — ela é necessária apenas para autenticar o app, não para as chamadas ao Ollama.

🔑 Fluxo de Autenticação

1. Inicie o Claude Code: claude --model qwen3-coder

2. Se aparecer menu de autenticação, selecione "Anthropic Console account"

3. Forneça sua API key da Anthropic (usada apenas para autenticar o app)

4. A partir daí, todas as chamadas de modelo vão para o Ollama local

💡 Por que ainda precisa da API key?

Claude Code usa a API key da Anthropic para autenticação e billing tracking do próprio app. As chamadas de inferência (geração de texto) vão para o Ollama e não geram cobrança. A autenticação é separada do backend de modelo.

↩️ Como Voltar ao Anthropic

Alternar de volta para o Claude da Anthropic é simples. O processo depende de qual método de configuração você usou para conectar ao Ollama.

Se usou variáveis (Opção B)

unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
claude  # usa Anthropic normalmente

Válido apenas na sessão atual. Novas sessões já iniciam sem as variáveis.

Se usou settings.json (Opção C)

# Editar ~/.claude/settings.json
# Remover o bloco "env":
{
  # apenas outras configurações
}

Persiste permanentemente até você editar o arquivo novamente.

🔄 Fluxo Recomendado para Alternar

# Usar Ollama (rápido/offline/gratuito):
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_API_KEY=""
claude --model qwen3-coder

# Na mesma sessão, voltar para Anthropic (máxima qualidade):
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
claude  # usa Claude 3.7 Sonnet da Anthropic

🎯 Quando Usar Cada Backend

🦙 Ollama: exploração, refatoração simples, código privado, sem internet, uso intensivo
🤖 Anthropic: tarefas complexas, código crítico, problemas difíceis, análise profunda

📋 Resumo do Módulo

✓

ANTHROPIC_BASE_URL é a chave — aponta para localhost:11434 para usar Ollama

✓

3 métodos de configuração — A: rápido (ollama launch), B: variáveis, C: settings.json permanente

✓

settings.json é a mais conveniente — configura uma vez, usa sempre

✓

API key ainda é necessária — para autenticar o app CC, não para as chamadas ao Ollama

✓

Alternar é simples — unset das variáveis devolve ao Anthropic imediatamente

Próximo Módulo:

3.4 — vLLM: Alternativa Avançada para hardware com GPU dedicada

← Módulo Anterior Próximo Módulo →