Instalar o Claude Code no Windows, Mac e Linux: chave de API sem assinatura e pagamento com Satispay

Para instalar o Claude Code basta um comando, diferente conforme o terminal: a linha com install.sh no macOS, Linux e WSL, irm … | iex no PowerShell e a linha com install.cmd no Prompt de Comando. É o método recomendado pela Anthropic; o npm continua sendo possível, mas exige Node.js 22 ou posterior. O plano gratuito do Claude não inclui o Claude Code, portanto é necessária uma assinatura Pro ou superior, ou uma chave de API. Aqui, siga o segundo caminho: ANTHROPIC_BASE_URL=https://api.kunavo.com (sem /v1), a chave em ANTHROPIC_AUTH_TOKEN, quatro variáveis que fixam os modelos e /status para a verificação final. O crédito é recarregado com Satispay em euros a partir de $10 e você paga apenas pelos tokens consumidos.

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

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

:: Windows – Prompt dei comandi (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Da dove vengono questi comandi: la documentazione di Claude Code esiste anche in italiano e l'abbiamo riletta il 3 de outubro de 2026, in particolare le pagine su instalação e gateway de LLM. Prezzi e metodi di pagamento di Kunavo sono aggiornati al 3 de outubro de 2026. Anthropic serve l'Italia sia su Claude.ai sia con l'API (países compatíveis, letto il 3 de outubro de 2026).

O que é necessário

I requisiti della documentação oficial (letta il 3 de outubro de 2026) sono bassi:

• macOS 13.0 ou posterior; Windows 10 1809 ou posterior, ou Windows Server 2019 ou posterior; Ubuntu 20.04+, Debian 10+ ou Alpine Linux 3.19+.
• Pelo menos 4 GB de RAM e um processador x64 ou ARM64. O Windows de 32 bits não é compatível.
• Um shell entre Bash, Zsh, PowerShell e CMD.
• Uma conexão a partir de um país compatível com a Anthropic: a Itália é compatível.
• Node.js apenas se você escolher npm e, nesse caso, a partir da versão 22.

Qual comando, em qual terminal

Não são necessários direitos de administrador nem WSL: a documentação oficial afirma isso explicitamente, embora mais de um guia disponível sugira o contrário. Depois de instalado, o Claude Code é atualizado automaticamente em segundo plano. Quem prefere um gerenciador de pacotes pode usar Homebrew ou WinGet, sabendo que, nesse caso, ele mesmo inicia as atualizações:

# Homebrew – canale stable; non si aggiorna da solo
brew install --cask claude-code

# WinGet (Windows) – non si aggiorna da solo
winget install Anthropic.ClaudeCode

Antes de tentar, feche o terminal e abra um novo: somente uma janela nova relê o PATH. Depois, verifique. claude doctor também será útil mais adiante, pois verifica a instalação e as configurações sem abrir uma sessão e informa imediatamente se o problema está em uma ou nas outras.

claude --version   # stampa la versione, ad esempio 2.1.284 (Claude Code)
claude doctor      # diagnostica di installazione e impostazioni, senza aprire una sessione

Download bloqueado: 403 ou página HTML no lugar do script

Quando lo script non arriva, il terminale non lo dice in modo chiaro: bash si lamenta con syntax error near unexpected token '<' (sta cercando di eseguire una pagina web), oppure curl si ferma su curl: (22) The requested URL returned error: 403. La página oficial sobre problemas de instalação (in inglese, letta il 3 de outubro de 2026) distingue due casi. Se la pagina scaricata dice App unavailable in region, il server crede che ti colleghi da un paese escluso: dall'Italia capita quasi sempre per una VPN o un proxy che esce all'estero. Un 403 senza testo arriva più spesso da un proxy aziendale o da un firewall. Cambiare metodo di installazione non aiuta, perché Homebrew e WinGet scaricano dagli stessi server: prova da un'altra rete oppure chiedi all'IT di sbloccare quei domini.

Com npm: Node.js 22, não 18

Se Node.js lo usi già tutti i giorni, npm sembra la scelta naturale. Funziona ed è tra i metodi documentati, con una condizione che molte guide in italiano non hanno aggiornato: ci vuole Node.js 22 o successivo. Con un Node più vecchio vedrai l'avviso EBADENGINE, però l'installazione arriva in fondo e claude parte lo stesso (documentação oficial, letta il 3 de outubro de 2026). Le versioni aggiornate di Node sono su nodejs.org.

node -v                                    # serve v22 o successiva
npm install -g @anthropic-ai/claude-code   # senza sudo

# aggiornamento: @latest, non npm update -g
npm install -g @anthropic-ai/claude-code@latest

Três hábitos a evitar:

• sudo antes de npm install -g. A documentação desaconselha isso, tanto pelos conflitos de permissões quanto pela segurança.
• npm update -g para atualizar. Em vez disso, repita a instalação com @latest, como na última linha acima.
• Ignorar as dependências opcionais. Il binario di Claude Code arriva proprio come dipendenza facoltativa, un pacchetto @anthropic-ai/claude-code-* per ogni piattaforma. Con --omit=optional, o con optional=false nel file .npmrc, non viene scaricato e su macOS o Linux claude risponde claude native binary not installed (problemas de instalação, in inglese, letta il 3 de outubro de 2026).

Claude Code no Windows: onde surgem os problemas

Su Windows Claude Code gira in modo nativo, e l'installazione in sé è la parte facile. I problemi nascono dall'ambiente. Il primo è il terminale: se incolli in PowerShell la riga per CMD, PowerShell protesta per il &&; se incolli in CMD la riga per PowerShell, CMD non sa cosa sia irm; e la riga curl … | bash del Mac in PowerShell non funziona proprio. Su un Windows in italiano alcuni di questi messaggi possono comparire tradotti. In ogni caso la soluzione è tornare alla tabella qui sopra e prendere la riga del terminale che hai davanti (i messaggi in inglese sono nella tabella degli errori in fondo; fonte: documentação, letta il 3 de outubro de 2026).

Preste atenção também ao menu Iniciar: “Windows PowerShell (x86)” abre um processo de 32 bits e o Claude Code para com Claude Code does not support 32-bit Windows, mesmo que o PC seja de 64 bits. Escolha a opção sem (x86).

Git for Windows non è obbligatorio. Se è installato, Claude Code esegue i comandi attraverso Git Bash; se manca, usa PowerShell. Quando Git c'è ma Claude Code non trova bash.exe, indicagli il percorso con CLAUDE_CODE_GIT_BASH_PATH nel blocco env di ~/.claude/settings.json, di solito C:\Program Files\Git\bin\bash.exe. E WSL? Serve solo in un caso preciso:

Com o WSL, tudo acontece dentro do Linux: a linha install.sh deve ser executada no shell do WSL e, de lá, você executa claude.

“claude” não foi encontrado

Se, após a instalação, o terminal responder command not found: claude ou 'claude' is not recognized, o programa existe, mas a pasta dele não está no PATH. O instalador nativo o copia para ~/.local/bin/claude no macOS e Linux e para %USERPROFILE%\.local\bin\claude.exe no Windows. Primeira tentativa: um terminal novo. Se isso não bastar no Windows, estes são os comandos PowerShell da documentação para verificar e adicionar a pasta ao PATH do usuário:

# 1. Controlla se la cartella di installazione è già nel PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Nessun risultato? Aggiungila al PATH utente, poi chiudi e riapri il terminale
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Nel nuovo terminale
claude --version

npm.ps1 cannot be loaded no PowerShell

Isso se aplica apenas a quem instala com npm: as políticas de execução (execution policy) do PowerShell bloqueiam o script .ps1 criado pelo npm, e a mensagem completa contém running scripts is disabled on this system. A documentação indica três saídas: permitir que o usuário atual execute scripts locais com o comando abaixo, executar npm.cmd e claude.cmd no lugar dos scripts do PowerShell ou abandonar o npm e usar o instalador nativo.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Sem assinatura: conta Claude ou chave de API

Installato non vuol dire pronto: al primo avvio Claude Code chiede di autenticarsi, e il piano gratuito di Claude.ai non basta (documentação, letta il 3 de outubro de 2026). Le due strade a confronto:

Esiste anche la chiave della Console di Anthropic, sempre a consumo. Lì però i crediti prepagati scadono dopo un anno e non si rimborsano (suporte da Anthropic, letto il 3 de outubro de 2026); si paga con carta, mentre il bonifico ACH è riservato agli account API con fatturazione mensile (suporte da Anthropic). Il credito Kunavo non ha scadenza.

Configurar a chave de API: seis variáveis

Che Claude Code parli con un endpoint diverso da quello di Anthropic è previsto: la documentazione ufficiale ha una pagina, tradotta anche in italiano, su come conectá-lo a um gateway de LLM. Nessun plugin, nessuna versione modificata. Bastano queste variabili:

No macOS e Linux, adicione-as ao final de ~/.zshrc ou ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # solo il dominio, senza /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 um teste rápido que dura o mesmo que a janela do PowerShell:

# Vale solo in questa finestra di PowerShell: chiusa la finestra, sparisce
$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 não precisar redefini-las todas as vezes, o local correto é o bloco env de ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json): ele vale para todos os seus projetos. Se o arquivo já contiver outras configurações, adicione apenas 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"
  }
}

