Como instalar o Claude Code no Windows, macOS e Linux — chave de API sem assinatura e pagamento com BLIK

O Claude Code é instalado com um único comando oficial (abaixo estão as versões para macOS e Linux, PowerShell e CMD). A Anthropic recomenda o instalador nativo, e o npm é uma alternativa que exige Node.js 22 ou superior. Sem uma assinatura Pro/Max e sem fazer login, basta definir ANTHROPIC_BASE_URL=https://api.kunavo.com (sem /v1), ANTHROPIC_AUTH_TOKEN com a chave de API e quatro variáveis que fixam os modelos. Assim, você paga apenas pelos tokens usados com o saldo, que pode recarregar com BLIK em zlotys, a partir de 10 USD. Por fim, digite /status no Claude Code para verificar se a chave funciona.

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

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

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

Polecenia i zmienne sprawdziliśmy 3 października 2026 w documentação oficial de instalação do Claude Code i w documentação das variáveis de ambiente. Polskiej wersji tej dokumentacji nie ma. Ceny i metody płatności sprawdziliśmy 3 października 2026. Polska jest na lista de países atendidos pela Anthropic (sprawdzone 3 października 2026), zarówno dla Claude.ai, jak i dla API.

Login ou chave de API?

Após a instalação, o Claude Code precisa se autenticar. Há dois caminhos, e este guia descreve o segundo em detalhes:

Antes de começar

Método 1: instalador nativo (recomendado)

Na documentação oficial, esse método tem a aba “Native Install (Recommended)”. Os comandos estão no início da página. No macOS, Linux e WSL, use a linha com install.sh. No Windows PowerShell, use irm … | iex; no prompt de comando CMD, use a linha com install.cmd. A instalação nativa é atualizada automaticamente em segundo plano. Também é possível instalar o Claude Code pelo Homebrew ou WinGet, mas, segundo a documentação, essas instalações não são atualizadas automaticamente por padrão; portanto, você as atualiza manualmente no gerenciador de pacotes:

# Homebrew – kanał stable; domyślnie nie aktualizuje się sam
brew install --cask claude-code

# WinGet (Windows) – domyślnie nie aktualizuje się sam
winget install Anthropic.ClaudeCode

Após a instalação, abra uma nova janela do terminal, pois uma janela aberta anteriormente não vê a variável PATH atualizada. Depois, verifique:

claude --version   # wypisuje numer wersji, np. 2.1.280 (Claude Code)
claude doctor      # diagnostyka instalacji i ustawień, bez otwierania sesji

claude doctor não abre uma sessão. Ele apenas exibe o estado da instalação e o diagnóstico dos arquivos de configurações. Assim, você distingue mais rapidamente um problema de instalação de um problema de configuração.

Quando o download falhar

Jeśli terminal pokazuje syntax error near unexpected token '<' albo curl: (22) The requested URL returned error: 403, to według página oficial sobre problemas de instalação (sprawdzone 3 października 2026) adres instalatora zwrócił stronę HTML lub kod błędu zamiast skryptu. Strona z napisem App unavailable in region oznacza według dokumentacji, że Claude Code nie jest dostępny w Twoim kraju. Polska jest jednak na liście obsługiwanych krajów, więc jeśli widzisz ten napis w Polsce, sprawdź, czy połączenie nie wychodzi przez VPN albo proxy. Samo 403 bez treści może też pochodzić z firmowego proxy lub zapory, która blokuje pobieranie. Dokumentacja radzi wtedy najpierw sprawdzić połączenie sieciowe, bo inne metody instalacji łączą się z tymi samymi serwerami. Spróbuj z innej sieci albo poproś administratora o odblokowanie tych adresów.

Método 2: npm (Node.js 22 ou superior)

npm nadal jest jedną z metod opisanych w oficjalnej dokumentacji. Pakiet wymaga Node.js 22 lub nowszego. Część polskich poradników wciąż podaje Node.js 18, co jest już nieaktualne. Na starszym Node.js npm wypisze ostrzeżenie EBADENGINE, ale nie przerwie instalacji, a claude będzie działać, bo pakiet pobiera natywny program, który nie korzysta z Node.js w czasie działania. Jeśli nie masz Node.js, zainstaluj wersję 22 lub nowszą ze site nodejs.org.

