Instalar o Claude Code: comandos para Windows, macOS e Linux, chave de API sem assinatura e pagamento com iDEAL

Você instala o Claude Code com um único comando oficial: no macOS, Linux e WSL com curl -fsSL https://claude.ai/install.sh | bash, no Windows no PowerShell com irm https://claude.ai/install.ps1 | iex (no Prompt de Comando, CMD, usando a linha install.cmd abaixo). Depois, escolha como pagar. Faça login com uma conta Pro, Max, Team, Enterprise ou Console (a assinatura gratuita do Claude.ai não inclui o Claude Code) ou, sem assinatura, use uma chave de API: defina ANTHROPIC_BASE_URL (apenas o domínio, sem /v1), ANTHROPIC_AUTH_TOKEN e quatro variáveis de modelo, e verifique com /status se a chave está ativa. Recarregue o saldo da Kunavo com iDEAL (Países Baixos) ou Bancontact (Bélgica), a partir de $10, sem cobrança mensal.

Commando’s en variabelen gecontroleerd op 3 de outubro de 2026 in de documentação oficial de instalação do Claude Code en de documentação sobre variáveis de ambiente; prijzen en betaalmethoden gecontroleerd op 3 de outubro de 2026. Nederland en België staan allebei op de lista de países com suporte da Anthropic (gecontroleerd op 3 de outubro de 2026), zowel voor Claude.ai als voor de API. Deze handleiding bestaat ook in het Engels: Instalar o Claude Code.

Antes de instalar

Instalar o Claude Code no macOS e Linux

Abra o Terminal e cole esta linha:

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

Esta é a instalação nativa recomendada: um único programa independente que se atualiza em segundo plano. O comando claude é instalado em ~/.local/bin. Um terminal que já estava aberto ainda não conhece o novo PATH, portanto abra uma nova janela antes de testar. No WSL, use exatamente a mesma linha no terminal do WSL.

Instalar o Claude Code no Windows

No Windows, há duas linhas, e a necessária depende apenas da janela que você abriu. Se o prompt começar com PS C:\Users\Naam>, você está no PowerShell; se mostrar apenas C:\Users\Naam> sem PS, é o Prompt de Comando (CMD). Você não precisa abrir a janela como administrador: de acordo com a documentação oficial, isso não é necessário.

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

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

O erro mais comum é colar a linha na janela errada. A linha do CMD no PowerShell retorna The token '&&' is not a valid statement separator; a linha do PowerShell no CMD retorna 'irm' is not recognized as an internal or external command. Em um Windows em neerlandês, essa segunda mensagem pode aparecer em neerlandês, com a mesma causa. E a linha do macOS com | bash no PowerShell retorna uma mensagem de erro informando que bash não é reconhecido. Em todos os três casos, use a linha correspondente à sua janela.

Git for Windows is optioneel. Staat het erop, dan voert Claude Code commando’s uit via de meegeleverde Git Bash; zonder Git gebruikt het PowerShell. Is Git wel geïnstalleerd maar wordt Git Bash niet gevonden, zet dan CLAUDE_CODE_GIT_BASH_PATH in het env-blok van ~/.claude/settings.json op het pad naar bash.exe; het voorbeeldpad in de documentatie is C:\Program Files\Git\bin\bash.exe.

Portanto, o WSL não é um requisito, como afirmam alguns guias antigos, mas uma opção. Se você escolher o WSL, execute a linha do macOS/Linux no terminal do WSL e inicie claude também lá, não no PowerShell ou CMD.

Via Homebrew, WinGet ou npm

Isso também é possível, com uma diferença importante: de acordo com a documentação oficial, as instalações pelo Homebrew e WinGet não se atualizam automaticamente. Nesse caso, faça a atualização manualmente:

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # bijwerken gebeurt niet vanzelf

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # bijwerken gebeurt niet vanzelf

O pacote npm exige Node.js 22 ou posterior, não Node.js 18 como ainda afirmam alguns guias antigos. Com uma versão mais antiga do Node.js, o npm apenas exibe um aviso EBADENGINE e continua a instalação normalmente: o pacote instala o mesmo programa nativo, que não precisa do Node.js para ser executado. Nunca use sudo npm install -g: isso causa problemas de permissão e é um risco de segurança. Atualize com @latest, não com npm update -g.

node -v                                           # moet v22 of hoger zijn
npm install -g @anthropic-ai/claude-code          # nooit met sudo

# later bijwerken: met @latest, niet met npm update -g
npm install -g @anthropic-ai/claude-code@latest

Verificar a instalação

claude --version   # toont het versienummer, gevolgd door (Claude Code)
claude doctor      # alleen-lezen diagnose van installatie en instellingen, start geen sessie

