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

O Claude Code é instalado com um comando oficial por sistema: no macOS, no Linux e no WSL, curl -fsSL https://claude.ai/install.sh | bash; no Windows, no PowerShell, irm https://claude.ai/install.ps1 | iex (no Prompt de Comando, o CMD, use a linha do install.cmd mais abaixo). Depois, há duas formas de usá-lo. Com uma assinatura, faça login com uma conta Pro, Max, Team, Enterprise ou Console (quem tem apenas o plano gratuito do Claude.ai não tem acesso ao Claude Code). 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 confirme com /status. O saldo da Kunavo pode ser recarregado com MB WAY no checkout em euros, a partir de US$ 10, sem mensalidade.

Comandos e variáveis verificados a 3 de outubro de 2026 na documentação oficial de instalação do Claude Code e na documentação das variáveis de ambiente; preços e meios de pagamento verificados a 3 de outubro de 2026. Portugal consta da lista de países compatíveis com a Anthropic (consultada a 3 de outubro de 2026), tanto para o Claude.ai como para a API. Este guia existe também em inglês: Instalar o Claude Code.

Antes de instalar

macOS, Linux e WSL: uma única linha

No Terminal (no macOS, em Aplicativos › Utilitários), execute:

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

É a instalação nativa recomendada: um programa autônomo que, segundo a documentação oficial, se atualiza sozinho em segundo plano. O comando claude fica 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, a linha é exatamente a mesma, executada dentro do terminal do WSL.

Instalar no Windows

No Windows há duas linhas, e a escolha depende apenas da janela que está aberta. Se a linha começa por PS C:\Users\Nome>, você está no PowerShell; se aparece apenas C:\Users\Nome>, sem o PS, você está no Prompt de Comando (CMD). Não é preciso usar “Executar como administrador”: a documentação oficial diz expressamente que isso não é necessário, ao contrário do que alguns guias em português recomendam.

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

:: Linha de Comandos do Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

No Windows, o erro mais frequente é usar a janela errada. Se o PowerShell responder The token '&&' is not a valid statement separator, você recebeu a linha do CMD; se o CMD responder 'irm' is not recognized as an internal or external command, recebeu a do PowerShell. Em um Windows em português, essa segunda mensagem pode aparecer traduzida, com a mesma causa. E a linha do macOS, com | bash, colada no PowerShell, gera um erro dizendo que bash não é reconhecido. Nos três casos, a solução é usar a linha correspondente à janela.

O Git for Windows é opcional. Com ele, a ferramenta Bash do Claude Code passa a correr no Git Bash, e o PowerShell continua disponível ao lado; sem ele, todos os comandos correm pelo PowerShell. Quando o Git está instalado numa pasta fora do habitual e o Claude Code não dá com o bash.exe, indica-se o caminho em CLAUDE_CODE_GIT_BASH_PATH, dentro do bloco env de ~/.claude/settings.json; o exemplo da documentação é C:\Program Files\Git\bin\bash.exe.

O WSL é, portanto, uma opção, não um requisito, ao contrário do que aparece em alguns guias. Quem escolher o WSL executa a linha do macOS/Linux no terminal do WSL e inicia o claude também nele, não pelo PowerShell nem pelo CMD.

Pelo Homebrew, WinGet ou npm

Também funciona, com uma diferença importante: segundo a documentação oficial, as instalações pelo Homebrew e pelo WinGet não se atualizam sozinhas. A atualização é manual. Existem ainda repositórios apt, dnf e apk assinados para Linux.

# Homebrew
brew install --cask claude-code
brew upgrade claude-code              # não se atualiza sozinho

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # não se atualiza sozinho

O pacote npm exige o Node.js 22 ou posterior — não o Node.js 18 que alguns guias ainda indicam. Com um Node.js mais antigo, o npm mostra apenas um aviso EBADENGINE durante a instalação, em vez de falhar. Nunca use sudo npm install -g: a documentação oficial desaconselha isso expressamente. Para atualizar, use @latest, não npm update -g.

