Instalar o Claude Code: Windows, macOS e Linux, chave de API sem assinatura e pagamento por Bancontact

Para instalar o Claude Code, basta uma linha, mas ela não é igual em todos os lugares: curl -fsSL https://claude.ai/install.sh | bash no terminal do macOS, Linux ou WSL, irm https://claude.ai/install.ps1 | iex no PowerShell e uma linha install.cmd no prompt de comando do Windows. A verdadeira questão surge na primeira inicialização: quem paga pelas solicitações? Uma conta Pro, Max, Team, Enterprise ou Console permite fazer login (o plano gratuito do Claude.ai não inclui o Claude Code). Sem assinatura, uma chave de API é suficiente: seis variáveis, incluindo ANTHROPIC_BASE_URL sem /v1 e ANTHROPIC_AUTH_TOKEN, e depois uma rápida verificação em /status. O saldo da Kunavo pode ser pago com cartão, Apple Pay, Google Pay, Link ou, na Bélgica, Bancontact, a partir de $10, sem assinatura.

D’où viennent les informations : les commandes et les variables sont reprises de la documentation officielle de Claude Code (instalação, variáveis de ambiente, conexão com um gateway), relue le 3 de outubro de 2026 ; les prix Kunavo et les moyens de paiement ont été contrôlés le 3 de outubro de 2026. D’après la lista de países compatíveis com a Anthropic (lue le 3 de outubro de 2026), Claude.ai et l’API sont ouverts en France, en Belgique, en Suisse, au Luxembourg et au Canada, comme au Maroc, en Tunisie, en Algérie, au Sénégal et en Côte d’Ivoire. Le même guide existe em inglês et, pour la Flandre, em holandês.

Qual comando digitar: tudo depende da janela

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

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

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

As três primeiras linhas instalam a versão nativa, recomendada pela Anthropic: um binário autônomo armazenado em ~/.local/bin (%USERPROFILE%\.local\bin no Windows), que baixa suas atualizações em segundo plano e as aplica na próxima inicialização. Quando a instalação terminar, feche o terminal e abra outro: aquele usado para instalar ainda não conhece o novo PATH.

No Windows, escolher a janela errada é a principal causa de falha, e a mensagem deixa isso claro. The token '&&' is not a valid statement separator: você colou a linha do CMD no PowerShell. 'irm' is not recognized as an internal or external command: o contrário. Em um Windows em francês, essa segunda mensagem pode aparecer traduzida; a causa não muda. As outras mensagens estão na tabela de erros, no fim do guia.

Requisitos

Windows: o que dizem os tutoriais antigos e o que é verdade

Une bonne partie des tutoriels en français datent des premières versions de Claude Code. Voici leurs consignes les plus répandues, confrontées à la documentação de instalação atual et à la página de solução de problemas (lues le 3 de outubro de 2026) :

Si vous installez Git for Windows, Claude Code passe par Git Bash et garde l’outil PowerShell à côté. Il arrive qu’il ne trouve pas bash.exe : indiquez alors son chemin dans la variable CLAUDE_CODE_GIT_BASH_PATH, au sein du bloc env de ~/.claude/settings.json (la documentation donne C:\Program Files\Git\bin\bash.exe en exemple). Dernier piège : le raccourci « Windows PowerShell (x86) » lance une version 32 bits, que Claude Code refuse.

Nativo ou WSL: a escolha depende de onde seus projetos estão localizados:

No WSL, tudo acontece dentro da distribuição Linux: é lá que você cola a linha curl … | bash e depois digita claude. Se for iniciado pelo PowerShell ou CMD, ele não encontrará essa instalação.

Homebrew, WinGet, apt ou npm

Os gerenciadores de pacotes funcionam, com uma ressalva: o Claude Code não é atualizado automaticamente por eles. No Homebrew e no WinGet, a variável CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 faz o Claude Code iniciar a própria atualização; sem ela, você terá de fazê-lo manualmente:

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # pas de mise à jour automatique

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # pas de mise à jour automatique

Sur Debian, Ubuntu, Fedora, RHEL et Alpine, Anthropic publie aussi des dépôts apt, dnf et apk signés, mis à jour avec le reste du système ; la procédure figure sur la página de instalação.