claude doctor não inicia uma sessão; ele mostra o estado da instalação e dos seus arquivos de configuração. Assim, você identifica rapidamente se o problema está na instalação ou na configuração.

Krijg je command not found: claude, of meldt Windows dat claude niet wordt herkend, dan staat de installatiemap niet in je PATH. Open eerst een nieuw terminalvenster. Helpt dat niet, zet dan op macOS en Linux ~/.local/bin in je PATH via ~/.zshrc of ~/.bashrc. Op Windows is de map %USERPROFILE%\.local\bin; volgens de solução de problemas oficial controleer en voeg je die zo toe in PowerShell:

# 1. Staat de installatiemap al in je PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Geen uitvoer? Voeg de map toe aan je gebruikers-PATH en open een nieuw venster
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. In het nieuwe venster: twee paden betekent twee installaties naast elkaar
where.exe claude

Se você instalar via npm e o PowerShell informar npm.ps1 cannot be loaded because running scripts is disabled on this system, a política de execução do PowerShell está bloqueando os scripts de inicialização do npm. Use o instalador nativo, execute npm.cmd e claude.cmd, ou permita scripts locais para o seu próprio usuário:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Primeira inicialização: assinatura ou chave de API

Na primeira inicialização, escolha como o Claude Code será pago. As duas opções são mutuamente exclusivas: se uma chave de API estiver configurada, um login salvo permanecerá sem uso; se você remover a variável, o Claude Code voltará a usar o login, sem precisar ser reinstalado.

Opção A: fazer login com sua assinatura

Inicie claude na pasta do projeto e faça login pelo navegador. Há uma armadilha: se ANTHROPIC_API_KEY já estiver configurado, o Claude Code perguntará uma vez se deve usar essa chave. Se você recusar, ele ignorará a chave depois sem perguntar novamente, fazendo parecer que a variável não foi lida. Ative-a novamente em /config → Use custom API key.

Opção B: sem assinatura, com uma chave de API

ANTHROPIC_BASE_URL é uma variável integrada do Claude Code. De acordo com a documentação oficial, ela substitui o endpoint da API para enviar solicitações por meio de um proxy ou gateway. Portanto, apontar o Claude Code para um endpoint com a Anthropic Messages API é uma configuração compatível, sem plug-in e sem versão personalizada. Etapas:

1. Crie uma conta na Kunavo.
2. Recarregue seu saldo em Billing, a partir de $10 (iDEAL e Bancontact são mencionados mais adiante).
3. Crie em /app/keys uma chave que comece com sk-kn-. Ela é exibida apenas uma vez, portanto salve-a imediatamente.
4. Defina as variáveis. No macOS e Linux, em ~/.zshrc ou ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # alleen het domein, zonder /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

No Windows, para testar primeiro em uma única janela do PowerShell:

# Geldt alleen voor dit PowerShell-venster
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Para uso permanente, o env-bloco das configurações do usuário é o melhor local: ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json). Os valores valem em todos os lugares onde o Claude Code é executado, inclusive para agentes em segundo plano. As variáveis do shell valem apenas para aquela janela do terminal: um editor aberto pelo Dock ou pelo menu Iniciar não as verá. Se já houver outras configurações no arquivo, adicione apenas o env-bloco:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Zet de sleutel nunca in de .claude/settings.json van een project: volgens de documentação oficial do gateway (gecontroleerd op 3 de outubro de 2026) wordt dat bestand gecommit en gedeeld met iedereen die de repository kloont. Let ook op de volgorde: zetten zowel je shell als een instellingenbestand dezelfde variabele, dan wint het instellingenbestand. Heeft een gewijzigde shellvariabele geen effect, kijk dan eerst in settings.json.

Cada linha tem sua própria armadilha:

