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

Codificação agentiva, agora com backends de modelos locais.

Conteúdo da página

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

Essa diferença é importante 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 claramente a distinção: 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 vários arquivos, executa alterações, roda testes e itera sobre falhas. Na prática, isso o torna mais parecido com um engenheiro júnior nativo do terminal que pode realizar tarefas rotineiras rapidamente, mas ainda precisa de revisão.

Essa tensão entre velocidade e supervisão é muito do que as pessoas agrupam sob o termo “vibe coding”; O que é Vibe Coding? desmonta o termo, sua origem e como a eficiência e o risco se apresentam na prática.

laptop-homeresver-claude-code-coffee-books

Um detalhe fácil de perder ao percorrer rapidamente a documentação: o CLI do Terminal (e a interface 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 é apontado 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 LLMs em 2026 alinha o 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 para ferramentas de desenvolvimento de IA reúne assistentes estilo Copilot, automação e padrões de editores em um só lugar.

Para uma análise detalhada de assistentes de codificação na mesma categoria, Comparação de Assistentes de Codificação de IA percorre o Cursor, Copilot, Cline e o restante em um nível mais alto do que este guia de instalação.

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

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 atualizam automaticamente.
  • 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 de dentro 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 (first-party). O fluxo de início rápido suporta logins via assinatura Claude (Pro, Max, Team, Enterprise), 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 centralizado de custos.

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 ao 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 é (da maior para a menor): política gerenciada, flags do CLI, local, projeto, usuário. Essa ordem explica vários momentos de “por que minha configuração é ignorada”.

Você pode gerenciar configurações interativamente via o comando /config, que abre uma interface 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. Duas peculiaridades de comportamento valem a pena ser tratadas 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 da primeira parte (um proxy, gateway ou servidor local), alguns recursos são intencionalmente conservadores. Por exemplo, a busca de ferramentas MCP é desativada por padrão, a menos que você a reative explicitamente.

Para o limite específico de assinatura agora aplicado em pilhas de agentes de terceiros, esta atualização de política da Anthropic para fluxos de trabalho OpenClaw explica por que o uso baseado em API é necessário.

Um padrão mínimo para “usar um gateway” parece com isto:

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, há 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 fixar IDs de modelo específicos. Há também uma lista de permissão 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, em seguida, fixar o que “padrão” resolve via env:

{
  "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 funcionar em modelos não-Anthropic, 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ê tiver o Ollama instalado e em execução, o caminho rápido é:

ollama launch claude

Ou especificar 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 uma configuração 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 de 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 agêntica é faminta por contexto. O Ollama deixa claro: o Claude Code requer uma grande janela de contexto e recomenda pelo menos 64k tokens. Se seu modelo local atingir um máximo de 8k ou 16k, o Claude Code ainda funcionará, mas a promessa de “nível de projeto” se tornará frágil.

Para 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 falha francas), Melhores LLMs para OpenCode - Testados Localmente é uma verificação cruzada útil quando você está selecionando tags GGUF ou Ollama para o Claude Code.

Executando LLMs auto-hospedados via llama.cpp

llama.cpp é atraente pela 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 compatível com a API Anthropic Messages.

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

O que executar no lado do servidor

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

Dois detalhes importam para o Claude Code:

  • O servidor explicitamente não faz afirmações fortes 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 tivesse esquecido repentinamente como ser um agente.

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

# Construa ou baixe o llama-server, então 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 rígida de autenticação, 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 seu Claude Code é principalmente uma sobrescrição de URL base:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export ANTHROPIC_API_KEY=my-local-key   # apenas se você habilitou --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 por assinatura, que é a fonte de muitas reclamações de “por que está abrindo um navegador”.

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

O llama-server expõe um endpoint de saúde simples que retorna “loading model” (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”.

Preço e modelo de custos

O preço do Claude Code é menos sobre “comprar um CLI” e mais sobre “qual via de faturamento sustenta os tokens”.

Planos de assinatura incluem Claude Code

A Anthropic inclui o Claude Code nas camadas de assinatura paga do Claude. Até abril de 2026, a lista de preços publicada mostra:

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

Preço por token de API

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

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

Controles de custo no CLI

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

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

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

Roteando o Claude Code para Ollama ou llama.cpp pode remover as faturas 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 o uptime”. Para algumas equipes, essa compensação é 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 um chatbot. As ferramentas sugerem isso.

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

O Claude Code é limitado por permissão por design. Os documentos descrevem um modelo em camadas: operações somente leitura, como leituras 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 a fricção. 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 prompting, enquanto ainda solicita aprovação para comandos com efeitos colaterais fora de sua lista segura.

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

Use comandos integrados para manter sessões honestas

Alguns comandos transformam o Claude Code de “assistente” para “ferramental”:

  • /init gera um guia de projeto CLAUDE.md, que é uma maneira leve de alimentar contexto consistente. Para playbooks reutilizáveis e fluxos de trabalho repetíveis que ficam acima do CLAUDE.md, Habilidades Claude para desenvolvedores cobre layout SKILL.md, compatibilidade de IDE, ajuste de gatilho e teste.
  • /diff dá uma visão interativa das alterações, incluindo diffs por turno.
  • /rewind permite retroceder a conversa e/ou código para um ponto anterior, usando checkpoints.
  • /debug habilita logs de depuração em meio à sessão.
  • /doctor diagnostica e verifica sua instalação e configurações.

Estes não são truques; eles 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 únicas (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.

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

Isso geralmente significa que o Claude Code ainda está tentando usar 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 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 dá erro nos cabeçalhos anthropic-beta

Alguns gateways rejeitam cabeçalhos desconhecidos ou campos beta. Há uma variável de ambiente projetada para este modo exato de falha:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

A documentação do gateway LLM também nota 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. O llama-server documenta que o uso de ferramentas requer a flag –jinja. Sem ela, o servidor pode responder, mas o loop do agente se 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:

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

Algo parece estranho e você precisa de observabilidade

Use os integrados:

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

A posição do Claude Code como ferramenta protegida de primeira parte da Anthropic tornou-se estrategicamente significativa em abril de 2026, quando a Anthropic bloqueou o acesso de assinatura do Claude para frameworks de agentes de terceiros, mantendo o Claude Code no faturamento por assinatura. A Cronologia de ascensão e queda do OpenClaw cobre esse evento e o que ele revela sobre a abordagem da Anthropic em relação a ferramentas de primeira versus terceira parte.

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.