node -v                                    # potrzebna wersja v22 lub nowsza
npm install -g @anthropic-ai/claude-code   # bez sudo

# aktualizacja: @latest, a nie npm update -g
npm install -g @anthropic-ai/claude-code@latest

• Nunca use sudo npm install -g. A documentação alerta que isso causa problemas de permissões e representa um risco de segurança.
• Atualize por meio de @latest. Para atualizar, use npm install -g @anthropic-ai/claude-code@latest, não npm update -g.
• Não ignore as dependências opcionais. O programa correto é instalado como uma dependência opcional, ou seja, o pacote @anthropic-ai/claude-code-* para sua plataforma. Com a flag --omit=optional ou com optional=false em .npmrc, a instalação no macOS ou Linux terminará com a mensagem claude native binary not installed.

Claude Code no Windows: PowerShell, CMD, WSL e PATH

O Windows tem dois comandos de instalação diferentes, e a escolha depende apenas do terminal. Se a linha começar com PS C:\Users\TwojaNazwa>, você está trabalhando no PowerShell. Se você vir apenas C:\Users\TwojaNazwa>, sem PS, está no prompt de comando (CMD). De acordo com a documentação, não é necessário executar o terminal como administrador, embora alguns guias recomendem isso.

O erro mais comum é colar o comando no terminal errado. Colar a linha do CMD no PowerShell resulta em The token '&&' is not a valid statement separator. Colar a linha do PowerShell no CMD resulta em 'irm' is not recognized as an internal or external command. No Windows em polonês, a mesma mensagem é: “irm” não é reconhecido como um comando interno ou externo, programa executável ou arquivo em lote. Por outro lado, colar a linha curl … | bash do macOS no PowerShell termina com o erro A parameter cannot be found that matches parameter name 'fsSL' ou 'bash' is not recognized as the name of a cmdlet. Em todos esses casos, basta usar a linha destinada ao seu terminal.

No menu Iniciar há duas entradas: “Windows PowerShell” e “Windows PowerShell (x86)”. A segunda funciona como um processo de 32 bits, portanto, mesmo em um computador de 64 bits, termina com o erro Claude Code does not support 32-bit Windows. Abra a entrada sem o sufixo (x86).

Git for Windows jest opcjonalny, ale zalecany. Gdy jest zainstalowany, Claude Code wykonuje polecenia przez dołączony do niego Git Bash, a bez niego przez PowerShell. Jeśli Git jest zainstalowany, ale Claude Code nie znajduje Git Bash, ustaw w bloku env pliku ~/.claude/settings.json zmienną CLAUDE_CODE_GIT_BASH_PATH ze ścieżką do bash.exe. Przykładowa ścieżka z dokumentacji to C:\Program Files\Git\bin\bash.exe.

Se você escolher o WSL, execute a linha para macOS e Linux no terminal do WSL e inicie claude também ali, não no PowerShell nem no CMD.

Erro de política de execução de scripts (npm no PowerShell)

A mensagem npm.ps1 cannot be loaded because running scripts is disabled on this system durante a instalação ou execução pelo npm significa que as políticas de execução do PowerShell bloqueiam o script de inicialização .ps1 gerado pelo npm. De acordo com a documentação, você pode permitir que o usuário atual execute scripts locais (comando abaixo), usar npm.cmd e claude.cmd ou mudar para o instalador nativo do PowerShell.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

O comando “claude” não é reconhecido após a instalação

command not found: claude ou 'claude' is not recognized significa que o diretório de instalação não está em PATH. O instalador nativo coloca o programa em ~/.local/bin/claude no macOS e Linux e em %USERPROFILE%\.local\bin\claude.exe no Windows. Primeiro, abra um novo terminal. Se ainda não funcionar no Windows, verifique e adicione o caminho no PowerShell, conforme indicado na documentação:

# 1. Sprawdź, czy katalog instalacji jest już w PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Brak wyniku? Dopisz go do PATH użytkownika, zamknij i otwórz terminal
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. W nowym terminalu
claude --version

Chave de API em vez de login (sem assinatura)

