Instalação e configuração do Claude Code para Ollama, llama.cpp e preços

Código com agentes, agora com backends de modelos locais.

Conteúdo da página

Claude Code não é apenas autocompletar com melhor marketing. É uma ferramenta de codificação autônoma: lê sua base de código, edita arquivos, executa comandos e integra-se às suas ferramentas de desenvolvimento.

Essa diferença importa porque a unidade de trabalho deixa de ser “uma linha de código” e passa a ser “uma tarefa com um estado final”.

A Anthropic define essa distinção claramente: a conclusão de código sugere a próxima linha enquanto você digita, enquanto o Claude Code opera no nível do projeto, planeja através de múltiplos arquivos, executa alterações, roda testes e itera sobre falhas. Na prática, isso o torna mais próximo de um engenheiro júnior nativo do terminal que pode realizar tarefas rápidas, mas que ainda precisa de revisão.

Essa tensão entre velocidade e supervisão é o que muitas pessoas agrupam sob o termo “vibe coding”; O que é Vibe Coding? desmonta o termo, de onde vem e como a eficiência e o risco se manifestam na prática.

laptop-homeresver-claude-code-coffee-books

Um detalhe fácil de perder ao folhear a documentação: o Terminal CLI (e a superfície do VS Code) pode ser configurado para usar provedores de terceiros. É aí que entram o Ollama e o llama.cpp.

Uma vez que o Claude Code esteja apontando para um endpoint HTTP local, as compensações de tempo de execução, hardware e hospedagem ficam fora do cliente; esta comparação de hospedagem de LLM em 2026 alinha Ollama, pilhas de inferência dedicadas e opções de nuvem em um só lugar.

Para ver como o Claude Code se encaixa ao lado de outros fluxos de trabalho de codificação e entrega assistidos por IA, este guia de ferramentas para desenvolvedores de IA reúne assistentes estilo Copilot, automação e padrões de editor em um só lugar.

Para uma análise detalhada ferramenta por ferramenta de assistentes de codificação na mesma categoria, Comparação de Assistentes de Codificação de IA percorre Cursor, Copilot, Cline e o resto em um nível superior a este guia de instalação.

Instalação e início rápido do Claude Code

Opções de instalação e o que elas implicam

Existem vários caminhos de instalação, e eles não são iguais:

  • Scripts de instalação nativos são a opção “sempre atualizada” porque se auto-atualizam.
  • Homebrew e WinGet são a opção de “mudança controlada” porque você atualiza explicitamente.

Comandos de instalação (início rápido oficial):

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Em seguida, inicie uma sessão interativa a partir de uma pasta de projeto:

cd /path/to/your/project
claude

Login e tipos de conta

O Claude Code precisa de uma conta para funcionar no modo de primeira parte. O fluxo de início rápido suporta logins via assinatura Claude (Pro, Max, Team, Enterprise), uma conta Console (créditos de API) ou provedores de nuvem suportados. Uma nota operacional útil: no primeiro login no Console, um workspace “Claude Code” é criado para rastreamento de custos centralizado.

Configuração do Claude Code: settings.json e variáveis de ambiente

Se o Claude Code parece mágico quando funciona, muitas vezes parece “misterioso” quando não funciona. A cura é entender sua camada de configuração e as poucas variáveis de ambiente que realmente importam.

Arquivos de configuração e precedência

As configurações do Claude Code são hierárquicas, com três arquivos voltados para o desenvolvedor:

  • Escopo de usuário, aplica-se em todos os lugares: ~/.claude/settings.json
  • Escopo de projeto, compartilhado em um repositório: .claude/settings.json
  • Escopo local, sobrescritas por máquina: .claude/settings.local.json (ignorado pelo git)

A precedência é (do maior para o menor): política gerenciada, flags de CLI, local, projeto, usuário. Essa ordenação explica vários momentos de “por que minha configuração foi ignorada”.

Você pode gerenciar configurações interativamente via o comando /config, que abre uma UI de configurações dentro do REPL.