AUTH_TOKEN ou API_KEY?

Kunavo legge la chiave da tutti e due gli header, Authorization: Bearer e x-api-key, quindi in teoria vanno bene entrambe le variabili. La differenza la fa Claude Code. Con ANTHROPIC_API_KEY, inviata come x-api-key, la sessione interattiva ti chiede una volta se approvare la chiave; se rispondi no, la ignora senza dire nulla finché non la riattivi da /config → Usar chave de API personalizada. ANTHROPIC_AUTH_TOKEN non chiede niente, ed è anche la variabile che la documentação sobre gateways (letta il 3 de outubro de 2026) suggerisce quando non sai quale scegliere.

Por que fixar os modelos

Senza variabili Claude Code ragiona per alias, e gli alias seguono le uscite di Anthropic. Oggi, secondo la documentação sobre a configuração dos modelos (letta il 3 de outubro de 2026), per chi usa l'API opus corrisponde a Opus 5.5 e sonnet a Sonnet 5.5. Kunavo, al 3 de outubro de 2026, non offre Sonnet 5.5: senza ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la fase esecutiva di opusplan e i subagent con model: sonnet chiederebbero un modello che su Kunavo non c'è e tornerebbero 404. Con claude-sonnet-5 in quella variabile l'alias punta a Claude Sonnet 5, lo stesso modello di ANTHROPIC_MODEL. Quest'ultima decide invece il modello della sessione: senza, Claude Code partirebbe dal suo predefinito, oggi Opus 5.5. Opus 5.5 è disponibile, e fissare opus su claude-opus-5-5 serve a un'altra cosa: evitare che modello e tariffa cambino da un giorno all'altro quando l'alias passerà a un Opus successivo. Claude Opus 5.5 richiede Claude Code 2.1.280 o successivo; con una versione più vecchia, lancia prima claude update.

