Instalar o Claude Code: Native vs npm, Ajuste de PATH e Primeiro Uso

Para uma instalação nativa (Native Install) do Claude Code, o ambiente de execução do Node.js não é necessário. O instalador do npm atualmente requer o Node.js 22+, mas o próprio binário instalado opera de forma independente do runtime do Node. A documentação oficial da Anthropic recomenda explicitamente o Native Install (para mais detalhes, consulte o guia de instalação). Para utilizar o agente de programação no terminal, o desenvolvedor precisa escolher um método de instalação, executar o comando no shell apropriado e garantir que o executável seja localizado corretamente pelo sistema operacional. Quando surgem erros na chamada do comando, identificar a causa depende de distinguir a distribuição nativa autônoma da instalação via gerenciador de pacotes.

Native vs npm: limites da escolha e o papel do Node.js

A documentação oficial da Anthropic recomenda o Native Install (guia de instalação). Nessa opção, o runtime do Node.js é dispensável: o instalador baixa um binário pré-compilado e autônomo que não interage com o Node durante a sua execução.

A instalação via pacote global npm permanece como alternativa viável. Atualmente, o instalador do npm exige o Node.js 22 ou superior. Caso a instalação seja executada em uma versão anterior do Node.js, o npm emitirá um alerta EBADENGINE, mas o processo normalmente é concluído: o pacote baixa o binário pré-compilado específico da plataforma e cria um link para ele. Em tempo de execução, o binário instalado do Claude Code também não é executado dentro do Node.js.

Portanto, a afirmação de que o Claude Code sempre exige o Node.js é tecnicamente incorreta. Verificar a versão do Node.js só é necessário quando você opta intencionalmente pela instalação via npm.

Comandos de instalação para sistemas suportados

Para realizar a instalação correta, utilize os scripts oficiais de acordo com seu sistema operacional e shell em uso.