node -v                                           # tem de ser v22 ou posterior
npm install -g @anthropic-ai/claude-code          # nunca com sudo

# para atualizar mais tarde: com @latest, não com npm update -g
npm install -g @anthropic-ai/claude-code@latest

Confirmar a instalação

claude --version   # mostra o número da versão, seguido de (Claude Code)
claude doctor      # diagnóstico só de leitura da instalação e das definições, sem abrir sessão

O claude doctor não inicia nenhuma sessão: mostra o estado da instalação e dos arquivos de configuração. É a maneira mais rápida de descobrir se um problema está na instalação ou na configuração.

Um command not found: claude (ou, no Windows, a indicação de que claude não é um comando conhecido) quer dizer que o terminal não sabe onde o programa ficou. Muitas vezes basta fechar a janela e abrir outra. Se continuar, falta a pasta no PATH: no macOS e no Linux é ~/.local/bin, a acrescentar no ficheiro de arranque da shell (~/.zshrc ou ~/.bashrc); no Windows é %USERPROFILE%\.local\bin; segundo a solução de problemas oficial, confirma-se e acrescenta-se assim no PowerShell:

# 1. A pasta de instalação já está no PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem resultado? Acrescente-a ao PATH do utilizador e abra uma janela nova
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Na janela nova: dois caminhos significam duas instalações lado a lado
where.exe claude

Se você instalou pelo npm e o PowerShell responde npm.ps1 cannot be loaded because running scripts is disabled on this system, é a política de execução do PowerShell que está bloqueando os scripts do npm. Use o instalador nativo ou permita scripts locais para o seu usuário:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

E, se aparecer Claude Code does not support 32-bit Windows, o “Windows PowerShell (x86)” foi aberto. O Windows tem duas entradas do PowerShell, e a versão x86 é executada como um processo de 32 bits; abra a entrada “Windows PowerShell”, sem o (x86).

Primeiro uso: assinatura ou chave de API

Na primeira inicialização, você decide como o Claude Code será pago. Não é preciso reinstalar para mudar de opção: o que importa é haver ou não uma chave definida.

Opção A — iniciar sessão com a assinatura

Na pasta do projeto, execute claude e inicie sessão no navegador. Atenção para quem já tem ANTHROPIC_API_KEY no ambiente: em vez de abrir o navegador, o Claude Code solicita uma única aprovação dessa chave. Se essa aprovação for recusada, a chave será ignorada dali em diante e a pergunta não se repetirá, dando a impressão de que a variável não está sendo lida. Para reativá-la: /config → Use custom API key.

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

ANTHROPIC_BASE_URL é uma variável do próprio Claude Code, criada para encaminhar as solicitações por um proxy ou gateway. Apontá-la para um endpoint compatível com a Messages API da Anthropic é, portanto, uma configuração compatível, sem plug-ins nem versões modificadas. As etapas:

1. Criar uma conta no Kunavo.
2. Adicionar saldo em Faturamento, a partir de US$ 10 (o pagamento com MB WAY é explicado mais abaixo).
3. Em /app/keys, criar uma chave que começa por sk-kn-. Ela é exibida apenas uma vez, portanto é recomendável salvá-la imediatamente.
4. Defina as variáveis. No macOS e no Linux, em ~/.zshrc ou ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # só o domínio, sem /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 janela do PowerShell:

# Vale só para esta janela do 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

Para uso permanente, o melhor local é o bloco env das configurações do usuário: ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json). Ali, os valores se aplicam a todos os projetos, incluindo os agentes em segundo plano; a extensão do VS Code é a exceção (veja abaixo). Uma variável exportada no shell só chega aos programas iniciados a partir desse shell: um editor aberto pelo Dock ou pelo menu Iniciar não a verá. Se o arquivo já tiver outras configurações, acrescente 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"
  }
}