As tarifas do Kunavo para os três modelos da configuração, por milhão de tokens (entrada / saída): Claude Sonnet 5 $1,40 / $7,00 (tabela de preços da Anthropic: $2,00 / $10,00); Claude Opus 5.5 $2,80 / $14,00; Claude Haiku 4.5 $0,70 / $3,50, que também trabalha nos bastidores.

Onde não colocá-la e qual configuração prevalece

Il .claude/settings.json dentro il progetto viene committato: una chiave scritta lì finisce nel repository e arriva a chiunque lo cloni (documentação sobre gateways). Se una variabile compare sia nella shell sia nel blocco env di un file di impostazioni, prevale il file: quando una modifica a ~/.zshrc sembra ignorata, il motivo è quasi sempre lì. Il campo model del file di impostazioni, invece, cede il passo ad ANTHROPIC_MODEL. Nell'estensione di Claude Code per VS Code le stesse variabili vanno in claudeCode.environmentVariables, nelle impostazioni utente di VS Code. L'app desktop di Claude resta fuori da tutto questo: non legge né ANTHROPIC_BASE_URL né settings.json (documentação sobre gateways, letta il 3 de outubro de 2026).

Primeira inicialização e verificação com /status

Se la chiave è al suo posto, claude parte sem tela de login: restano solo la configurazione iniziale e la domanda se ti fidi della cartella. Se invece compare il login, Claude Code non ha trovato la chiave. Il caso tipico è la chiave scritta solo nel .claude/settings.json o nel .claude/settings.local.json del progetto: in modalità interattiva quel blocco env entra in gioco solo dopo la configurazione iniziale e la conferma di fiducia (documentação sobre gateways, letta il 3 de outubro de 2026), quindi al primo avvio non c'è ancora. Spostala nella shell o nel file utente. Un vecchio login Pro o Max non dà fastidio, perché la variabile ha la precedenza sull'accesso salvato; se vuoi cancellarlo, c'è /logout.