macOS, Linux e WSL (Bash / Zsh)

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows Prompt de Comando (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Instalação alternativa via npm

npm install -g @anthropic-ai/claude-code

Importante: Não execute o comando com sudo npm install -g. O uso de privilégios de superusuário gera conflitos de permissões em arquivos no diretório pessoal (home) e introduz riscos de segurança.

Na plataforma Windows nativa, a presença do Git for Windows agora é opcional. Se o Git for Windows estiver instalado, o agente poderá executar comandos Bash por meio do Git Bash; se o utilitário não estiver instalado, o Claude Code recorrerá à sua ferramenta integrada no PowerShell.

Verificação da instalação

Após a conclusão do script, confirme se o arquivo binário está acessível no sistema:

claude --version

A saída correta da versão confirma que o binário foi baixado, extraído e registrado no ambiente. Observe que a exibição bem-sucedida da versão valida apenas a integridade do executável; isso não significa que o cliente esteja autenticado ou apto a enviar requisições ao modelo.

Para uma auditoria detalhada do ambiente, execute o utilitário de diagnóstico:

claude doctor

O comando claude doctor realiza uma verificação do ambiente local: ele checa arquivos de configuração, permissões do sistema de arquivos e dependências do sistema, identificando eventuais problemas de configuração sem iniciar uma sessão interativa de código.

Diagnóstico: o que fazer em caso de erro command not found

Se o terminal relatar que o comando claude não foi encontrado (ou se o Windows exibir uma mensagem informando que o comando não é reconhecido como interno ou externo), siga este fluxo de diagnóstico:

[Ошибка вызова: claude не найден]
         │
         ▼
[Шаг 1: Открыть новый сеанс терминала]
         │
    Помогло? ──Да──> Завершено
         │ Нет
         ▼
[Шаг 2: Проверить физическое наличие бинарного файла на диске]
         │
    Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку
         │ Да
         ▼
[Шаг 3: Проверить тип установки и PATH]
         │
 ┌───────┴────────────────────────┐
 ▼                                ▼
[Native Install]                [npm Install]
Проверить PATH:                 Проверить PATH через npm prefix -g:
- Unix: ~/.local/bin            - Unix: <prefix>/bin
- Win: %USERPROFILE%\.local\bin - Win: <prefix>
(Не переустанавливать только из-за PATH)

A árvore de decisão acima organiza a sequência de etapas diagnósticas:

• Erro inicial: [Ошибка вызова: claude не найден] traduz-se como [Erro de invocação: claude não encontrado].
• Passo 1: [Шаг 1: Открыть новый сеанс терминала] instrui a abrir uma nova sessão de terminal. Se isso resolver a falha (Помогло? ──Да──> Завершено / Ajudou? ──Sim──> Concluído), o procedimento está encerrado. Se não resolver (Нет / Não), siga para o Passo 2.
• Passo 2: [Шаг 2: Проверить физическое наличие бинарного файла на диске] orienta a checar a presença física do executável no disco. Se o arquivo estiver ausente (Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку / Arquivo encontrado? ──Não──> Erro de download/permissões; repetir instalação), execute o script de instalação novamente. Se o arquivo estiver presente (Да / Sim), passe para o Passo 3.
• Passo 3: [Шаг 3: Проверить тип установки и PATH] avalia o tipo de instalação e as variáveis de ambiente:
  • Para o Native Install, verifique o PATH (Проверить PATH:): ~/.local/bin no Unix/macOS/WSL ou %USERPROFILE%\.local\bin no Windows.
  • Para o npm Install, consulte o PATH via npm prefix -g (Проверить PATH через npm prefix -g:): <prefix>/bin no Unix ou <prefix> no Windows.
  • A recomendação final (Не переустанавливать только из-за PATH) reforça: (Não reinstale apenas por causa de falhas no PATH).

1. Abra uma nova sessão de terminal

Os scripts de instalação aplicam modificações nos arquivos de configuração do shell (.bashrc, .zshrc) ou nas variáveis de ambiente do usuário no Windows. Janelas de terminal abertas anteriormente não reconhecem essas alterações imediatamente. Feche a sessão atual por completo e abra um novo terminal.

2. Verifique o caminho físico do arquivo

No Native Install, o executável é posicionado por padrão nos seguintes diretórios (salvo se houver definições personalizadas no ambiente):

• no macOS, Linux e WSL: ~/.local/bin/claude (os pacotes versionados ficam em ~/.local/share/claude);
• no Windows: %USERPROFILE%\.local\bin\claude.exe.

Esses caminhos são os padrões do sistema, e não locais imutáveis caso existam substituições configuradas pelo usuário. Se o arquivo não estiver no diretório esperado, o instalador pode ter falhado devido a instabilidades de rede ou permissões de gravação insuficientes.

3. Execute comandos de diagnóstico no shell

Para averiguar como o shell localiza o binário, recorra aos comandos padrão do sistema:

• no Zsh / Bash: execute command -v claude ou type -a claude;
• no PowerShell: execute Get-Command claude e também where.exe claude;
• no CMD: utilize o comando where claude.

4. Separe a resolução do PATH entre Native e npm

Um erro frequente ao solucionar problemas é tentar corrigir caminhos do Node.js diante de uma falha no Native Install.

• Caso tenha utilizado o Native Install, os diretórios do Node.js e a saída de npm prefix -g não têm relação com a falha. O caminho que precisa constar na variável PATH é ~/.local/bin (em sistemas Unix) ou %USERPROFILE%\.local\bin (no Windows).
• Para a instalação via npm install -g, o diretório de executáveis é determinado por npm prefix -g:
  • em sistemas Unix-like (macOS, Linux, WSL), o executável fica em <prefix>/bin;
  • no Windows, o executável fica diretamente na raiz de <prefix>. Comandos como npm bin -g e npm root -g não indicam o diretório correto dos executáveis.

Se o binário estiver presente no disco, mas o comando não for reconhecido, avalie primeiro o PATH e a resolução do shell. Se a execução pelo caminho absoluto também falhar, analise a mensagem de erro exata e verifique o guia oficial de solução de problemas: permissões de execução, compatibilidade do binário com a plataforma ou downloads incompletos podem demandar ajustes. Não reinstale às cegas apenas por causa de uma mensagem de command not found.

Primeira execução e exploração segura

Após confirmar que o comando está acessível, acesse o diretório de um projeto pequeno de teste e inicie a sessão:

cd /path/to/test-project
claude

Na primeira inicialização, a interface solicitará a conclusão do processo padrão de autenticação pelo navegador. Dentro de uma sessão ativa, o comando /status permite inspecionar o diretório de trabalho atual, o identificador da conta e o modelo selecionado.

Para o primeiro contato, execute um exercício introdutório sem comandos destrutivos:

Объясни назначение основных файлов в проекте. Не изменяй файлы, не устанавливай зависимости и не выполняй команды в терминале.

(Tradução do prompt de teste: “Explique a finalidade dos principais arquivos do projeto. Não altere arquivos, não instale dependências e não execute comandos no terminal.”)

A resposta esperada é que o agente liste os arquivos principais e esclareça suas funções, sem gerar diffs nem aplicar modificações no código. Ao concluir a tarefa, execute git diff em outro terminal para verificar se o repositório permaneceu intacto.

É essencial destacar: uma instrução textual no prompt representa apenas uma orientação em linguagem natural fornecida ao modelo, e não um modo de execução forçado (enforced mode) ou sandbox no nível do sistema operacional. Caso o repositório exija restrições contra modificações automáticas, ative o modo de planejamento:

claude --permission-mode plan

No modo plan, o agente por padrão apenas lê arquivos e utiliza comandos de shell em modo somente leitura, sem alterar o código-fonte. Contudo, esse modo não atua como um sandbox isolado no nível do sistema operacional: quando a execução automática está habilitada, comandos previamente aprovados pelo classificador ainda podem ser acionados (não presuma isolamento rígido de sistema; dados confirmados pela documentação em 2026-09-15).

A relação detalhada das políticas de permissão está disponível no guia de permissões. Para encerrar a sessão interativa, utilize o atalho Ctrl+D.

Conectando um provedor de API independente

A instalação do utilitário de terminal e a configuração posterior do provedor de modelos são etapas operacionais distintas. Caso prefira utilizar um gateway independente compatível com a API da Anthropic em vez da autenticação direta padrão, os parâmetros de acesso são ajustados separadamente após confirmar o funcionamento da CLI.

Nesse contexto, o provedor independente BetterToken disponibiliza chaves de acesso personalizadas (API Key), com acompanhamento de volume de requisições, consumo de tokens e faturamento por meio do painel Dashboard. As instruções para exportar as variáveis de ambiente necessárias e configurar o endereço base da API podem ser consultadas na documentação do BetterToken sobre o Claude Code. Os procedimentos de download, atualização e execução local do próprio binário continuam sendo realizados pelos utilitários padrão da CLI, conforme detalhado neste guia.