Resta o npm, prático se o Node.js já fizer parte das suas ferramentas. O pacote exige no mínimo o Node.js 22. Em uma versão mais antiga, o npm apenas exibe um aviso EBADENGINE e conclui a instalação, pois o pacote instala o mesmo binário nativo, que não precisa do Node.js para funcionar. Duas regras: não use sudo npm install -g e atualize com @latest, pois npm update -g permanece na faixa de versões original e pode deixar você desatualizado.

node -v                                       # v22 ou plus récent
npm install -g @anthropic-ai/claude-code      # jamais avec sudo

# mise à jour : avec @latest, pas avec npm update -g
npm install -g @anthropic-ai/claude-code@latest

Verificar a instalação e corrigir o PATH

claude --version   # affiche le numéro de version, suivi de (Claude Code)
claude doctor      # diagnostic de l’installation et des réglages, sans ouvrir de session

Um número de versão retornado significa que está instalado. claude doctor vai além sem iniciar uma sessão: verifica o estado da instalação, erros nos arquivos de configuração e o resultado da última atualização. Quando algo dá errado, este é o primeiro comando a executar.

command not found: claude sur macOS ou Linux, claude « non reconnu » sous Windows : le programme est bien installé, mais le shell ne sait pas où le chercher. Une nouvelle fenêtre suffit le plus souvent. Sinon, ajoutez ~/.local/bin au PATH dans ~/.zshrc ou ~/.bashrc. Sous Windows, la página oficial de solução de problemas donne ces trois étapes PowerShell :

# 1. Le dossier d'installation est-il déjà dans le PATH ?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Aucun résultat ? Ajoutez-le au PATH de l'utilisateur, puis ouvrez une nouvelle fenêtre
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Dans la nouvelle fenêtre : deux chemins = deux installations concurrentes
where.exe claude

Instalou via npm e o PowerShell responde npm.ps1 cannot be loaded? A política de execução bloqueia os scripts do npm. Mude para o instalador nativo ou autorize scripts locais apenas para sua conta:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Quem paga pelas solicitações: assinatura do Claude ou chave de API

A escolha não é feita durante a instalação, mas na primeira inicialização, e pode ser revertida. Uma chave definida no ambiente tem precedência sobre uma conexão claude.ai salva, que permanece inativa; remova a variável e a conexão voltará a ter precedência na próxima inicialização.

Com uma assinatura do Claude

Nada para configurar: claude na pasta do projeto e, depois, login no navegador. A única exceção é uma ANTHROPIC_API_KEY que esteja presente no seu ambiente. Nesse caso, o Claude Code pergunta uma vez se deve usá-la; uma recusa é memorizada, e a chave passa a ser ignorada sem mensagem, dando a impressão de que a variável não é lida. Para alterar essa escolha: /config → Use custom API key.

Sem assinatura: a chave de API da Kunavo

Faire pointer Claude Code ailleurs que chez Anthropic n’a rien d’un bricolage. La lista oficial de variáveis de ambiente présente ANTHROPIC_BASE_URL comme le moyen d’envoyer les requêtes vers un proxy ou une passerelle. Kunavo répond au format de l’API Messages d’Anthropic : vous gardez le Claude Code officiel, sans extension ni version modifiée.

1. Abra uma conta: cadastro na Kunavo.
2. Adicione saldo em Billing, no mínimo $10 (formas de pagamento abaixo).
3. Gere uma chave em /app/keys. Ela começa com sk-kn- e só é exibida no momento da criação: copie-a imediatamente.
4. Preencha as seis variáveis abaixo.

Pourquoi épingler quatre modèles ? Les alias de Claude Code suivent les sorties d’Anthropic. D’après la documentação sobre a configuração dos modelos (lue le 3 de outubro de 2026), pour un compte API, le réglage par défaut et opus visent aujourd’hui Opus 5.5, et sonnet vise Sonnet 5.5, que Kunavo ne sert pas : sans ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la phase d’exécution d’opusplan et les sous-agents réglés sur sonnet tombent sur une 404. L’alias opus est épinglé sur Opus 5.5 (claude-opus-5-5), qui exige Claude Code v2.1.280 ou plus récent ; sur une version plus ancienne, lancez claude update. Un modèle tout juste sorti n’est pas non plus toujours disponible chez Kunavo le jour même. Avec des noms complets, chaque requête part vers un modèle servi, au prix que vous connaissez. La documentação sobre o protocolo dos gateways (lue le 3 de outubro de 2026) confirme le point sur les tâches de fond : avec Claude Haiku 4.5, elles coûtent peu.