Nunca ponha a chave no .claude/settings.json de um projeto: segundo a documentação oficial de gateways (consultada a 3 de outubro de 2026), esse ficheiro entra nos commits e é partilhado com quem clonar o repositório. E atenção à precedência: quando a shell e um ficheiro de definições definem a mesma variável, prevalece o ficheiro de definições. Se uma alteração na shell não surtir efeito, veja primeiro o settings.json.

Quem usa a extensão do VS Code define as variáveis em claudeCode.environmentVariables, nas configurações de usuário do próprio VS Code (comando Preferences: Open User Settings (JSON)). Segundo a documentação de gateways, a extensão verifica as credenciais nessa configuração antes de iniciar; os valores de ~/.claude/settings.json chegam ao processo do Claude Code, 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" }
  ]
}

As quatro variáveis de modelo e outras armadilhas

Cada linha do bloco tem sua própria armadilha:

• Em ANTHROPIC_BASE_URL não se inclui o caminho. O caminho /v1/messages é acrescentado pelo próprio Claude Code; um endereço que já termina em /v1 resulta em /v1/v1/messages, que responde 404.
• ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY: o Kunavo aceita ambos. Segundo a documentação de gateways, ANTHROPIC_AUTH_TOKEN segue no cabeçalho Authorization: Bearer e se aplica imediatamente; ANTHROPIC_API_KEY segue no cabeçalho x-api-key e, no modo interativo, precisa ser aprovada uma vez antes de entrar em vigor (veja a Opção A). Por isso, este guia usa ANTHROPIC_AUTH_TOKEN.
• O nome em ANTHROPIC_MODEL precisa ser exato. Copie-o exatamente como aparece aqui: claude-sonnet-5.
• Sem ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_DEFAULT_OPUS_MODEL, os aliases mudam sozinhos. Segundo a documentação de configuração de modelos (consultada a 3 de outubro de 2026), para quem usa a API da Anthropic o alias opus aponta para o Opus 5.5 e o alias sonnet para o Sonnet 5.5, e estes aliases mudam com as novas versões. Fixa-se com o nome completo do modelo ou com variáveis como ANTHROPIC_DEFAULT_OPUS_MODEL. O Kunavo não serve o Sonnet 5.5, e um modelo que não existe devolve 404: sem ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5, falham o /model sonnet, os subagentes com model: sonnet e o passo de execução do opusplan. Já o opus aponta para claude-opus-5-5, que o Kunavo serve, mas só a partir do Claude Code v2.1.280; quem tiver uma versão anterior corre claude update.
• ANTHROPIC_DEFAULT_HAIKU_MODEL também se aplica às tarefas em segundo plano. Segundo a documentação, ele define o alias haiku e o modelo das funções em segundo plano do Claude Code. Com o Claude Haiku 4.5, essas chamadas usam o modelo mais barato da tabela abaixo.

Preços por milhão de tokens, do catálogo do Kunavo; a coluna da Anthropic vem de claude.com/pricing (consultado a 3 de outubro de 2026):

Dentro de uma sessão, você pode mudar de modelo com /model claude-opus-5-5, ou iniciar diretamente com claude --model claude-opus-5-5. O cálculo em euros, com exemplos de uso mensal e o ponto a partir do qual uma assinatura passa a compensar mais, está em Preço do Claude Code em euros; o consumo de cada pessoa pode ser calculado com a calculadora de custos de tokens. Todos os modelos e preços estão na página de preços.

Confirmar com /status

Execute claude. Com ANTHROPIC_AUTH_TOKEN definida, não aparece uma tela de início de sessão: a variável se aplica imediatamente. Se a tela de início de sessão aparecer, o Claude Code não leu nenhuma chave. Nesse caso, defina-a em um local que o Claude Code leia antes do assistente da primeira inicialização: um export no shell ou o bloco env de ~/.claude/settings.json. Um bloco env em .claude/settings.json ou em .claude/settings.local.json de um projeto só se aplica, em uma sessão interativa, depois do assistente da primeira inicialização e da pergunta sobre confiar na pasta.