Variáveis de ambiente que controlam o roteamento do provedor

O Claude Code pode ser direcionado em tempo de execução por variáveis de ambiente. Dois comportamentos curiosos valem a pena tratar como restrições de design:

  1. Se ANTHROPIC_API_KEY estiver definida, o Claude Code usará a chave em vez de uma assinatura Claude, mesmo quando você estiver logado. No modo de impressão (-p), a chave é sempre usada quando presente.

  2. Se ANTHROPIC_BASE_URL apontar para um host não de primeira parte (um proxy, gateway ou servidor local), alguns recursos são intencionalmente conservadores. Por exemplo, a busca de ferramentas MCP é desabilitada por padrão, a menos que você a reative explicitamente.

Um padrão mínimo de “usar um gateway” parece com isso:

export ANTHROPIC_BASE_URL=https://your-gateway.example
export ANTHROPIC_API_KEY=sk-your-key

Nota sobre gateway: o Claude Code espera certos formatos de API. Para o formato Anthropic Messages, o gateway deve expor /v1/messages e /v1/messages/count_tokens e deve encaminhar os cabeçalhos anthropic-beta e anthropic-version. Se um gateway rejeitar esses cabeçalhos, existe um controle dedicado para remover betas experimentais.

Seleção de modelo no Claude Code quando você não está usando a Anthropic diretamente

O Claude Code tem um conceito de aliases (opus, sonnet, haiku) e também suporta a fixação de IDs de modelo específicos. Também existe uma lista de permissões que pode restringir o que os usuários podem selecionar no seletor de modelo, mesmo quando roteado através de provedores de terceiros.

Um padrão pragmático é definir um modelo inicial e restringir o seletor, depois fixar o que “padrão” resolve via ambiente:

{
  "model": "claude-sonnet-4-5",
  "availableModels": ["claude-sonnet-4-5", "haiku"],
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"
  }
}

Executando LLMs auto-hospedados via Ollama

O Ollama é atualmente a maneira de menor fricção para fazer o Claude Code rodar em modelos não-Anthropics, porque ele expõe uma API compatível com Anthropic para o Claude Code se comunicar.

Configuração rápida com ollama launch

Se você tem o Ollama instalado e em execução, o caminho rápido é:

ollama launch claude

Ou especifique um modelo no lançamento:

ollama launch claude --model glm-4.7-flash

Configuração manual com variáveis de ambiente explícitas

A integração do Ollama documenta um cabeamento manual simples onde o Claude Code se comunica com o Ollama através do endpoint de API compatível com Anthropic:

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

claude --model qwen3.5

Este padrão é opinativo de uma maneira útil: trata o “roteamento do provedor” como uma preocupação de ambiente, não algo que você clica em uma GUI.

Verificação de realidade da janela de contexto

A codificação autônoma é faminta por contexto. O Ollama aponta isso francamente: o Claude Code requer uma janela de contexto grande e recomenda pelo menos 64k tokens. Se seu modelo local atingir o limite em 8k ou 16k, o Claude Code ainda rodará, mas a promessa de “nível de projeto” torna-se frágil.

Para um comportamento prático de modelos locais em uma configuração de agente de terminal similar (Ollama e llama.cpp, tarefas de codificação e notas de falhas francas), Melhores LLMs para OpenCode - Testados Localmente é uma verificação útil quando você está fazendo uma lista curta de tags GGUF ou Ollama para o Claude Code.

Executando LLMs auto-hospedados via llama.cpp

llama.cpp é atraente por uma razão oposta: ele não está tentando ser uma plataforma. É um servidor rápido e leve que pode expor rotas compatíveis com OpenAI e uma rota de API compatível com Anthropic Messages.

Para caminhos de instalação, comportamento de llama-cli e llama-server além dos trechos abaixo, Início Rápido do llama.cpp com CLI e Servidor é a referência de ponta a ponta.

O que executar no lado do servidor

