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

O Claude Code instala-se 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 (na Linha de Comandos, o CMD, a linha do install.cmd mais abaixo). Depois há duas formas de o usar. Com subscrição, inicia-se sessão com uma conta Pro, Max, Team, Enterprise ou Console (quem só tem o plano gratuito do Claude.ai não tem acesso ao Claude Code). Sem subscrição, usa-se uma chave de API: definem-se ANTHROPIC_BASE_URL (só o domínio, sem /v1), ANTHROPIC_AUTH_TOKEN e quatro variáveis de modelo, e confirma-se com /status. O saldo do Kunavo carrega-se 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 suportados pela 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: Install Claude Code.

Antes de instalar

macOS, Linux e WSL: uma só linha

No Terminal (no macOS está em Aplicações › 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, por isso abra uma janela nova 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>, está no PowerShell; se aparece só C:\Users\Nome>, sem o PS, está na Linha de Comandos (CMD). Não é preciso usar «Executar como administrador»: a documentação oficial diz expressamente que 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 tropeção mais frequente é a janela trocada. Se o PowerShell responder The token '&&' is not a valid statement separator, recebeu a linha do CMD; se o CMD responder 'irm' is not recognized as an internal or external command, recebeu a do PowerShell. Num Windows em português, esta segunda mensagem pode aparecer traduzida, com a mesma causa. E a linha do macOS, com | bash, colada no PowerShell, dá um erro a dizer que bash não é reconhecido. Nos três casos, a solução é usar a linha que corresponde à 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 escolha e não um requisito, ao contrário do que se lê em alguns guias. Quem escolher o WSL executa a linha do macOS/Linux no terminal do WSL e inicia o claude também aí, não a partir do PowerShell nem do 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 faz-se à mão. 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-o 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 ficheiros de definições. É a forma mais rápida de perceber 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 resoluçã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 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 a bloquear os scripts do npm. Use o instalador nativo ou permita scripts locais para o seu utilizador:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

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

Primeira utilização: subscrição ou chave de API

No primeiro arranque decide-se como o Claude Code é pago. Não é preciso reinstalar para mudar de rota: o que decide é haver ou não uma chave definida.

Rota A — iniciar sessão com a subscrição

Na pasta do projeto, execute claude e inicie sessão no browser. Atenção a quem já tem ANTHROPIC_API_KEY no ambiente: em vez de abrir o browser, o Claude Code pede uma única aprovação dessa chave. Recusada essa aprovação, a chave é ignorada daí em diante e a pergunta não se repete, e parece que a variável não está a ser lida. Para a reativar: /config → Use custom API key.

Rota B — sem subscrição, com chave de API

ANTHROPIC_BASE_URL é uma variável do próprio Claude Code, pensada para encaminhar os pedidos por um proxy ou gateway. Apontá-la para um endpoint compatível com a Messages API da Anthropic é, por isso, uma configuração suportada, sem plug-ins nem versões modificadas. Os passos:

1. Criar uma conta no Kunavo.
2. Carregar o saldo em Billing, a partir de US$ 10 (o pagamento com MB WAY está explicado mais abaixo).
3. Em /app/keys, criar uma chave que começa por sk-kn-. Só é mostrada uma vez, por isso convém guardá-la logo.
4. Definir as variáveis. No macOS e no Linux, no ~/.zshrc ou no ~/.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 numa 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 sítio é o bloco env das definições do utilizador: ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json). Aí, os valores aplicam-se a todos os projetos, incluindo os agentes em segundo plano; a extensão do VS Code é a exceção (ver abaixo). Uma variável exportada na shell só chega aos programas iniciados a partir dessa shell: um editor aberto pela Dock ou pelo menu Iniciar não a vê. Se o ficheiro já tiver outras definiçõ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 definições de utilizador do próprio VS Code (comando Preferences: Open User Settings (JSON)). Segundo a documentação de gateways, a extensão verifica as credenciais nesta definição antes de arrancar; os valores do ~/.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 as outras armadilhas

Cada linha do bloco tem a sua armadilha:

• Em ANTHROPIC_BASE_URL não entra o caminho. O caminho /v1/messages é o próprio Claude Code que o junta; um endereço já terminado em /v1 acaba em /v1/v1/messages, que responde 404.
• ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY: o Kunavo aceita as duas. Segundo a documentação de gateways, ANTHROPIC_AUTH_TOKEN segue no cabeçalho Authorization: Bearer e aplica-se de imediato; ANTHROPIC_API_KEY segue no cabeçalho x-api-key e, no modo interativo, tem de ser aprovada uma vez antes de entrar em vigor (ver Rota A). Por isso este guia usa ANTHROPIC_AUTH_TOKEN.
• O nome em ANTHROPIC_MODEL tem de ser exato. Copie-o tal 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 conta para as tarefas de fundo. Segundo a documentação, define o alias haiku e o modelo das funções de fundo 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, muda-se de modelo com /model claude-opus-5-5, ou arranca-se logo com claude --model claude-opus-5-5. A conta em euros, com exemplos de uso mensal e o ponto a partir do qual compensa mais uma subscrição, está em Preço do Claude Code em euros; o consumo de cada um calcula-se 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 ecrã de início de sessão: a variável aplica-se de imediato. Se o ecrã de início de sessão aparecer, o Claude Code não leu nenhuma chave. Nesse caso, defina-a num sítio que o Claude Code lê antes do assistente do primeiro arranque: um export na shell ou o bloco env de ~/.claude/settings.json. Um bloco env no .claude/settings.json ou no .claude/settings.local.json de um projeto só se aplica, numa sessão interativa, depois do assistente do primeiro arranque 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. Esta linha só aparece quando há um endereço de gateway definido; se faltar, a ANTHROPIC_BASE_URL não chegou à sessão.
• A linha Auth token deve indicar ANTHROPIC_AUTH_TOKEN. Se, em vez dela, aparecer Login method com uma conta claude.ai, a variável não foi lida e a sessão está a usar a subscrição.

Quem já tinha iniciado sessão com uma subscrição pode ver, ao arrancar, um aviso de que há duas credenciais ativas (a mensagem termina em auth may not work as expected). Os pedidos seguem pela chave; o /logout limpa o início de sessão antigo.

Para testar endereço e chave antes de abrir o Claude Code, a documentação sugere um pedido de um único token de saída, que gasta uma fração ínfima do saldo. Os comandos leem as variáveis da shell, por isso defina-as aí também, mesmo que já estejam no 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 endereço e 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, ficam indisponíveis enquanto ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN ou um apiKeyHelper estiverem ativos; o Remote Control também fica desligado enquanto ANTHROPIC_BASE_URL apontar para um endereço fora da Anthropic.
• O /fast mostra o modo rápido como desativado. Só com um bearer token, o Claude Code trata o modo rápido como desligado.
• A pesquisa de ferramentas MCP (MCP tool search) fica desligada por omissã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 do /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 resto — código, ferramentas, subagentes, servidores MCP, hooks e prompt caching — funciona como sempre. Mais pormenores 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 num checkout em euros. 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 a 3 de outubro de 2026):

• Por pagamento: entre 0,50 € e 5000 €.
• Por dia: 1000 € por omissão, ajustável até 10 000 € na aplicação MB WAY. Os carregamentos maiores podem ultrapassar o limite diário predefinido; nesse caso, suba-o na aplicação antes de pagar. Compare o valor em euros que o checkout mostra com estes limites.
• Pagamentos recorrentes: não suportados.
• No extrato aparece o nome da Stripe (Stripe Inc), com o valor da operação.

1. Criar uma conta no Kunavo.
2. Em Billing, escolher um valor, a partir de US$ 10. Os 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, escolher MB WAY, introduzir o número de telemóvel e confirmar a compra na aplicação MB WAY. O valor em euros aparece antes da confirmação.
4. Em /app/keys, criar a chave e colocá-la em ANTHROPIC_AUTH_TOKEN.

O saldo é pré-pago: não há mensalidade, o saldo não expira e os pedidos que falham não são cobrados. O carregamento automático só funciona com um cartão guardado ou com o Link; com MB WAY, carrega-se sempre à mão, porque, segundo a Stripe, o MB WAY não aceita pagamentos recorrentes nem fica guardado para pagamentos futuros. O Kunavo não emite faturas, nem com NIF nem com IVA; o histórico de carregamentos fica em Billing. Estes meios de pagamento carregam apenas o saldo da API do Kunavo. Mais sobre o tema em Pagar o Claude com MB WAY.

Erros comuns

Depois de instalar

No primeiro arranque num projeto, escreva /init: o Claude Code percorre o repositório e escreve um CLAUDE.md com o que deduziu: como se corre o projeto, como se testam as alterações, que regras de estilo segue. Reveja esse ficheiro e mantenha-o curto, porque é carregado em todas as sessões. Entre tarefas independentes, /clear começa uma conversa nova; numa tarefa longa, /compact resume o histórico para continuar.

O que convém saber

• É uma API paga por token, não uma subscrição Claude Pro ou Max. Quem usa o Claude Code várias horas todos os dias costuma pagar menos com uma subscrição; pagar por token compensa com uso irregular, e um mês parado 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 partilhada, sem quota reservada e sem garantias contratuais; quem precisa delas deve contratar diretamente com a Anthropic.
• O MB WAY serve só para carregamentos manuais; o carregamento automático exige um cartão ou o Link.
• Os valores em euros mostrados no checkout já incluem a comissão de conversão da Stripe.

Perguntas frequentes