Como instalar o Claude Code no Windows, macOS e Linux — e como usá-lo sem assinatura

Para instalar o Claude Code, basta um comando: no macOS, Linux ou WSL, execute curl -fsSL https://claude.ai/install.sh | bash; no Windows, execute irm https://claude.ai/install.ps1 | iex no PowerShell (no Prompt de Comando, CMD, use a linha de install.cmd mostrada abaixo). Depois, abra um novo terminal, verifique com claude --version, entre na pasta do seu projeto e execute claude; o primeiro comando útil é /init. Para se conectar, há dois caminhos: iniciar sessão com uma conta Pro, Max, Team, Enterprise ou Console (o plano gratuito do Claude.ai não inclui o Claude Code) ou definir duas variáveis de ambiente, ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN, e usar uma chave de API paga conforme o uso, sem assinatura.

Comandos verificados em 11 de setembro de 2026 com a documentação oficial de instalação da Anthropic.

Requisitos

Instalar no macOS e Linux

Abra o Terminal e cole:

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

Este é o método recomendado: ele instala um binário independente que se atualiza automaticamente em segundo plano. O executável fica em ~/.local/bin/claude e um terminal que já estava aberto não vê o novo PATH; portanto, abra outra janela antes de testar. No WSL, o comando é o mesmo.

Instalar o Claude Code no Windows

No Windows, há duas linhas diferentes; a única coisa que muda é o terminal. Se o prompt começar com PS C:\Users\TuNombre>, você está no PowerShell; sem o PS, apenas C:\Users\TuNombre>, é o Prompt de Comando (CMD). Não é necessário executar como administrador.

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

:: Windows Símbolo del sistema (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Colar a linha no terminal errado é o erro mais comum. A linha do CMD no PowerShell retorna The token '&&' is not a valid statement separator; a do PowerShell no CMD retorna 'irm' is not recognized as an internal or external command (em um Windows em português, «não é reconhecido como um comando interno ou externo»); e o curl … | bash do macOS colado no PowerShell retorna A parameter cannot be found that matches parameter name 'fsSL'. Nos três casos, basta usar a linha correspondente.

Instalar o Git for Windows é opcional, mas recomendado: o Claude Code usa o Git Bash dele para executar comandos e, sem ele, usa o PowerShell. Se o Git estiver instalado e ainda assim o Git Bash não for encontrado, defina CLAUDE_CODE_GIT_BASH_PATH no bloco env da configuração, usando o caminho de bash.exe.

Com o WSL, execute a linha do macOS/Linux dentro do terminal do WSL e abra claude nele, não no PowerShell nem no CMD.

Com um gerenciador de pacotes

Também funciona, com uma diferença importante: nenhum deles se atualiza automaticamente por padrão (você precisará executar brew upgrade claude-code ou winget upgrade Anthropic.ClaudeCode). Também existem repositórios apt, dnf e apk assinados para Debian/Ubuntu, Fedora/RHEL e Alpine.

# Homebrew (macOS, Linux) — canal stable
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — requiere Node.js 22 o posterior; nunca con sudo
npm install -g @anthropic-ai/claude-code

Com npm, a partir da versão 2.1.198, o pacote exige Node.js 22 ou posterior; com um Node antigo, o npm apenas exibe um aviso EBADENGINE e a instalação termina. Ele instala o mesmo binário nativo, que não usa Node.js para ser executado. Nunca use sudo npm install -g: isso causa problemas de permissões e representa um risco de segurança.

Verificar a instalação

claude --version   # imprime la versión, por ejemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico de la instalación y la configuración, sin abrir sesión

Use claude doctor: sem iniciar sessão, ele mostra o estado da instalação, os erros dos arquivos de configuração e a solução sugerida. É a forma mais rápida de saber se o problema está na instalação ou na configuração.

Se você vir command not found: claude (ou, no Windows, que claude não é reconhecido), a pasta de instalação não está no PATH. No macOS e Linux, abra um novo terminal e, se continuar igual, adicione ~/.local/bin ao PATH em ~/.zshrc ou ~/.bashrc. No Windows, a pasta é %USERPROFILE%\.local\bin; verifique-a e adicione-a pelo PowerShell:

# 1. Comprueba si la carpeta de instalación ya está en el PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. ¿Sin salida? Añádela al PATH de usuario y abre una terminal nueva
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. En la terminal nueva: si hay dos instalaciones, verás dos rutas
where.exe claude

Primeira conexão: assinatura ou chave de API

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

Na pasta do projeto, execute claude e siga o início de sessão no navegador com uma conta Pro, Max, Team, Enterprise ou Console. Um detalhe confuso: se a variável ANTHROPIC_API_KEY já estiver definida, o Claude Code perguntará uma única vez se você deseja usar essa chave. Se responder não, ele a ignorará a partir de então sem perguntar novamente, e parecerá que a variável não foi lida. Para reativá-la: /config → Use custom API key.

Opção B — sem assinatura, com uma chave paga conforme o uso

O Claude Code lê ANTHROPIC_BASE_URL nativamente, portanto apontá-lo para qualquer endpoint da Anthropic Messages API é uma configuração compatível: sem plugins, sem proxy e sem binários modificados. As etapas são: crie a conta, recarregue o saldo (mínimo de $10), gere uma chave sk-kn- no painel de chaves (ela será exibida apenas uma vez) e adicione este bloco env à configuração do usuário, ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json). Assim, ele será aplicado a todos os terminais, à extensão do editor e aos processos em segundo plano:

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

Para testar primeiro em uma única janela do PowerShell:

# Solo para esta ventana de PowerShell (en macOS/Linux: export VARIABLE=valor)
$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

• ANTHROPIC_BASE_URL contém apenas o domínio. O Claude Code adiciona /v1/messages; com /v1 no final, a requisição vai para /v1/v1/messages e retorna 404.
• Use ANTHROPIC_AUTH_TOKEN, não ANTHROPIC_API_KEY. Eles são enviados em cabeçalhos HTTP diferentes: o primeiro envia Authorization: Bearer e funciona imediatamente; o segundo envia x-api-key e também passa pela aprovação única mencionada acima.
• Escreva o nome exato do modelo em ANTHROPIC_MODEL. A Kunavo reconhece apenas o nome idêntico e não traduz nomes antigos com data.
• Fixe também ANTHROPIC_DEFAULT_OPUS_MODEL. O modelo padrão do Claude Code e seu alias opus apontam para o Opus mais recente e, se a Kunavo ainda não o oferecer, a primeira solicitação retornará um 404. Aqui, o alias opus fica fixado em Claude Opus 5.5 (claude-opus-5-5), que requer o Claude Code v2.1.280 ou posterior; com uma versão anterior, execute claude update.
• E também ANTHROPIC_DEFAULT_SONNET_MODEL. O alias sonnet solicita o Sonnet 5.5, que a Kunavo não oferece: sem esta variável, /model sonnet, a fase de execução de opusplan e os subagentes configurados com sonnet retornam um 404. Fixá-la em claude-sonnet-5 evita isso.
• ANTHROPIC_DEFAULT_HAIKU_MODEL cobre as chamadas em segundo plano que o Claude Code faz por conta própria (resumos, títulos): apontá-las para o Haiku é uma economia sem esforço.

Nunca coloque a chave no .claude/settings.json do projeto: esse arquivo vai para o repositório. Na extensão do VS Code, as variáveis ficam em claudeCode.environmentVariables, dentro das configurações do usuário do VS Code, porque a extensão verifica as credenciais antes de iniciar.

Tarifas por 1M de tokens, obtidas do catálogo:

Como saber qual opção está ativa

Dentro do Claude Code, execute /status. Uma linha Auth token significa que a chave está em uso; uma linha Login method com uma conta do claude.ai significa que a variável não foi lida. Elas não se acumulam: enquanto a variável existir, a assinatura ficará suspensa; remova-a e o Claude Code voltará à assinatura, sem reinstalação.

Atrás de um gateway, três coisas mudam: o Remote Control e o ditado por voz não ficam disponíveis (eles precisam da identidade do claude.ai); /fast pode dizer que o modo rápido não está disponível, porque essa verificação vai diretamente para a Anthropic, embora as requisições normais não mudem; e os valores de /context passam a ser estimativas locais. O código, as ferramentas, os subagentes, o MCP, os hooks e o caching de prompts funcionam da mesma forma. Todos os detalhes estão na documentação da integração e no guia da chave de API do Claude Code (ambos em inglês).

Como usar o Claude Code: primeiros passos

# 1. Arranca siempre dentro de la carpeta del proyecto
cd ~/proyectos/mi-app
claude

# 2. Primer comando: lee el repositorio y genera CLAUDE.md
> /init

# 3. Pide las tareas en español y con la ruta del archivo
> cambia la validación de src/api/user.ts a zod y arregla los tests

# 4. Para tareas que tocan muchos archivos: Shift+Tab activa el modo plan

O Claude Code pede sua permissão antes de editar um arquivo ou executar um comando; se ele estiver seguindo pelo caminho errado, pressione Esc para interrompê-lo e /rewind para voltar a um ponto anterior. O CLAUDE.md que /init gera é um rascunho: mantenha nele o que você repetiria em todas as sessões (comandos de teste, convenções, pastas que não devem ser tocadas). Ele é carregado em cada sessão e enviado em cada requisição, e a Anthropic recomenda não ultrapassar 200 linhas.

• Trocar de modelo: /model seguido do nome completo, por exemplo /model claude-opus-5, ou inicie com claude --model claude-opus-5. Faça isso entre tarefas: cada modelo tem seu próprio cache, e trocar no meio de uma tarefa obriga a reler toda a conversa sem cache.
• /clear entre tarefas sem relação. Comece uma nova conversa; isso não custa nada. A anterior pode ser recuperada com /resume.
• /compact quando uma tarefa se prolongar: resuma o histórico e continue. Com uma chave de API, o cache dura cinco minutos por padrão; portanto, compacte antes de uma pausa longa, não depois.
• Quanto custa uma sessão: /usage mostra os tokens, mas o valor que calcula é uma estimativa local pelo preço de tabela da Anthropic; com a Kunavo, a cobrança real está na sua página de uso.

Pagamento e transparência sobre a escolha

O saldo é pré-pago por meio da Stripe: cartão (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay ou Link; o débito direto SEPA não está disponível. A recarga mínima é de $10, o saldo não expira, as solicitações com falha não são cobradas e cada chave aceita um limite de gastos mensal. Todas as tarifas estão na página de preços.

Se você usa o Claude Code muitas horas por dia, a taxa fixa de uma assinatura costuma sair mais barata; o pagamento conforme o uso compensa quando o uso é irregular ou você não quer depender da janela de 5 horas, e um mês sem atividade custa zero. A comparação completa, em inglês, está em Claude Code pricing. Pela Kunavo, você usa capacidade compartilhada, sem capacidade dedicada nem SLA contratual: se precisar dessas garantias, contrate diretamente com a Anthropic.

Perguntas frequentes