O servidor HTTP do llama.cpp (llama-server) suporta uma API de Mensagens compatível com Anthropic em POST /v1/messages, com streaming via SSE. Também oferece count_tokens em /v1/messages/count_tokens.

Dois detalhes importam para o Claude Code:

  • O servidor explicitamente não faz fortes afirmações de compatibilidade total com a especificação da API Anthropic, mas afirma que funciona bem o suficiente para muitos aplicativos.
  • O uso de ferramentas requer iniciar o llama-server com a flag –jinja. Se você perder isso, o Claude Code se comportará como se de repente esquecesse como ser um agente.

Uma execução local mínima parece com:

# Construa ou baixe llama-server, depois execute com um modelo GGUF
./llama-server -m /models/your-model.gguf --jinja --host 127.0.0.1 --port 8080

Se você quiser uma fronteira de autenticação rígida, o llama-server pode ser configurado com uma chave de API:

./llama-server -m /models/your-model.gguf --jinja --api-key my-local-key --host 127.0.0.1 --port 8080

Aponte o Claude Code para o llama-server

Com o servidor em execução, o lado do Claude Code é principalmente uma sobrescrita de URL base:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export ANTHROPIC_API_KEY=my-local-key   # apenas se você ativou --api-key no llama-server

claude --model your-model-alias

Se você não definir uma chave de API ou token de autenticação, o Claude Code pode tentar voltar para o login de assinatura, que é a fonte de muitas reclamações de “por que está abrindo um navegador”.

Verificações de saúde e primeira triagem de falha

llama-server expõe um endpoint de saúde simples que retorna “carregando modelo” até que o modelo esteja pronto, e “ok” quando estiver utilizável. Quando o Claude Code parece travar na primeira solicitação, verificar /health é uma maneira rápida de distinguir “bug de configuração do cliente” de “servidor ainda carregando”.

Precificação e modelo de custos

A precificação do Claude Code é menos sobre “comprar um CLI” e mais sobre “qual trilho de cobrança sustenta os tokens”.

Planos de assinatura incluem Claude Code

A Anthropic inclui o Claude Code nos níveis de assinatura paga do Claude. Até abril de 2026, a precificação publicada lista:

  • Pro a $17 por mês com desconto anual ($200 cobrado antecipadamente), ou $20 cobrado mensalmente, e inclui o Claude Code.
  • Planos Max começando a $100 por mês.
  • Planos Team precificados por assento, com assento padrão a $20 por assento por mês cobrado anualmente ($25 mensalmente) e assento premium a $100 por assento por mês cobrado anualmente ($125 mensalmente).

Precificação de tokens de API

Se você usar o Claude Code via cobrança de API, os custos seguem as taxas de token. A Anthropic publica precificação por milhão de tokens (MTok) para modelos como:

  • Haiku 4.5 a $1/MTok de entrada e $5/MTok de saída.
  • Sonnet 4.5 a $3/MTok de entrada e $15/MTok de saída.
  • Opus 4.5 a $5/MTok de entrada e $25/MTok de saída.

Controles de custos no CLI

O modo de impressão (-p) suporta limites de orçamento diretos como –max-budget-usd, o que é útil quando você está criando scripts de tarefas e quer gastos previsíveis.

Dentro de sessões interativas, /cost mostra estatísticas de uso de tokens.

Backends locais mudam a conta, não a física

Rotear o Claude Code para Ollama ou llama.cpp pode remover cobranças de API por token, mas não torna o trabalho gratuito. Você está trocando custos de nuvem por computação local, memória e “alguém possui a estabilidade”. Para algumas equipes, essa troca é todo o ponto.

Fluxo de trabalho típico: do plano ao PR

Meu viés é que o Claude Code é mais forte quando você o trata como um motor de fluxo de trabalho, não como um chatbot. As ferramentas dão dicas disso.

Comece com o modelo de permissão, não com o prompt

O Claude Code é bloqueado por permissão por design. Os documentos descrevem um modelo em camadas: operações de leitura, como leitura de arquivos e grep, são permitidas, enquanto comandos bash e modificações de arquivos precisam de aprovação.

