Tutorial de instalação do Claude Code — comandos para macOS e Windows; depois conecte-se com assinatura ou chave de API

A instalação do Claude Code exige apenas um comando: no macOS, Linux e 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 install.cmd abaixo). Depois da instalação, abra um novo terminal, use claude --version para confirmar e execute claude para começar. Na primeira conexão, há duas opções: entrar com uma conta Pro, Max, Team, Enterprise ou Console (o plano gratuito Claude.ai não inclui o Claude Code) ou definir as duas variáveis de ambiente ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN, usando uma chave de API cobrada conforme o uso, sem precisar de assinatura.

Comandos verificados em 11 de setembro de 2026, com base na documentação oficial de instalação da Anthropic. Esta página trata apenas da instalação e da primeira conexão; para o uso diário depois da instalação, consulte o tutorial do Claude Code.

Verifique antes de instalar

Instalação no macOS

Abra o “Terminal” e cole esta linha:

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

Esta é a forma nativa de instalação recomendada oficialmente: ela instala um executável independente, que se atualiza automaticamente em segundo plano. O ponto de entrada do executável fica em ~/.local/bin/claude; terminais que já estavam abertos não leem o novo PATH, então abra uma nova janela depois da instalação. Linux e WSL usam a mesma linha de comando.

Instalação no Windows

O Windows tem duas linhas de comando diferentes; a diferença depende apenas do terminal aberto. Se o prompt for PS C:\Users\你的名字>, é PowerShell; se não houver PS e houver apenas C:\Users\你的名字>, é o Prompt de Comando (CMD). Não é necessário executar como administrador.

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

:: Windows 命令提示字元（CMD）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Colar no lugar errado é a falha mais comum no Windows. Se você executar a linha do CMD no PowerShell, verá The token '&&' is not a valid statement separator; se executar a linha do PowerShell no CMD, verá 'irm' is not recognized as an internal or external command. Se colar o curl … | bash do macOS no PowerShell, aparecerá A parameter cannot be found that matches parameter name 'fsSL'. Nos três casos, basta voltar à linha correspondente.

Recomendamos instalar também o Git for Windows: o Claude Code usará o Git Bash incluído nele para executar comandos; se não estiver instalado, usará o PowerShell. Se você instalou o Git Bash, mas ele não foi encontrado, adicione CLAUDE_CODE_GIT_BASH_PATH ao bloco env do arquivo de configuração, apontando para o caminho de bash.exe.

Se escolher o WSL, execute a linha acima do macOS／Linux no terminal do WSL e inicie o claude também no WSL, não no PowerShell ou CMD.

Instalação com um gerenciador de pacotes