ANTHROPIC_BASE_URL é uma variável integrada do Claude Code. Segundo a documentação oficial, ela substitui o endpoint da API para direcionar as solicitações por um proxy ou gateway. Portanto, conectar o Claude Code a um serviço compatível com a API Anthropic Messages é uma configuração prevista pela Anthropic. Você não precisa de plugins nem de um programa modificado. No macOS e Linux, adicione as variáveis ao arquivo de configuração do shell (~/.zshrc ou ~/.bashrc):

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # sama domena, bez /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, você pode primeiro verificar a configuração em uma janela do PowerShell:

# Działa tylko w tym oknie PowerShella – po zamknięciu znika
$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 manter a configuração, o melhor é inserir as variáveis no bloco env do arquivo de configurações do usuário ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json). Segundo a documentação, esse arquivo se aplica a todos os seus projetos. Se o arquivo já tiver outras configurações, 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"
  }
}

É fácil cometer um erro em qualquer uma dessas seis linhas:

• ANTHROPIC_BASE_URL é apenas o domínio. O Claude Code adiciona /v1/messages automaticamente. Com /v1 no final, a solicitação irá para /v1/v1/messages e retornará 404.
• ANTHROPIC_AUTH_TOKEN, não ANTHROPIC_API_KEY. O valor de ANTHROPIC_AUTH_TOKEN vai para o cabeçalho Authorization com o prefixo Bearer e funciona imediatamente. ANTHROPIC_API_KEY vai para o cabeçalho x-api-key e, no modo interativo, precisa ser aprovado uma vez. Se você recusar, a chave será ignorada silenciosamente. Você pode ativá-la novamente em /config → Use custom API key.
• ANTHROPIC_MODEL seleciona o modelo principal. Aqui, ele é Claude Sonnet 5 (claude-sonnet-5). O nome deve ser exatamente igual ao da lista de modelos da Kunavo. A Kunavo não reconhece nomes antigos com uma data no final.
• ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL fixam os aliases opus e sonnet. Według documentação oficial de configuração de modelos (sprawdzone 3 października 2026) dla użytkowników API model domyślny i alias opus wskazują Opus 5.5, a alias sonnet wskazuje Sonnet 5.5. Aliasy z czasem się zmieniają, a wersję przypina się pełną nazwą modelu albo zmiennymi takimi jak te dwie. Zapytanie o model, którego nie ma w Kunavo, zwraca 404. Alias opus przypinamy do Claude Opus 5.5 (claude-opus-5-5), bo kolejny Opus wydany przez Anthropic nie musi być od razu dostępny w Kunavo. Opus 5.5 wymaga Claude Code w wersji 2.1.280 lub nowszej, starszą wersję zaktualizujesz poleceniem claude update. Sonnet 5.5 nie jest obecnie (stan na 3 października 2026) dostępny w Kunavo, więc bez przypięcia aliasu sonnet do claude-sonnet-5 błąd 404 zwracają /model sonnet, faza wykonania w trybie opusplan i subagenci ustawieni na model: sonnet.
• ANTHROPIC_DEFAULT_HAIKU_MODEL também atende às tarefas em segundo plano. Segundo a documentação, essa variável seleciona o modelo para o alias haiku e para funções executadas em segundo plano. Na Kunavo, Claude Haiku 4.5 custa 0,70 USD por milhão de tokens de entrada e 3,50 USD por milhão de tokens de saída. O modelo principal Claude Sonnet 5 custa 1,40 USD / 7,00 USD (preços da Anthropic: 2,00 USD / 10,00 USD), e Claude Opus 5.5 custa 2,80 USD / 14,00 USD (entrada / saída, por milhão de tokens).

Klucza não wpisuj do projektowego .claude/settings.json. Według documentação de conexão do gateway ten plik trafia do repozytorium, a więc do każdego, kto je sklonuje. Pamiętaj też o kolejności pierwszeństwa. Gdy ta sama zmienna jest ustawiona i w powłoce, i w bloku env pliku ustawień, w większości sesji obowiązuje wartość z pliku ustawień. Osobna zasada dotyczy klucza model w pliku ustawień: zmienna ANTHROPIC_MODEL ma przed nim pierwszeństwo, a model działa tylko wtedy, gdy zmiennej nie ma. Jeśli zmiana w powłoce nie działa, najpierw sprawdź plik ustawień. W rozszerzeniu Claude Code dla VS Code zmienne ustawia się w claudeCode.environmentVariables, w ustawieniach użytkownika samego VS Code.