• ANTHROPIC_BASE_URL contém apenas o domínio. O Claude Code adiciona /v1/messages por conta própria; com /v1 no final, a solicitação vai para /v1/v1/messages e você recebe um 404.
• Use ANTHROPIC_AUTH_TOKEN, não ANTHROPIC_API_KEY. De acordo com a documentação, ANTHROPIC_AUTH_TOKEN é enviado como cabeçalho Authorization com Bearer antes do valor e vale imediatamente. ANTHROPIC_API_KEY vai no cabeçalho x-api-key e, no modo interativo, precisa ser aprovado uma vez primeiro (consulte a opção A).
• Escreva exatamente o nome do modelo em ANTHROPIC_MODEL. A Kunavo reconhece apenas o nome exato e não traduz nomes antigos com uma data no final.
• Fixe também ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL. Volgens de documentação sobre configuração de modelos (gecontroleerd op 3 de outubro de 2026) wijzen de standaardinstelling en de alias opus voor API-gebruikers naar Opus 5.5 en de alias sonnet naar Sonnet 5.5, en schuiven die aliassen mee met nieuwe versies. Vastzetten doe je met de volledige modelnaam of met variabelen als ANTHROPIC_DEFAULT_OPUS_MODEL. Kunavo biedt Sonnet 5.5 nu niet aan, en een nieuw Opus-model staat er niet altijd meteen; een model dat er niet is, geeft een 404. Zonder ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 mislukken daardoor /model sonnet, de uitvoerfase van opusplan en subagents die op model: sonnet staan. De alias opus zet je vast op Opus 5.5 (claude-opus-5-5); daarvoor heb je Claude Code v2.1.280 of nieuwer nodig; een oudere versie werk je bij met claude update.
• ANTHROPIC_DEFAULT_HAIKU_MODEL também vale para tarefas em segundo plano. De acordo com a documentação, essa variável determina o alias haiku e o modelo para funções em segundo plano, como títulos de sessão. Com Claude Haiku 4.5, elas permanecem econômicas.

Se você usar a extensão do VS Code, defina as variáveis em claudeCode.environmentVariables, nas configurações do usuário do próprio VS Code (comando Preferences: Open User Settings (JSON)). A extensão já verifica as credenciais de login nesse local antes de iniciar; os valores de ~/.claude/settings.json chegam ao processo iniciado, mas não a essa verificação.

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.kunavo.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-kn-..." },
    { "name": "ANTHROPIC_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "claude-opus-5-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "claude-haiku-4-5" }
  ]
}

Prijzen per miljoen tokens, uit de Kunavo-catalogus; de lijstprijs van Anthropic komt van claude.com/pricing (gecontroleerd op 3 de outubro de 2026):

Durante uma sessão, alterne com /model claude-opus-5-5 ou comece diretamente com claude --model claude-opus-5-5. O custo aproximado mensal do Claude Code e quando uma assinatura é mais vantajosa estão em Claude Code pricing (em inglês); calcule seu próprio consumo com a calculadora de tokens do Claude. Todos os modelos e preços estão na página de preços.

Verificando com /status

Inicie claude. Com ANTHROPIC_AUTH_TOKEN configurado, você não verá uma tela de login: a variável entra em vigor imediatamente. Se ainda assim aparecer a tela de login, o Claude Code não leu uma chave. Nesse caso, defina-a em um local que o Claude Code leia antes do assistente de primeira inicialização: um export no seu shell ou o bloco env de ~/.claude/settings.json. Um bloco env em .claude/settings.json ou .claude/settings.local.json de um projeto só entra em vigor em uma sessão interativa após o assistente de primeira inicialização e a pergunta sobre confiar na pasta.

Typ in de sessie /status en kijk op het tabblad Status naar twee regels (bron: de documentação oficial do gateway, gecontroleerd op 3 de outubro de 2026):

• Anthropic base URL deve mostrar https://api.kunavo.com. Essa linha aparece somente quando há um endereço de gateway configurado; se ela não aparecer, ANTHROPIC_BASE_URL não alcançou a sessão.
• Auth token deve mencionar ANTHROPIC_AUTH_TOKEN. Se, em vez disso, você vir Login method com uma conta do claude.ai, a variável não foi lida e a sessão está usando sua assinatura.

Se você já havia feito login com uma assinatura, o Claude Code poderá avisar, ao iniciar, que há duas fontes de login ativas (a mensagem termina com auth may not work as expected). Nesse caso, as solicitações passam pela chave; use /logout para remover o login antigo.

