Como Instalar e Configurar o Claude Code do Zero

Você já sabe o que o Claude Code faz — transforma comandos em linguagem natural em código real, direto no seu terminal. Agora é hora de colocar essa ferramenta para rodar na sua máquina. E o processo, apesar de simples, tem detalhes que podem travar sua instalação se você pular etapas.

Este guia cobre cada passo necessário para instalar o Claude Code, configurar credenciais, ajustar o ambiente e executar seu primeiro comando com sucesso. Funciona para Windows, Mac e Linux — e inclui os erros mais comuns que travam iniciantes logo nos primeiros minutos.

Requisitos mínimos para rodar o Claude Code

Antes de abrir o terminal e digitar qualquer comando, confirme que sua máquina atende aos pré-requisitos. Ignorar essa etapa é o motivo número um de falhas na instalação.

Hardware e sistema operacional

O Claude Code roda no terminal, então não exige uma máquina potente. Porém, como ele interage com o sistema de arquivos e executa operações em tempo real, há um mínimo necessário:

Software obrigatório

O Claude Code depende de duas ferramentas que precisam estar instaladas antes de tudo:

• Node.js 18 ou superior — O Claude Code é distribuído como pacote npm. Sem o Node.js, nada funciona.
• Git — Necessário para controle de versão e para que o Claude Code interaja com repositórios.

Para verificar se já estão instalados, abra o terminal e rode:

node --version
git --version

Se ambos retornarem números de versão, você está pronto para avançar. Se não, instale-os antes de continuar.

Conta na Anthropic

Você precisa de uma conta ativa na Anthropic com acesso à API. O Claude Code consome créditos da API a cada interação, então tenha um plano ativo ou créditos disponíveis antes de começar.

Instalação do Claude Code no Windows, Mac e Linux

Com os pré-requisitos confirmados, vamos à instalação propriamente dita. O processo é praticamente idêntico nos três sistemas — a diferença está na preparação do ambiente.

Instalação no macOS

1. Abra o Terminal (Cmd + Espaço, digite “Terminal”)
2. Certifique-se de que o Node.js está atualizado:

node --version

3. Instale o Claude Code globalmente via npm:

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

4. Confirme a instalação:

claude --version

Se o terminal retornar o número da versão, a instalação foi bem-sucedida.

Instalação no Linux (Ubuntu/Debian)

1. Abra o terminal
2. Atualize o npm para evitar conflitos de permissão:

sudo npm install -g npm@latest

3. Instale o Claude Code:

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

4. Verifique:

claude --version

Instalação no Windows (via WSL2)

O Windows exige uma etapa extra. Se você ainda não tem o WSL2:

1. Abra o PowerShell como administrador e rode:

wsl --install

2. Reinicie o computador
3. Abra o terminal do Ubuntu (instalado pelo WSL2)
4. Instale o Node.js dentro do WSL2:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

5. Instale o Claude Code:

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

6. Confirme:

claude --version

Configuração de credenciais e autenticação

Instalar o Claude Code é metade do caminho. Sem autenticação, ele não consegue se comunicar com os servidores da Anthropic. Existem duas formas de configurar suas credenciais.

Método 1: Login interativo (recomendado para iniciantes)

A forma mais simples é usar o login interativo. No terminal, digite:

claude

Na primeira execução, o Claude Code detecta que não há credenciais configuradas e abre um fluxo de autenticação no navegador. Você faz login com sua conta Anthropic, autoriza o acesso e o token é salvo automaticamente no seu ambiente local.

Método 2: Chave de API via variável de ambiente

Para quem prefere controle manual — ou precisa usar o Claude Code em scripts e automações — a alternativa é configurar a chave de API diretamente:

1. Acesse o console da Anthropic e gere uma API key
2. No terminal, exporte a variável:

export ANTHROPIC_API_KEY="sua-chave-aqui"

3. Para tornar permanente, adicione a linha acima ao seu arquivo de perfil do shell:

# Para Bash
echo 'export ANTHROPIC_API_KEY="sua-chave-aqui"' >> ~/.bashrc
source ~/.bashrc

# Para Zsh
echo 'export ANTHROPIC_API_KEY="sua-chave-aqui"' >> ~/.zshrc
source ~/.zshrc

Verificando a autenticação

Depois de configurar as credenciais por qualquer um dos métodos, teste com:

claude "diga olá"

Se o Claude responder no terminal, sua autenticação está funcionando corretamente.

Rodando o primeiro comando no Claude Code

Com tudo instalado e autenticado, é hora de ver o Claude Code em ação. Vamos fazer isso da forma correta — dentro de um projeto real.