Onde escrever as variáveis

A versão recomendada, a ser mesclada com o conteúdo existente do arquivo, se já houver um (adicione apenas o bloco env):

{
  "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"
  }
}

Os mesmos valores no shell, no macOS e no Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # le domaine seul, sans /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

Para um teste rápido em uma janela do PowerShell:

# Valable uniquement dans cette fenêtre PowerShell
$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

E, para a extensão do VS Code, nas configurações de usuário do editor (comando Preferences: Open User Settings (JSON)):

{
  "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" }
  ]
}

O aplicativo de desktop Claude é uma exceção: ele não lê ANTHROPIC_BASE_URL nem settings.json. Uma variável alterada no shell que continua sem efeito? Primeiro, procure a mesma variável em um settings.json, que tem prioridade.

Tarifs par million de tokens tirés du catalogue Kunavo, à côté du prix public d’Anthropic relevé sur claude.com/pricing (lu le 3 de outubro de 2026) :

Para mudar para Opus durante uma tarefa: /model opus durante a sessão (o alias fixado em claude-opus-5-5), ou claude --model claude-opus-5-5 na inicialização. O orçamento mensal conforme seu uso e o limite a partir do qual a assinatura se torna mais vantajosa estão calculados em o preço do Claude Code. A calculadora de custo em tokens do Claude faz o cálculo para os seus próprios volumes, e a página de preços lista todos os modelos.

Verifique com /status

O primeiro sinal, antes mesmo de /status: com ANTHROPIC_AUTH_TOKEN configurado, o Claude Code inicia sem uma tela de login. Se essa tela aparecer, nenhuma chave foi lida, geralmente porque ela está apenas nas configurações do projeto (.claude/settings.json ou .claude/settings.local.json). Em uma sessão interativa, este bloco env só é aplicado depois do assistente de primeira inicialização e da pergunta de confiança sobre a pasta. Mova a chave para o seu shell ou para ~/.claude/settings.json.

Une fois dans la session, /status s’ouvre sur l’onglet Status. Voici comment le lire, d’après la documentação sobre gateways (lue le 3 de outubro de 2026) :

Você já estava conectado com uma assinatura? Nesse caso, o Claude Code pode informar na inicialização que há duas fontes de autenticação ativas, em um aviso que termina com auth may not work as expected. A chave é usada para as solicitações; /logout remove a conexão antiga e faz o aviso desaparecer.

Para saber se um problema vem do Kunavo ou da sua configuração, teste sem o Claude Code. A documentação propõe uma solicitação limitada a um único token de saída, que custa uma fração de centavo. Os dois comandos abaixo obtêm o endereço e a chave do shell: definidos apenas em settings.json, eles não seriam vistos aqui.

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": "."}]}'