Primeira execução e /status

Segundo a documentação de conexão do gateway (verificado em 3 października 2026), com ANTHROPIC_AUTH_TOKEN definido, o comando claude abre imediatamente uma sessão sem tela de login. A variável funciona imediatamente e não precisa ser aprovada, como no caso de ANTHROPIC_API_KEY. Se, em vez disso, você vir a tela de login, o Claude Code não leu a chave.

A chave deve estar onde o Claude Code a lê antes da primeira configuração, ou seja, definida com o comando export no shell ou no bloco env do arquivo ~/.claude/settings.json do usuário. No modo interativo, o bloco env do .claude/settings.json ou .claude/settings.local.json do projeto só começa a funcionar após o assistente da primeira execução e a pergunta sobre confiar na pasta. Com a chave apenas nas configurações do projeto, você ainda verá a tela de login na primeira inicialização.

Na sessão, digite /status e verifique duas linhas:

• Anthropic base URL aparece apenas quando um endereço de gateway está definido. Ele deve mostrar https://api.kunavo.com. Se essa linha não aparecer, ANTHROPIC_BASE_URL não chegou à sessão.
• Auth token com o nome ANTHROPIC_AUTH_TOKEN indica que a chave de API está funcionando, e não o login salvo do claude.ai. Se você vir Login method com uma conta claude.ai, a variável não funcionou.