Também é possível deixar um gerenciador de pacotes existente fazer o gerenciamento, mas o custo é que por padrão nada será atualizado automaticamente; você precisará atualizar regularmente por conta própria (por exemplo, brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Debian／Ubuntu, Fedora／RHEL e Alpine têm repositórios apt, dnf e apk oficiais e assinados.

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

A instalação via npm exige Node.js 22 ou superior desde a v2.1.198; se a versão do Node.js for mais antiga, o npm apenas imprime o aviso EBADENGINE, mas a instalação ainda é concluída. O que ele instala é o mesmo executável do instalador nativo, que não depende do Node.js durante a execução. Nunca use sudo npm install -g: isso causa problemas de permissão e também apresenta riscos de segurança.

Verificar se a instalação foi bem-sucedida

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

Vale lembrar de claude doctor: ele não inicia uma sessão de trabalho; apenas lista o estado da instalação, erros no arquivo de configuração e correções sugeridas. É a forma mais rápida de distinguir entre “a instalação está quebrada” e “a configuração está quebrada”.

Se aparecer command not found: claude ou, no Windows, 'claude' is not recognized, significa que o diretório de instalação não está no PATH. No macOS／Linux, abra primeiro um novo terminal e tente novamente; se ainda não funcionar, adicione ~/.local/bin ao PATH de ~/.zshrc ou ~/.bashrc. O local de instalação no Windows é %USERPROFILE%\.local\bin; verifique e adicione usando o PowerShell:

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

Primeira conexão: login com assinatura ou chave com cobrança por uso

Caminho A: entrar com uma conta de assinatura

Execute claude na pasta do projeto e siga as instruções do navegador para entrar com uma conta Pro, Max, Team, Enterprise ou Console. Observe um detalhe: se ANTHROPIC_API_KEY já estiver presente no ambiente, o Claude Code perguntará uma vez se você quer usar essa chave; se você escolher recusá-la, ele passará a ignorá-la silenciosamente e não perguntará novamente, dando a impressão de que a variável não foi lida. Para reativá-la, acesse /config e selecione Use custom API key.

Caminho B: sem assinatura, usando uma chave com cobrança por uso

O Claude Code oferece suporte nativo a ANTHROPIC_BASE_URL, portanto apontar para qualquer endpoint que forneça a Anthropic Messages API é uma configuração oficialmente compatível; não são necessários plug-ins, proxies ou executáveis modificados. As etapas são: criar uma conta, adicionar créditos (mínimo de $10), criar uma chave iniciada por sk-kn- na página de gerenciamento de chaves (ela será exibida apenas uma vez) e configurar as variáveis abaixo. macOS／Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只寫到網域，不要加 /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:

# 只對這個 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 contínuo, recomendamos gravar isso no bloco env do arquivo de configuração do usuário ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json). Escrito nesse local, será lido por todos os terminais, extensões do editor e processos em segundo plano; se o arquivo já tiver outras configurações, basta mesclar env nele:

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

Nestas seis linhas, cada uma tem um ponto cuja configuração incorreta pode causar problemas por muito tempo:

• ANTHROPIC_BASE_URL deve conter apenas o domínio. O Claude Code adicionará /v1/messages por conta própria; se você acrescentar /v1, o resultado será /v1/v1/messages e a resposta será 404.
• Use ANTHROPIC_AUTH_TOKEN, não ANTHROPIC_API_KEY. Os dois são enviados em cabeçalhos HTTP diferentes: o primeiro envia Authorization: Bearer e entra em vigor imediatamente; o segundo envia x-api-key e ainda exige a confirmação única mencionada acima.
• ANTHROPIC_MODEL deve conter o nome completo e correto do modelo. O Kunavo aceita apenas nomes que correspondam exatamente; ele não associa automaticamente nomes antigos com sufixo de data.
• ANTHROPIC_DEFAULT_OPUS_MODEL é responsável pelo alias opus. O modelo padrão do Claude Code e o alias opus apontam para o Opus mais recente; se a Kunavo ainda não oferecer esse modelo, isso resultará em 404. Portanto, esta linha e ANTHROPIC_MODEL também precisam ser fixadas. Aqui, o alias opus é fixado em Opus 5.5 (claude-opus-5-5), o que exige o Claude Code v2.1.280 ou posterior; em versões antigas, execute primeiro claude update.
• ANTHROPIC_DEFAULT_SONNET_MODEL é responsável pelo alias sonnet. Na Anthropic API, o alias sonnet aponta para Sonnet 5.5, mas a Kunavo não oferece esse modelo. Sem essa fixação, o /model sonnet, o runtime de opusplan e os subagentes configurados como model: sonnet retornarão 404. Portanto, aqui ele também é fixado como Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL controla as chamadas em segundo plano. Os resumos e títulos gerados pelo Claude Code usam este modelo: Claude Haiku 4.5 custa $0.70 / $3.50 por 1M de tokens; o modelo principal Claude Sonnet 5 custa $1.40 / $7.00 (o mesmo preço oficial da Anthropic).

Não coloque a chave em .claude/settings.json dentro do projeto — esse arquivo será incluído em commits e compartilhado com todas as pessoas que clonarem o projeto. Se usar a extensão do VS Code, coloque a variável em claudeCode.environmentVariables nas configurações do usuário do VS Code, porque a extensão verifica as credenciais antes de iniciar.

Confirmar qual caminho está conectado

Depois de entrar no Claude Code, execute /status. Se aparecer a linha Auth token, a chave está ativa; se aparecer Login method junto com uma conta claude.ai, significa que a variável não foi lida. As duas opções não se acumulam: enquanto a variável da chave existir, a assinatura conectada ficará suspensa; remova a variável para voltar à assinatura, sem reinstalar.

Ao usar um gateway, três coisas serão diferentes: Remote Control e entrada de voz exigem uma identidade claude.ai e não poderão ser usados; a verificação de disponibilidade de /fast consultará diretamente a Anthropic e poderá indicar que o recurso não está disponível, mas as solicitações comuns não serão afetadas; os valores de /context passarão a ser estimativas locais. Programação, ferramentas, subagentes, MCP, hooks e cache de prompts continuarão funcionando normalmente. A explicação completa está na documentação de integração do Claude Code e no guia de chaves de API do Claude Code (ambos em inglês).

Tabela de erros comuns

Depois da instalação

Ao entrar no projeto pela primeira vez, execute /init para que ele leia o projeto inteiro e gere CLAUDE.md. Depois, como alternar entre Opus, Sonnet e Haiku conforme a tarefa, quanto custa uma sessão de trabalho e como usar /clear e /compact para reduzir os custos estão no tutorial do Claude Code.

Também vale falar com franqueza sobre qual caminho escolher: para quem interage por longos períodos todos os dias e usa muito, a mensalidade fixa da assinatura geralmente é mais vantajosa; a cobrança por uso é adequada para quem tem consumo variável ou não quer ficar limitado por uma janela de uso de 5 horas; nos meses sem trabalho, o custo é $0. Ao usar o Kunavo, você utiliza capacidade compartilhada, sem cota dedicada e sem SLA contratual; equipes que precisam dessas garantias devem contratar diretamente a Anthropic. A mensalidade e o ponto de equilíbrio dos dois caminhos estão em Custos do Claude Code.

Perguntas frequentes