Criando um projeto de teste

mkdir meu-projeto-teste
cd meu-projeto-teste
git init

O Claude Code funciona melhor dentro de repositórios Git, pois usa o contexto do projeto para entender a estrutura de arquivos e tomar decisões mais inteligentes.

Iniciando o modo interativo

Digite simplesmente:

claude

Isso abre o modo interativo, onde você conversa com o Claude diretamente no terminal. A partir daqui, você pode fazer pedidos como:

> Crie um servidor Express.js básico com uma rota GET que retorna "Hello World" na porta 3000

O Claude Code vai:

1. Criar os arquivos necessários (como server.js e package.json)
2. Escrever o código
3. Pedir sua confirmação antes de salvar as alterações
4. Opcionalmente, rodar o projeto para testar

Modo de comando único

Se você não quer entrar no modo interativo, pode passar instruções diretamente:

claude "crie um arquivo README.md descrevendo este projeto como uma API REST em Node.js"

O Claude executa a tarefa e retorna ao prompt normal do terminal.

Entendendo as permissões

Por padrão, o Claude Code pede confirmação antes de executar ações que modificam arquivos ou rodam comandos no sistema. Isso é uma camada de segurança. Nas primeiras interações, leia cada solicitação de permissão com atenção para entender o que está sendo feito.

Você pode ajustar o nível de permissão com flags:

claude --allowedTools "Edit,Bash(npm install)" "configure o projeto"

Isso permite que o Claude edite arquivos e rode npm install sem pedir confirmação a cada vez.

Erros comuns na instalação e como resolver

Mesmo seguindo cada passo, problemas acontecem. Aqui estão os erros mais frequentes e suas soluções diretas.

Erro: “command not found: claude”

Causa: O npm instalou o pacote, mas o diretório global de binários não está no PATH do sistema.

Solução:

# Descubra onde o npm instala pacotes globais
npm config get prefix

# Adicione o diretório bin ao PATH
export PATH="$(npm config get prefix)/bin:$PATH"

Adicione essa linha ao seu .bashrc ou .zshrc para tornar permanente.

Erro: “EACCES: permission denied”

Causa: O npm não tem permissão para instalar pacotes globais no diretório padrão.

Solução (sem usar sudo permanentemente):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Depois, reinstale o Claude Code sem sudo:

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

Erro: “Node.js version not supported”

Causa: Sua versão do Node.js é anterior à 18.

Solução: Atualize o Node.js. A forma mais prática é usar o nvm (Node Version Manager):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

Erro: “Authentication failed” ou “Invalid API key”

Causa: A chave de API está incorreta, expirada ou não foi exportada corretamente.

Solução:

1. Verifique se a variável existe: echo $ANTHROPIC_API_KEY
2. Se retornar vazio, exporte novamente
3. Gere uma nova chave no console da Anthropic se necessário
4. Confirme que não há espaços extras ou aspas incorretas na chave

Erro: WSL2 não reconhece o comando npm

Causa: O Node.js foi instalado no Windows, não dentro do WSL2.

Solução: Instale o Node.js diretamente no ambiente Linux do WSL2, conforme descrito na seção de instalação para Windows acima. As instalações do Windows e do WSL2 são ambientes separados.

Próximos passos após a instalação

Com o Claude Code instalado, autenticado e funcionando, o próximo passo natural é aprender os comandos que vão multiplicar sua produtividade. Saber pedir da forma certa faz diferença enorme na qualidade do código gerado.

Também vale configurar o ambiente de desenvolvimento com extensões de editor, aliases de terminal e arquivos de configuração do projeto (como o CLAUDE.md) que dão contexto adicional ao Claude sobre seu projeto específico.

A instalação é apenas o ponto de partida. A partir daqui, cada interação com o Claude Code vai te ensinar a formular pedidos melhores e a integrar a ferramenta no seu fluxo de trabalho diário.

Artigos relacionados

• Claude Code – Guia Completo para Criar Projetos com IA
• Comandos Essenciais do Claude Code para Produtividade
• Como Configurar o Ambiente Ideal para Claude Code
• Claude Code — Erros de Instalação e Como Resolver

Bruno Bracaioli

Empreendedor e Desenvolvedor

Bruno Bracaioli é especialista em arquitetura de software, ciência de dados e cybersecurity. Além disso, investe em criptomoedas e em investimentos tradicionais como CDBs, Ações, Tesouro e outros. É influenciador digital no instagram (@brunobracaioli) e no Youtube (/brunobracaioli). Contato por: bruno@bracaiolitech.com ou pelo bruno@b2tech.com