Dentro da sessão, escreva /status e procure duas linhas no separador Status (fonte: a documentação oficial de gateways, consultada a 3 de outubro de 2026):

• Anthropic base URL deve mostrar https://api.kunavo.com. Essa linha só aparece quando há um endereço de gateway definido; se estiver ausente, ANTHROPIC_BASE_URL não chegou à sessão.
• A linha Auth token deve indicar ANTHROPIC_AUTH_TOKEN. Se, em vez disso, aparecer Login method com uma conta claude.ai, a variável não foi lida e a sessão está usando a assinatura.

Quem já havia iniciado sessão com uma assinatura pode ver, ao iniciar, um aviso de que há duas credenciais ativas (a mensagem termina em auth may not work as expected). As solicitações seguem pela chave; o /logout limpa o início de sessão antigo.

Para testar o endereço e a chave antes de abrir o Claude Code, a documentação sugere uma solicitação de um único token de saída, que consome uma fração ínfima do saldo. Os comandos leem as variáveis do shell, portanto defina-as ali também, mesmo que já estejam 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 por {"id":"msg_ significa que o endereço e a chave funcionam; no PowerShell aparece um id que começa por msg_. Um 401 significa que a chave não foi reconhecida.

O que muda com uma chave de API

• Sem Remote Control nem ditado por voz. Segundo a documentação de gateways, eles ficam indisponíveis enquanto ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN ou um apiKeyHelper estiverem ativos; o Remote Control também fica desativado enquanto ANTHROPIC_BASE_URL apontar para um endereço fora da Anthropic.
• O /fast mostra o modo rápido como desativado. Somente com um bearer token, o Claude Code trata o modo rápido como desativado.
• A pesquisa de ferramentas MCP (MCP tool search) fica desativada por padrão quando ANTHROPIC_BASE_URL aponta para um endereço fora da Anthropic (documentação das variáveis de ambiente, consultada a 3 de outubro de 2026).
• Os números de /context são estimativas. O Kunavo não serve /v1/messages/count_tokens e, segundo a documentação de compatibilidade para gateways (consultada a 3 de outubro de 2026), sem esse endpoint o Claude Code recorre a uma estimativa baseada em caracteres.

O restante — código, ferramentas, subagentes, servidores MCP, hooks e prompt caching — funciona como sempre. Mais detalhes na documentação de integração do Claude Code (em inglês) e em Claude Code without a subscription (em inglês).

Pagar o saldo com MB WAY

Primeiro, a subscrição: uma subscrição Claude comprada no site paga-se só com cartão de crédito ou de débito (artigo de ajuda da Anthropic sobre os planos pagos, consultado a 3 de outubro de 2026); numa subscrição feita na aplicação Claude para iOS ou Android, os meios de pagamento são os da App Store ou do Google Play. Os meios de pagamento do Kunavo, MB WAY incluído, não pagam o Claude Pro nem o Max: carregam o saldo da API do Kunavo, que é o que a Rota B usa.

O saldo carrega-se no checkout da Stripe. Os preços estão em dólares americanos; para quem compra em Portugal, a Stripe mostra o valor em euros. Segundo a documentação da Stripe sobre Adaptive Pricing (consultada a 3 de outubro de 2026), essa conversão inclui uma comissão de 2–4% paga pelo comprador; quem escolhe pagar em dólares (com cartão, Apple Pay, Google Pay ou Link) não paga essa comissão, embora o banco possa aplicar a sua própria taxa de câmbio e comissões. O MB WAY só funciona em euros. No checkout em euros aparecem:

• MB WAY. Escolhe-se MB WAY, introduz-se o número de telemóvel e confirma-se a compra na aplicação MB WAY, através da notificação ou na área de atividade (Stripe sobre o MB WAY e MB WAY sobre compras online, consultados a 3 de outubro de 2026). Segundo a Stripe, são aceites números internacionais, mas a maioria dos clientes usa um número português, começado por +351.
• Cartões (Visa, Mastercard), Apple Pay, Google Pay e Link.

Não aparecem: referências Multibanco (pagamento por entidade e referência), PayPal, débito direto SEPA e Klarna, que só aparece a compradores nos Estados Unidos. A conversão para euros vem do Adaptive Pricing da Stripe, e a lista de meios de pagamento que ele disponibiliza inclui o MB WAY mas não o Multibanco. O MB WAY também permite gerar cartões virtuais MB NET para compras online (MB WAY sobre o MB NET, consultado a 3 de outubro de 2026); não está confirmado que o campo do cartão do checkout os aceite, por isso o caminho seguro é escolher MB WAY diretamente.

O que a Stripe documenta sobre o MB WAY (consultado em 3 de outubro de 2026):

• Por pagamento: entre 0,50 € e 5000 €.
• Por dia: 1000 € por padrão, ajustável até 10 000 € no aplicativo MB WAY. Carregamentos maiores podem ultrapassar o limite diário predefinido; nesse caso, aumente-o no aplicativo antes de pagar. Compare o valor em euros exibido pelo checkout com esses limites.
• Pagamentos recorrentes: não compatíveis.
• No extrato aparece o nome da Stripe (Stripe Inc), com o valor da operação.

1. Criar uma conta no Kunavo.
2. Em Faturamento, escolha um valor a partir de US$ 10. Carregamentos maiores trazem saldo extra: quem carrega US$ 100 recebe US$ 110; quem carrega US$ 1000 recebe US$ 1200; quem carrega US$ 5000 recebe US$ 6250.
3. No checkout da Stripe, com o valor em euros, escolha MB WAY, informe o número de celular e confirme a compra no aplicativo MB WAY. O valor em euros aparece antes da confirmação.
4. Em /app/keys, crie a chave e coloque-a em ANTHROPIC_AUTH_TOKEN.

O saldo é pré-pago: não há mensalidade, o saldo não expira e as solicitações que falham não são cobradas. O carregamento automático só funciona com um cartão salvo ou com o Link; com MB WAY, o carregamento é sempre manual, porque, segundo a Stripe, o MB WAY não aceita pagamentos recorrentes nem fica salvo para pagamentos futuros. O Kunavo não emite faturas, nem com NIF nem com IVA; o histórico de carregamentos fica em Billing. Esses meios de pagamento carregam apenas o saldo da API do Kunavo. Saiba mais sobre o tema em Pagar o Claude com MB WAY.

Erros comuns

Depois de instalar

Na primeira inicialização em um projeto, escreva /init: o Claude Code percorre o repositório e escreve um CLAUDE.md com o que deduziu: como executar o projeto, como testar as alterações e quais regras de estilo ele segue. Revise esse arquivo e mantenha-o curto, porque ele é carregado em todas as sessões. Entre tarefas independentes, /clear inicia uma nova conversa; em uma tarefa longa, /compact resume o histórico para continuar.

O que convém saber

• É uma API paga por token, não uma assinatura Claude Pro ou Max. Quem usa o Claude Code várias horas todos os dias costuma pagar menos com uma assinatura; pagar por token compensa com uso irregular, e um mês sem uso não custa nada. A comparação em euros está em Preço do Claude Code em euros.
• Quem trabalha com uma chave de API fica sem Remote Control e sem ditado por voz.
• Pelo Kunavo, usa-se capacidade compartilhada, sem cota reservada e sem garantias contratuais; quem precisa delas deve contratar diretamente com a Anthropic.
• O MB WAY serve apenas para carregamentos manuais; o carregamento automático exige um cartão ou o Link.
• Os valores em euros exibidos no checkout já incluem a comissão de conversão da Stripe.

Perguntas frequentes