Dentro da sessão, digite /status. As duas linhas importantes são:

• Anthropic base URL, que aparece apenas quando um gateway está configurado: deve indicar https://api.kunavo.com. Se não aparecer, ANTHROPIC_BASE_URL não chegou à sessão.
• Auth token com o nome ANTHROPIC_AUTH_TOKEN: você está usando a chave. Se, no lugar disso, encontrar Login method com uma conta claude.ai, a variável foi ignorada.

Quer verificar antes mesmo de abrir o Claude Code? A documentação propõe uma solicitação mínima, com 1 token de saída, que desconta do crédito um valor irrisório. O comando lê as variáveis do shell atual: se a chave estiver apenas em settings.json, exporte-a primeiro neste terminal. Se retornar um JSON que começa com {"id":"msg_, está tudo certo; 401 significa que a chave foi rejeitada.

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

No PowerShell, o mesmo teste é este, e a resposta correta contém um id que começa com msg_:

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

O que você perde com a chave de API

• Remote Control e digitação por voz. Eles exigem uma identidade claude.ai e não funcionam com ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY; a partir da versão 2.1.196, o Remote Control também é desativado quando ANTHROPIC_BASE_URL aponta para um host que não pertence à Anthropic.
• O modo /fast. Com apenas o token bearer, o Claude Code o considera desativado e nem tenta solicitá-lo.
• A pesquisa de ferramentas MCP, no início. Con un ANTHROPIC_BASE_URL personalizzato parte spenta (documentação do MCP, in inglese, letta il 3 de outubro de 2026). Si riaccende con ENABLE_TOOL_SEARCH=true se il gateway inoltra i blocchi tool_reference; con Kunavo non l'abbiamo provato.
• A precisão de /context. Kunavo non espone /v1/messages/count_tokens, un endpoint facoltativo secondo la especificação dos gateways (letta il 3 de outubro de 2026); senza, Claude Code stima i token a partire dai caratteri.

Para saber mais, em inglês: a documentação da integração com o Claude Code, a página sobre casos-limite de ANTHROPIC_BASE_URL e o guia Install Claude Code.

Pagar com Satispay, sem cartão de crédito

Prima una precisazione, perché è la domanda più frequente: Satispay non paga l'abbonamento Claude. Per Pro e Max comprati sul web Anthropic accetta solo carte di credito o di debito (suporte da Anthropic) e non accetta PayPal (suporte da Anthropic), entrambi letti il 3 de outubro de 2026. Su Kunavo Satispay ricarica invece il credito API che Claude Code consuma con la chiave configurata sopra. Tutti i dettagli, compresi i costi per caricare la Disponibilità, sono nella guida pagar o Claude com Satispay. Per Claude Code la sequenza è questa:

1. Cadastre-se no Kunavo com seu e-mail ou com uma conta do Google: nenhum cartão é necessário.
2. Abra o Faturamento e escolha quanto recarregar: mínimo $10, sem taxa de assinatura. Acima de determinados limites há um bônus: $100 diventano $110, $1.000 diventano $1.200, $5.000 diventano $6.250 de crédito.
3. Nel checkout di Stripe, che mostra l'importo in euro, scegli Satispay. Si passa alla pagina di Satispay (documentação da Stripe): numero di cellulare o QR code dall'app, poi conferma con Enviar (suporte do Satispay, letto il 3 de outubro de 2026). Meglio avere già abbastanza Disponibilità prima di cominciare.
4. O crédito aparece em Faturamento assim que o Stripe confirma o pagamento. Se não aparecer imediatamente, atualize a página em vez de pagar novamente: um segundo pagamento é somado ao crédito, não substitui o primeiro.
5. Em Chaves de API, gere a chave sk-kn-… e copie-a imediatamente para ANTHROPIC_AUTH_TOKEN: ela é exibida uma única vez.

Kunavo fissa i prezzi in dollari e Stripe li converte in euro con una taxa de câmbio de 2–4% a carico di chi paga (Stripe, Adaptive Pricing, letto il 3 de outubro de 2026): sulla ricarica minima da $10 sono tra $0,20 e $0,40. In dollari la commissione sparisce, ma sparisce anche Satispay, che esiste solo nel checkout in euro; se il checkout ti appare in dollari, spesso c'entra una VPN. L'importo esatto in euro è quello che leggi nel checkout prima di confermare.

Con Satispay le ricariche si fanno a mano: la ricarica automatica di Kunavo addebita solo una carta salvata o Link. Chi ha la carta Satispay, una Mastercard di debito per i piani Plus, Metal e Velvet (suporte do Satispay, letto il 3 de outubro de 2026), può salvarla e usarla come qualsiasi carta. Il credito non scade e le richieste fallite non vengono addebitate. Kunavo non emette fatture, né con IVA né elettroniche via SDI; lo storico delle ricariche resta in Faturamento.

Uma observação honesta: o Satispay está no checkout do Kunavo desde 3 de outubro de 2026 e o Stripe o oferece nos pagamentos em euros, mas nenhuma recarga ainda passou por ele. Se você não o encontrar, cartão, Apple Pay, Google Pay e Link fazem o mesmo trabalho.

Quanto custa uma sessão de trabalho

Com a chave de API, o custo está nos tokens, e o Claude Code envia muitos deles: a cada etapa, reenvia todo o contexto. A parte que não muda, porém, pode ser lida do cache por uma tarifa muito menor. Veja um exemplo elaborado, com as hipóteses explícitas: não é uma medição nem um limite de gastos.

• 40.000 tokens de entrada por solicitação, dos quais 36.000 (90%) são lidos do cache e 4.000 são gravados no cache;
• 1.000 tokens de saída por solicitação;
• 50 solicitações em uma sessão, sem contar as chamadas a Claude Haiku 4.5 em segundo plano;
• leitura do cache a 10% da tarifa de entrada e gravação a 1,25× a tarifa de entrada: essas são as proporções do Kunavo para Claude Sonnet 5 e cada linha da tabela usa as do próprio modelo.

Contextos longos, poucas leituras do cache e respostas prolixas aumentam a conta; um /clear entre uma tarefa e outra a reduz. Se a assinatura ou a API é mais vantajosa para você, veja em quanto custa o Claude Code; as tarifas de todos os modelos Claude estão em preços da API do Claude e na página de preços. Para refazer a conta com seus números, use o calculador de custos de tokens do Claude (em inglês).

Erros: mensagem, causa, solução

O que esta configuração não faz

• Não ativa uma assinatura Claude Pro ou Max: o crédito da Kunavo paga a API e o Claude Code com chave, não o claude.ai nem o aplicativo Claude.
• Não emite faturas: nem com IVA nem eletrônicas via SDI.
• Não recarrega automaticamente com Satispay: a recarga automática exige um cartão salvo ou Link.
• Não funciona sem as variáveis dos modelos enquanto a Kunavo não oferecer o Sonnet 5.5 (situação em 3 de outubro de 2026): o alias sonnet retornaria 404, assim como /model sonnet, a fase de execução de opusplan e os subagentes com model: sonnet.
• Não há documentação da Kunavo em italiano: o guia de integração e a página sobre saldo e pagamentos estão em inglês, enquanto a documentação da Anthropic sobre o Claude Code está traduzida.

Para uma visão geral de quem desenvolve com Claude na Itália, consulte o guia da API do Claude na Itália. Por onde começar: crie a conta, recarregue $10 com Satispay, configure as seis variáveis e verifique com /status.

Perguntas frequentes