Os modos de permissão existem para gerenciar o atrito. No CLI, você pode alternar modos com Shift+Tab (padrão -> acceptEdits -> plan). O modo Plan lê e propõe alterações, mas não edita. O modo acceptEdits permite que o Claude Code crie e edite arquivos em seu diretório de trabalho sem solicitar, enquanto ainda solicita comandos com efeitos colaterais fora de sua lista segura.

O modo Auto é uma opção mais recente que reduz prompts delegando aprovações para um classificador, posicionado como um caminho intermediário mais seguro entre prompts constantes e desabilitar prompts completamente. Requer uma versão mínima do Claude Code e requisitos específicos de plano e modelo.

Use comandos embutidos para manter as sessões honestas

Alguns comandos transformam o Claude Code de “assistente” em “ferramenta”:

  • /init gera um guia de projeto CLAUDE.md, que é uma maneira leve de alimentar contexto consistente.
  • /diff fornece uma visão interativa das alterações, incluindo diffs por turno.
  • /rewind permite recuar a conversa e/ou código para um ponto anterior, usando checkpoints.
  • /debug habilita log de debug no meio da sessão.
  • /doctor diagnostica e verifica sua instalação e configurações.

Estes não são truques; são as trilhas de segurança nas quais você se apoia quando um agente edita mais do que você esperava.

Quando ir para o modo não interativo

Para tarefas de uma única execução (explicar, resumir, gerar um plano de patch), o modo de impressão é uma boa opção:

claude -p "Resuma a arquitetura do repositório e liste os módulos mais arriscados"

Ele sai após a resposta, o que funciona bem em scripts e CI.

Lista de verificação de solução de problemas

A maioria dos problemas do Claude Code são problemas de configuração disfarçados. Aqui está uma lista de verificação que mapeia sintomas comuns ao mecanismo subjacente.

O Claude Code continua pedindo para fazer login enquanto usa um servidor local

Isso geralmente significa que o Claude Code ainda está tentando usar a autenticação de assinatura de primeira parte. Certifique-se de definir um modo de autenticação explícito para o proxy:

  • Defina ANTHROPIC_API_KEY para gateways que esperam X-Api-Key.
  • Ou defina ANTHROPIC_AUTH_TOKEN para gateways que usam Authorization Bearer.

Lembre-se de que ANTHROPIC_API_KEY sobrescreve o uso de assinatura mesmo se você estiver logado, e no modo interativo você pode precisar aprovar essa sobrescrita uma vez.

O gateway retorna erro nos cabeçalhos anthropic-beta

Alguns gateways rejeitam cabeçalhos desconhecidos ou campos beta. Existe uma variável de ambiente projetada para exatamente esse modo de falha:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

A documentação do gateway LLM também observa que você pode precisar disso ao usar o formato Anthropic Messages com Bedrock ou Vertex.

Chamada de ferramentas não funciona no llama.cpp

Verifique novamente as flags do servidor. llama-server documenta que o uso de ferramentas requer a flag –jinja. Sem ela, o servidor pode responder, mas o loop do agente degradará.

Prompts de permissão estão interrompendo cada comando

Isso pode ser normal, dependendo do modo e das regras de permissão. As opções incluem:

  • Alternar para acceptEdits temporariamente (edições de arquivo fluem mais rápido).
  • Escrever regras de permissão explícitas para comandos bash conhecidos como seguros em settings.json.
  • Usar /sandbox para isolar a ferramenta bash enquanto reduz prompts.
  • Avaliar o modo auto se seu plano e versão o suportarem, como um meio-termo.

Algo parece estranho e você precisa de observabilidade

Use os embutidos:

  • /doctor para validar instalação e configurações.
  • /debug para começar a capturar logs a partir desse ponto.
  • Se você estiver no modo de impressão, considere um orçamento máximo apertado e um máximo de turnos para manter experimentos limitados.