O Claude Code é instalado com um único comando em todas as plataformas compatíveis, e toda a primeira execução é: instalar, digitar claude, fazer login. Este guia traz o comando exato para cada sistema operacional, o que verificar quando algo não funciona e como apontá-lo para outro endpoint depois que funcionar.
Comandos verificados 3 de outubro de 2026 com base na documentação de configuração do Claude Code da Anthropic.
Antes de começar
| Requisito | Compatibilidade |
|---|---|
| Sistema operacional | macOS 13.0+, Windows 10 1809+ / Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+ |
| Hardware | 4 GB+ de RAM, x64 ou ARM64 |
| Shell | Bash, Zsh, PowerShell ou CMD |
| Rede | Conexão com a internet obrigatória |
| Conta | Pro, Max, Team, Enterprise ou Console — o plano gratuito do Claude.ai não inclui o Claude Code |
Instalação — o instalador nativo
Este é o método recomendado em todas as plataformas. Ele instala um binário autocontido e se mantém atualizado em segundo plano.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash# 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.cmdSe você não tiver certeza de qual shell do Windows está usando, o prompt informa: o PowerShell mostra PS C:\, o CMD mostra C:\ sem o PS. Executar o comando errado é a falha de instalação mais comum no Windows — consulte a tabela de solução de problemas abaixo para ver o erro exato em cada caso.
Gerenciadores de pacotes
Use-os se preferir que o gerenciador de pacotes existente controle a instalação. A desvantagem são as atualizações: nenhum deles é atualizado automaticamente por padrão, ao contrário do instalador nativo.
# Homebrew (macOS, Linux) — stable channel
brew install --cask claude-code
# WinGet (Windows)
winget install Anthropic.ClaudeCode
# npm — requires Node.js 22+; never with sudo
npm install -g @anthropic-ai/claude-codeO Homebrew publica dois casks: claude-code acompanha o canal estável (normalmente cerca de uma semana atrás, ignorando versões com regressões importantes) e claude-code@latest disponibiliza cada versão imediatamente. Existem repositórios apt, dnf e apk assinados para Debian / Ubuntu, Fedora / RHEL e Alpine, cada um com os mesmos canais stable e latest.
No npm, nunca use sudo npm install -g — isso causa problemas de permissão e representa um risco de segurança. O pacote npm instala exatamente o mesmo binário nativo do instalador independente, portanto não há dependência de Node em tempo de execução em nenhum dos casos.
Verifique a instalação
claude --version # prints e.g. "2.1.211 (Claude Code)"
claude doctor # read-only install + settings diagnostics
claude # start a session in the current projectclaude doctor é o comando que você deve lembrar: ele exibe a integridade da instalação, erros de validação dos arquivos de configurações e correções sugeridas sem iniciar uma sessão, sendo a maneira mais rápida de distinguir uma instalação quebrada de uma configuração quebrada.
Primeira execução e login
Abra um terminal no projeto em que deseja trabalhar e execute claude. Ele abre uma sessão interativa e orienta você no login pelo navegador. O Claude Code exige uma conta Pro, Max, Team, Enterprise ou Console.
Um comportamento que vale conhecer antes que ele surpreenda você: se ANTHROPIC_API_KEY já estiver definido no seu ambiente, o Claude Code solicitará uma vez que você aprove essa chave, em vez de abrir um navegador. Recuse esse aviso e a chave será ignorada silenciosamente dali em diante, sem novos avisos — o que parece exatamente que a variável não está sendo lida. Reative-a em /config → Use custom API key.
Windows: nativo ou WSL
| Opção | Exige | Sandbox | Escolha quando |
|---|---|---|---|
| Windows nativo | Nada; Git for Windows opcional | Não compatível | Seus projetos e ferramentas são nativos do Windows |
| WSL 2 | WSL 2 habilitado | Compatível | Toolchains Linux ou necessidade de execução de comandos em sandbox |
| WSL 1 | WSL 1 habilitado | Não compatível | O WSL 2 não está disponível para você |
No Windows nativo, instalar o Git for Windows é opcional, mas recomendado: ele fornece o Git Bash que sustenta a ferramenta Bash. Sem ele, o Claude Code executa comandos shell por meio da ferramenta PowerShell. No WSL, instale e inicie claude dentro do terminal do WSL, não no PowerShell.
Solução de problemas
| Sintoma | Causa e correção |
|---|---|
The token '&&' is not a valid statement separator | Você executou o comando do CMD no PowerShell. Use a linha irm … | iex. |
'irm' is not recognized… | O inverso — você executou o comando do PowerShell no CMD. Use a linha curl … install.cmd. |
syntax error near unexpected token '<', um 403 ou outro erro do curl | O download não retornou o script — normalmente por causa de um proxy ou filtro de rede entre você e o instalador. Tente novamente ou use uma instalação por gerenciador de pacotes. |
claude: command not found após uma instalação limpa | Abra um novo terminal para que o shell reconheça o diretório de instalação e execute claude doctor. Uma segunda instalação mais antiga ou um alias de shell obsoleto é a outra causa comum. |
| Erros de permissão durante uma instalação via npm | Você usou sudo ou o diretório global do npm não permite escrita. Corrija a propriedade do diretório em vez de executar novamente com sudo; um diretório global sem permissão de escrita também impede a atualização automática. |
Binário nativo ausente após npm install -g | Seu gerenciador de pacotes está configurado para ignorar dependências opcionais. O binário da plataforma é fornecido como uma delas, portanto permita-as e reinstale. |
| A instalação falha no Alpine ou em outra distribuição musl | O Alpine vem sem bash e curl. Instale bash curl libgcc libstdc++ ripgrep e defina USE_BUILTIN_RIPGREP como "0" no bloco env do seu arquivo de configurações. |
| A pesquisa e a descoberta de arquivos falham | O ripgrep normalmente vem incluído. Se não puder ser executado na sua plataforma, instale o ripgrep do sistema e defina USE_BUILTIN_RIPGREP=0. |
| Ferramenta Bash ausente no Windows nativo | Instale o Git for Windows. Se o Claude Code ainda não encontrar o Git Bash, defina CLAUDE_CODE_GIT_BASH_PATH no bloco env de ~/.claude/settings.json. |
401 depois que uma chave for configurada | A chave está no cabeçalho que o servidor não lê — alterne entre ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY. Consulte os detalhes no guia de chaves de API. |
Apontando o Claude Code para a Kunavo
Depois que estiver em execução, o Claude Code funcionará com qualquer endpoint que ofereça a Anthropic Messages API — ele lê ANTHROPIC_BASE_URL nativamente, portanto esta é uma configuração compatível, não uma solução alternativa. Sem plugin, sem proxy, sem binário modificado:
export ANTHROPIC_BASE_URL=https://api.kunavo.com
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-5Cinco coisas sobre esse bloco, cada uma capaz de custar uma hora se você errar:
ANTHROPIC_BASE_URLé apenas a origem. O Claude Code acrescenta/v1/messagespor conta própria — incluir o caminho resulta em um 404.- Use
ANTHROPIC_AUTH_TOKEN, nãoANTHROPIC_API_KEY. Eles vão em cabeçalhos HTTP diferentes. O token bearer entra em vigor imediatamente, enquantoANTHROPIC_API_KEYprecisa da aprovação única descrita acima. A Kunavo lê a chave de qualquer um dos dois cabeçalhos, incluindo/v1/models, portanto, na Kunavo, essa etapa de aprovação é o que os diferencia. - Defina
ANTHROPIC_MODELexplicitamente. A Kunavo corresponde exatamente aos slugs dos modelos e não cria aliases para nomes com sufixo de data, portantoclaude-sonnet-4-5-20250929retorna 404, enquantoclaude-sonnet-5funciona. - Defina também
ANTHROPIC_DEFAULT_OPUS_MODELeANTHROPIC_DEFAULT_SONNET_MODEL. O padrão integrado do Claude Code e seu aliasopusresolvem ambos para o Opus mais novo e, se a Kunavo ainda não oferecer esse modelo, a primeira solicitação retornará 404. O bloco fixaopusno Opus 5.5 (claude-opus-5-5), que requer o Claude Code v2.1.280 ou posterior — executeclaude updateem uma instalação mais antiga. O aliassonnetsolicita o Sonnet 5.5, que a Kunavo não oferece; portanto, sem a fixação do sonnet/model sonnet, a fase de execução deopusplane qualquer subagente definido comomodel: sonnetretornam 404. ANTHROPIC_DEFAULT_HAIKU_MODELcobre as chamadas em segundo plano que o Claude Code faz por conta própria para resumos e títulos.claude-haiku-4-5custa $0.70 / $3.50 por 1M contra $1.40 / $7.00 para o modelo principal, portanto é uma linha que gera economia permanente.
Coloque-os no bloco env de ~/.claude/settings.json em vez de exportá-los no shell se quiser que editores e agentes em segundo plano também os vejam — e nunca no .claude/settings.json versionado de um projeto. Crie a chave sk-kn- no painel depois de se cadastrar; um carregamento de $10 é o mínimo, não há tarifa mensal e o saldo não expira. O custo de cada modelo por token, comparado aos preços oficiais da API da Anthropic, determina até onde esses $10 chegam.
O que muda atrás de um gateway
Codificação, ferramentas, subagentes, MCP, hooks e cache de prompts não são afetados. Três coisas mudam, e vale conhecê-las antes de presumir que algo está quebrado:
- Remote Control e ditado por voz ficam indisponíveis. Ambos precisam de uma identidade claude.ai, que uma credencial de gateway substitui.
/fastpode informar que o modo rápido está desativado. A verificação de disponibilidade chama a Anthropic diretamente, em vez de seguir sua base URL. As solicitações normais não são afetadas.- As contagens de
/contexttornam-se estimativas locais. A contagem de tokens é o único endpoint que a especificação do gateway da Anthropic marca como opcional, e o Claude Code estima localmente quando ele está ausente — a Kunavo não oferece/v1/messages/count_tokensatualmente. A compactação automática e a própria sessão não são afetadas.
A lista completa, além da decisão entre roteador e ausência de roteador, está no guia do roteador do Claude Code.
Perguntas frequentes
Como instalo o Claude Code?
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, ou `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` no CMD. O instalador nativo é o método recomendado e se mantém atualizado em segundo plano. Homebrew (`brew install --cask claude-code`), WinGet (`winget install Anthropic.ClaudeCode`), npm e repositórios apt/dnf/apk assinados também são compatíveis, mas nenhum deles é atualizado automaticamente por padrão.
Preciso do Node.js para instalar o Claude Code?
Não para o instalador nativo, Homebrew, WinGet ou os repositórios de pacotes Linux — todos instalam um binário nativo que não usa Node em tempo de execução. Somente o caminho de instalação via npm envolve Node e, a partir da v2.1.198, esse pacote exige Node.js 22 ou posterior. Mesmo assim, o npm apenas instala o mesmo binário nativo por meio de uma dependência opcional específica da plataforma.
Quais são os requisitos de sistema do Claude Code?
macOS 13.0+, Windows 10 1809+ ou Windows Server 2019+, Ubuntu 20.04+, Debian 10+ ou Alpine Linux 3.19+; 4 GB ou mais de RAM em um processador x64 ou ARM64; conexão com a internet; e Bash, Zsh, PowerShell ou CMD como shell. Você também deve estar em um país compatível com a Anthropic.
Como faço login no Claude Code pela primeira vez?
Execute `claude` em um diretório de projeto e siga as instruções no navegador. O Claude Code exige uma conta Pro, Max, Team, Enterprise ou Console — o plano gratuito do Claude.ai não inclui acesso ao Claude Code. Se a variável de ambiente ANTHROPIC_API_KEY estiver definida, o Claude Code solicitará uma vez que você aprove essa chave, em vez de abrir um navegador.
Posso instalar o Claude Code no Windows sem WSL?
Sim. Execute o instalador do PowerShell ou CMD e inicie `claude` em qualquer terminal; você não precisa de direitos de Administrador. O Git for Windows é opcional, mas recomendado, pois fornece o Git Bash que sustenta a ferramenta Bash — sem ele, o Claude Code executa comandos shell por meio da ferramenta PowerShell. O WSL 2 é a opção a escolher se você quiser toolchains Linux ou execução de comandos em sandbox, algo que o Windows nativo não oferece.
Por que `claude` diz “command not found” depois da instalação?
O diretório de instalação não está no seu PATH no shell que você está usando. Abra primeiro um novo terminal — o instalador adiciona ~/.local/bin no macOS e Linux, e uma sessão existente não reconhecerá isso. Execute `claude doctor` para obter diagnósticos somente de leitura da instalação e dos arquivos de configurações. Uma segunda instalação mais antiga ou um alias de shell remanescente é a outra causa comum.
Como aponto o Claude Code para um endpoint de API diferente?
Defina ANTHROPIC_BASE_URL como a origem de qualquer endpoint que ofereça a Anthropic Messages API — o Claude Code lê essa variável nativamente e acrescenta /v1/messages sozinho, portanto nenhum plugin ou proxy é usado. Combine-a com ANTHROPIC_AUTH_TOKEN para a credencial e com um ANTHROPIC_MODEL explícito; defina ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_DEFAULT_HAIKU_MODEL como modelos oferecidos pelo endpoint, pois os aliases opus e sonnet seguem, caso contrário, os modelos mais novos da Anthropic. Na Kunavo, isso executa os mesmos modelos Claude por 30% do preço de tabela da Anthropic, no modelo pay-as-you-go.
Próximos passos
- Chave de API do Claude Code — onde obter uma, onde colocá-la e a incompatibilidade de cabeçalhos por trás da maioria dos 401.
- Preços do Claude Code — assinatura versus API, tarifas por modelo e quanto custa um mês.
- O Claude Code é gratuito? — o que é gratuito, o que não é e onde está a linha divisória.
- Executando sem avisos de permissão — o que
--dangerously-skip-permissionsrealmente remove e três contenções que levam cerca de um minuto cada. - Claude Code versus Codex CLI — se você ainda está escolhendo um agente de terminal.