Um JSON que começa com {"id":"msg_, ou, no PowerShell, um objeto cujo id começa com msg_: o endereço e a chave funcionam. Um 401: a chave foi recusada.

O que muda com uma chave de API

• Remote Control e a ditado por voz desaparecem. Ambos dependem de uma conta do claude.ai e permanecem indisponíveis enquanto ANTHROPIC_AUTH_TOKEN estiver definida. O Remote Control também é desativado quando ANTHROPIC_BASE_URL indica um host diferente da Anthropic.
• O modo rápido (/fast) aparece desativado, pois a verificação exige uma conexão com o claude.ai ou uma chave da Anthropic, não apenas um token bearer.
• A busca de ferramentas MCP é desativada por padrão quando ANTHROPIC_BASE_URL aponta para fora da Anthropic.
• /context exibe estimativas. Kunavo ne propose pas /v1/messages/count_tokens, et dans ce cas Claude Code compte à partir du nombre de caractères (documentação sobre o protocolo dos gateways).

No restante (leitura e escrita de código, ferramentas, subagentes, servidores MCP, hooks e cache de prompt), nada muda. Os detalhes técnicos, em inglês, estão na documentação de integração do Claude Code.

Pagar a partir da França ou da Bélgica

Deux circuits à ne pas confondre. L’abonnement Claude acheté sur le web se règle uniquement par carte de crédit ou de débit (FAQ de cobrança da Anthropic, lue le 3 de outubro de 2026) ; souscrit dans l’app mobile, il passe par l’App Store ou Google Play. Les montants de claude.com/pricing sont hors taxes.

Le solde Kunavo, lui, se recharge sur une page de paiement Stripe. Le tarif est fixé en dollars américains, mais depuis la France ou la Belgique Stripe vous montre le montant en euros, à un taux garanti 24 heures qui intègre 2 à 4 % de frais de conversion à votre charge (documentação da Stripe sobre o Adaptive Pricing, lue le 3 de outubro de 2026). Vous pouvez payer en dollars pour éviter ces frais, mais votre banque applique alors son propre change, et Bancontact n’est proposé qu’en euros. Les moyens de paiement disponibles :

• Cartão CB francês? Selon la documentação da Stripe sobre Cartes Bancaires (lue le 3 de outubro de 2026), plus de 95 % des cartes CB sont co-badgées Visa ou Mastercard. Elles passent donc au checkout en tant que Visa ou Mastercard, et une simple carte de débit fait l’affaire.
• Bancontact est proposé aux acheteurs situés en Belgique. Stripe vous envoie sur le site ou l’app Bancontact pour valider, et le résultat est connu immédiatement (documentação da Stripe sobre Bancontact, lue le 3 de outubro de 2026).
• Pay by Bank, le paiement depuis votre banque en ligne, n’est pas proposé depuis la France ni la Belgique : le checkout ne l’affiche qu’aux acheteurs situés au Royaume-Uni, en Irlande et en Finlande. La documentação da Stripe sobre Pay by Bank (lue le 3 de outubro de 2026) le classe en préversion privée pour la France et ne mentionne pas la Belgique.
• A partir da Suíça ou do Canadá, o valor é exibido em francos suíços ou dólares canadenses, com cartão e Link, além de Apple Pay e Google Pay, que dependem de um cartão.

Não oferecidos: PayPal, débito direto SEPA, Klarna, reservado a compradores localizados nos Estados Unidos (pagar em dólares não é suficiente).

1. Cadastre-se no Kunavo; nenhum cartão é solicitado nesta etapa.
2. Em Billing, escolha o valor: no mínimo $10. Valores maiores dão direito a um bônus ($100 payés, $110 crédités ; $1 000 payés, $1 200 crédités ; $5 000 payés, $6 250 crédités).
3. Na página da Stripe, selecione o meio de pagamento; o valor em euros é exibido antes da confirmação. Com o Bancontact, confirme no aplicativo ou com o cartão.
4. Crie a chave em /app/keys e coloque-a em ANTHROPIC_AUTH_TOKEN.

O saldo é pré-pago: não há tarifa mensal, data de expiração, e uma solicitação que falha não é cobrada. A recarga automática exige um cartão salvo ou o Link. O Bancontact não oferece suporte a pagamentos recorrentes na Stripe, portanto cada recarga via Bancontact é iniciada manualmente. O Kunavo não emite fatura com IVA, seja francesa, belga ou de outro país; o histórico das recargas pode ser consultado em Billing. Por fim, esses meios de pagamento servem exclusivamente para o saldo da API do Kunavo e não pagam uma assinatura Claude Pro ou Max. Todas as outras opções, incluindo a App Store e o Google Play, são analisadas em pagar pelo Claude sem cartão bancário.

Erros comuns

Primeiros passos em um projeto

Em um repositório que o Claude Code está descobrindo, comece com /init: ele explora o código e redige um CLAUDE.md que registra os comandos de teste e as convenções identificadas. Revise esse arquivo e reduza-o, pois ele é recarregado em cada sessão. Para mudar de assunto, /clear começa uma conversa vazia; para continuar uma tarefa longa, /compact resume o histórico.

Os limites da chave de API

• Você paga conforme o consumo, não por um plano Claude Pro ou Max. Para várias horas de Claude Code por dia, todos os dias, a assinatura costuma ser mais vantajosa; para uso irregular, o pagamento por token é mais flexível, e os meses de pouco uso não custam nada. Números em o preço do Claude Code.
• Sem Remote Control nem ditado por voz enquanto a chave estiver ativa.
• A capacidade do Kunavo é compartilhada, sem cota reservada nem compromisso contratual; se precisar disso, contrate diretamente com a Anthropic.
• O Bancontact permite apenas recargas manuais; a automática usa um cartão salvo ou o Link.
• Os valores em euros incluem as taxas de conversão da Stripe, e o Kunavo não emite fatura com IVA.

Perguntas frequentes