Você também pode verificar o endereço e a chave antes de iniciar o Claude Code, usando o método da documentação oficial. Ele envia uma solicitação de 1 token de saída, que descontará uma quantia simbólica do saldo. O comando lê as variáveis do shell atual; portanto, mesmo que a chave esteja no arquivo de configurações, primeiro defina as variáveis com o comando export nesse terminal. Uma resposta JSON que começa com {"id":"msg_ significa que o endereço e a chave funcionam. O código 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, a mesma verificação fica assim. Se tudo funcionar, a resposta exibirá o campo id começando 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 funciona de forma diferente com uma chave de API

• O Remote Control e a ditado por voz não estão disponíveis. Segundo a documentação, eles exigem uma identidade claude.ai e não funcionam quando ANTHROPIC_AUTH_TOKEN está ativo. A partir da versão 2.1.196, o Remote Control também é desativado quando ANTHROPIC_BASE_URL aponta para um host diferente de api.anthropic.com.
• /fast mostra o modo rápido como desativado. Segundo a documentação, quando há apenas um token bearer, o Claude Code considera o modo rápido desativado e não envia uma consulta de disponibilidade.
• A busca de ferramentas MCP fica desativada por padrão. Isso acontece quando ANTHROPIC_BASE_URL aponta para um host diferente do da Anthropic.
• Os números em /context são estimativas. Kunavo nie udostępnia endpointu /v1/messages/count_tokens. Według documentação de compatibilidade de gateways (sprawdzone 3 października 2026) Claude Code liczy wtedy tokeny lokalnie na podstawie liczby znaków.

A descrição completa da integração está na documentação da integração do Claude Code (em inglês), e a versão em inglês deste guia está no artigo Install Claude Code.

Pagamento via BLIK: adicionar saldo e chave de API

Subskrypcje Claude kupowane przez stronę Anthropic można opłacić wyłącznie kartą kredytową lub debetową (FAQ de cobrança do Claude, sprawdzone 3 października 2026). BLIK-iem nie zapłacisz za Pro ani za Max. W Kunavo BLIK doładowuje przedpłacone saldo API, z którego Claude Code płaci za tokeny po ustawieniu klucza tak jak wyżej. Wszystkie kroki płatności opisuje poradnik como pagar pelo Claude com BLIK, a w skrócie wygląda to tak:

1. Crie uma conta Kunavo por e-mail ou com uma conta do Google. Não é necessário informar um cartão ao se cadastrar.
2. Na guia Faturamento (Billing), escolha o valor da recarga. O mínimo é 10 USD e não há tarifa mensal. Em valores maiores, você recebe um bônus: 100 USD → 110 USD na saldzie, 1000 USD → 1200 USD na saldzie, 5000 USD → 6250 USD na saldzie.
3. Na stronie płatności Stripe kwota jest pokazana w złotych. Wybierz BLIK, wygeneruj w aplikacji bankowej sześciocyfrowy kod, wpisz go i potwierdź płatność w aplikacji. Według documentação da Stripe (sprawdzone 3 października 2026) kod BLIK jest ważny 2 minuty, a po rozpoczęciu płatności masz 60 sekund na jej zatwierdzenie.
4. Na guia Chaves de API, crie uma chave que comece com sk-kn-. A chave é exibida apenas uma vez, então salve-a imediatamente e insira-a em ANTHROPIC_AUTH_TOKEN.

Na stronie płatności w złotych oprócz BLIK-a są też karty (Visa, Mastercard), Apple Pay i Google Pay na obsługiwanych urządzeniach oraz Link. Nie ma natomiast Przelewy24, PayU, PayPal ani zwykłego przelewu bankowego. Ceny są ustalone w dolarach, a Stripe przelicza je na złote. Według documentação da Stripe sobre Adaptive Pricing (sprawdzone 3 października 2026) kurs zawiera opłatę za przewalutowanie w wysokości 2–4%, którą ponosi kupujący. Płacąc kartą w dolarach, unikniesz tej opłaty, choć wtedy obowiązują kurs i opłaty Twojego banku, a BLIK działa tylko w złotych. Dokładną kwotę w złotych zobaczysz na stronie płatności przed potwierdzeniem.

O BLIK funciona apenas para recargas manuais. A recarga automática exige um cartão salvo ou o Link. O saldo não expira, e você não paga por solicitações malsucedidas. A Kunavo não emite notas fiscais com IVA, e o histórico de recargas está disponível na guia Faturamento (Billing). Lembre-se de que esta é uma recarga do saldo da API da Kunavo, não um pagamento pelo Claude Pro ou Max.

Quanto custa (exemplo de cálculo)

No Claude Code, você paga pelos tokens. A cada solicitação, o Claude Code envia todo o contexto da conversa novamente, mas o início repetido do contexto pode ser cobrado pela tarifa de leitura do cache. Abaixo está um exemplo de cálculo baseado em tokens. Isso não é uma medição nem um limite máximo de custo. Todas as suposições são informadas:

• cada solicitação tem 40 000 tokens de entrada, dos quais 36 000 (90%) são cobrados como leitura do cache, e os 4000 restantes como gravação no cache;
• cada solicitação retorna 1000 tokens de saída;
• em uma sessão de trabalho há 50 dessas solicitações, sem chamadas de Claude Haiku 4.5 em segundo plano;
• na Kunavo, a leitura do cache custa 10% da tarifa de entrada, e a gravação no cache custa 1,25× a tarifa de entrada. Essas proporções valem para Claude Sonnet 5, e cada modelo da tabela é calculado segundo suas próprias proporções.

O custo real depende do tamanho do contexto, do número de acertos no cache, do tamanho da resposta e de você limpar ou não a conversa entre tarefas com o comando /clear. As tarifas de todos os modelos estão no preçário. Estime seu próprio consumo com a calculadora de custos de tokens do Claude (em inglês). O guia quanto custa o Claude Code explica quando uma assinatura é mais vantajosa e quando a API é melhor.

Erros mais comuns

Limitações

• A Kunavo não emite notas fiscais com IVA.
• O BLIK funciona apenas para recargas manuais. A recarga automática exige um cartão salvo ou o Link.
• Esta é uma API cobrada por tokens, não uma assinatura do Claude Pro ou Max. Remote Control e ditado por voz não funcionam com uma chave de API, o modo /fast está desativado, e a pesquisa de ferramentas MCP está desativada por padrão.
• Atualmente (verificado em 3 października 2026), a Kunavo não disponibiliza o Sonnet 5.5; por isso, a configuração acima fixa o alias sonnet em claude-sonnet-5. Sem modelos fixados, os aliases padrão podem retornar 404. O Claude Opus 5.5, fixado no alias opus, exige o Claude Code versão 2.1.280 ou posterior.
• A documentação oficial do Claude Code e a documentação de integração da Kunavo estão disponíveis apenas em inglês.

Perguntas frequentes