Quer testar o endereço e a chave antes de abrir o Claude Code? Envie, conforme sugerido pela documentação, uma solicitação de um token de saída; isso consome uma quantidade muito pequena de crédito. Os comandos leem as variáveis do seu shell, então defina-as ali também se elas já estiverem em settings.json.

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Uma resposta JSON que começa com {"id":"msg_ significa que o endereço e a chave funcionam; no PowerShell, você verá um id que começa com msg_. Um 401 significa que a chave foi recusada.

O que funciona de outra forma com uma chave de API

• Sem Remote Control nem ditado por voz. Ambos exigem uma conta do claude.ai e não estão disponíveis enquanto ANTHROPIC_AUTH_TOKEN estiver ativo; além disso, o Remote Control permanece desativado enquanto ANTHROPIC_BASE_URL apontar para um endereço fora da Anthropic.
• /fast informa que o fast mode está desativado. Com apenas um bearer token, o Claude Code trata o fast mode como desativado, sem enviar a verificação.
• A pesquisa de ferramentas MCP fica desativada por padrão assim que ANTHROPIC_BASE_URL aponta para um endereço fora da Anthropic.
• Os números em /context são uma estimativa: Kunavo biedt /v1/messages/count_tokens nu niet aan. Volgens de documentação oficial de compatibilidade para gateways (gecontroleerd op 3 de outubro de 2026) valt Claude Code zonder dat endpoint terug op een schatting op basis van tekens, dus /context toont benaderde aantallen.

Código, ferramentas, subagentes, servidores MCP, hooks e prompt caching funcionam normalmente. Mais detalhes estão na documentação de integração do Claude Code (em inglês) e em Claude Code without a subscription (em inglês).

Pagar com iDEAL ou Bancontact

Een Claude-abonnement betaal je via de website alleen met een creditcard of debitcard (Artigo de ajuda do Claude sobre assinaturas pagas, gecontroleerd op 3 de outubro de 2026); de prijzen op claude.com/pricing zijn exclusief belasting.

Het Kunavo-tegoed waardeer je op via Stripe Checkout. De prijzen staan in Amerikaanse dollars; voor kopers in Nederland en België toont Stripe het bedrag in euro’s. Volgens de Documentação da Stripe sobre Adaptive Pricing (gecontroleerd op 3 de outubro de 2026) zit in die wisselkoers een omrekenopslag van 2–4% die de koper betaalt; wie in dollars betaalt (met een kaart, Apple Pay, Google Pay of Link), betaalt die opslag niet. iDEAL en Bancontact werken alleen in euro’s. Op de betaalpagina worden aangeboden:

• iDEAL, voor Nederland. De methode heet inmiddels iDEAL | Wero (Stripe vroeg om die naam in het eerste kwartaal van 2026 over te nemen), dus ook die naam kun je op de betaalpagina zien. Je wordt doorgestuurd naar de omgeving van je eigen bank en bevestigt daar (Stripe sobre iDEAL, gecontroleerd op 3 de outubro de 2026).
• Bancontact, voor België, met je Bancontact-kaart of de app (Stripe sobre Bancontact, gecontroleerd op 3 de outubro de 2026).
• Cartões (Visa, Mastercard), Apple Pay, Google Pay e Link.

Não oferecidos: PayPal, débito direto SEPA, Klarna (disponível apenas para compradores nos Estados Unidos), Tikkie, Riverty (antigo AfterPay) e uma transferência bancária comum.

1. Crie uma conta na Kunavo.
2. Em Billing, escolha um valor, mínimo de $10. Quem adiciona mais crédito de uma só vez recebe crédito adicional: bij $100 krijg je $110, bij $1.000 krijg je $1.200, bij $5.000 krijg je $6.250.
3. Na página de pagamento da Stripe, escolha iDEAL ou Bancontact e conclua o pagamento no ambiente do seu banco (iDEAL) ou com o aplicativo ou cartão Bancontact. O valor em euros aparece na página de pagamento antes da confirmação.
4. Crie uma chave em /app/keys e informe-a em ANTHROPIC_AUTH_TOKEN.

O crédito é pré-pago: não há cobrança mensal, o crédito não expira e solicitações malsucedidas não são cobradas. A recarga automática só pode ser feita com um cartão salvo ou Link; com iDEAL e Bancontact, você precisa recarregar manualmente todas as vezes. A Kunavo não emite faturas com IVA; seu histórico de recargas está em Billing. Esses métodos de pagamento adicionam crédito somente à sua API da Kunavo: não é possível pagar uma assinatura Claude Pro ou Max com eles. Saiba mais sobre pagar em euros: Pagar o Claude com iDEAL.

Erros comuns

Após a instalação

Na primeira vez que iniciar em um projeto, digite /init: o Claude Code lê o repositório e cria um CLAUDE.md com os comandos de teste e as convenções encontradas. Verifique esse arquivo e mantenha-o curto, pois ele é carregado em todas as sessões. Entre tarefas independentes, /clear inicia uma nova conversa; se uma tarefa ficar longa, /compact resume o histórico e você continua trabalhando.

O que você precisa saber

• Esta é uma API com cobrança por token, não uma assinatura Claude Pro ou Max. Quem usa o Claude Code por horas todos os dias geralmente economiza com uma assinatura; pagar por token é adequado para uso variável, e um mês sem uso não custa nada. A comparação está em Claude Code pricing (em inglês).
• Com uma chave de API, o Remote Control e o ditado por voz não estão disponíveis.
• Por meio da Kunavo, você usa capacidade compartilhada, sem cota reservada e sem garantias contratuais; se precisar disso, celebre um contrato diretamente com a Anthropic.
• iDEAL e Bancontact servem apenas para recargas manuais; a recarga automática só pode ser feita com cartão ou Link.
• Os valores em euros incluem a margem de conversão da Stripe. A Kunavo não emite faturas com IVA.

Perguntas frequentes