💻 Instalação do Claude Code

Conjunto de ferramentas necessárias antes de instalar o Claude Code: Node.js na versão 18 ou superior, o gerenciador npm, e um terminal como PowerShell ou cmd.

Sem esses pré-requisitos, a instalação falha. Verificar e instalar corretamente evita erros comuns e garante uma base sólida.

Node.js versão mínima 18, npm incluído no instalador do Node.js, PowerShell recomendado para comandos de variáveis de ambiente.

Processo de instalar o Node.js no Windows via instalador gráfico em nodejs.org ou via winget no PowerShell. Inclui configuração automática do PATH.

O Claude Code é um pacote npm. Sem Node.js instalado e configurado corretamente no PATH, o comando npm não será reconhecido pelo sistema.

LTS vs Current (usar LTS), verificação com node -v e npm -v, instalação via winget como alternativa moderna.

Instalação global do pacote Claude Code via npm. O flag -g instala o comando claude disponível em qualquer diretório do sistema.

A instalação global permite usar o Claude Code em qualquer projeto sem configuração adicional. Um único comando configura a ferramenta para todo o sistema.

Flag -g para instalação global, pacote @anthropic-ai/claude-code, possível necessidade de rodar como administrador no Windows.

Configuração de variáveis de ambiente persistentes no Windows usando o comando setx no PowerShell, diferente do set que é temporário.

Variáveis como ANTHROPIC_AUTH_TOKEN precisam estar disponíveis sempre. Com set elas somem ao fechar o terminal.

setx para persistência, diferença entre set (temporário) e setx (permanente), necessidade de reabrir o terminal após setx.

Processo de autenticação ao executar o Claude Code pela primeira vez. Pode ser via API key direta, login no Anthropic Console via browser, ou configuração de provedor alternativo.

A autenticação correta define qual serviço será usado (Anthropic direto, OpenRouter, Ollama local). Escolher o método errado resulta em erros de conexão.

API key via variável de ambiente, login interativo via browser, variáveis ANTHROPIC_AUTH_TOKEN e ANTHROPIC_BASE_URL.

Testes básicos para confirmar que o Claude Code está instalado e funcionando: verificar versão, fazer uma chamada simples e confirmar conectividade com o modelo.

Confirmar o funcionamento antes de usar em projetos reais evita descobrir problemas no meio do trabalho. Diagnóstico precoce facilita correções.

claude --version para versão instalada, claude -p "hello" para teste de conectividade, interpretação de mensagens de erro comuns.

Lista das distribuições Linux onde o Claude Code funciona oficialmente, com foco nas baseadas em Debian (Ubuntu, Mint) e RPM (Fedora, CentOS) além de Arch Linux.

Cada distro tem gerenciadores de pacotes e configurações diferentes. Saber qual distro você usa determina quais comandos de instalação do Node.js utilizar.

apt para Ubuntu/Debian, dnf para Fedora, pacman para Arch, nvm funciona em todas as distros como método universal.

Métodos de instalação do Node.js no Linux: via nvm (Node Version Manager) que permite gerenciar múltiplas versões, ou via gerenciador de pacotes da distro.

O Node.js dos repositórios apt/dnf costuma ser desatualizado. O nvm instala a versão mais recente LTS e evita problemas de permissão com instalações globais do npm.

nvm install --lts para versão LTS, nvm use para ativar versão, sem necessidade de sudo com nvm, verificação com node -v.

Instalação global do Claude Code no Linux. Com nvm, o npm global funciona sem sudo, evitando problemas de permissão comuns em instalações diretas via apt.

Instalar com sudo npm pode causar problemas de permissão. Com nvm, tudo fica no diretório do usuário, sem necessidade de root.

Instalação sem sudo com nvm, diretório ~/.nvm para binários, verificação com which claude para confirmar local de instalação.

Arquivo de configuração do shell Linux executado a cada sessão. Adicionar variáveis de ambiente com export garante que elas estarão disponíveis sempre.

Sem isso, é necessário reconfigurar as variáveis toda vez que abrir um terminal. O .bashrc/.zshrc automatiza essa configuração de forma permanente.

.bashrc para bash, .zshrc para zsh, comando export, source ~/.bashrc para aplicar sem reiniciar, verificação com echo $VARIAVEL.

Autenticação do Claude Code no Linux. Em ambientes desktop abre o browser automaticamente. Em servidores sem GUI, usa variável de ambiente com a API key.

Entender o método correto para cada situação (desktop vs servidor headless) evita erros de autenticação e configurações desnecessárias.

Login interativo em desktop, API key via export para servidores, verificação de autenticação com claude -p "teste".

Processo de atualização do Claude Code para a versão mais recente. O Claude Code é atualizado frequentemente com novos recursos e correções de bugs.

Manter o Claude Code atualizado garante acesso aos recursos mais recentes, melhor estabilidade e compatibilidade com modelos novos.

npm update -g @anthropic-ai/claude-code, verificar versão atual com claude --version, conferir changelog no GitHub.

Ferramentas base para desenvolvimento no macOS: Homebrew é o gerenciador de pacotes mais popular, e Xcode CLI Tools fornece compiladores e git necessários para npm.

O macOS não vem com ferramentas de desenvolvimento por padrão. Homebrew simplifica a instalação de Node.js e outras dependências com um único comando.

Instalação do Homebrew via script oficial, xcode-select --install para CLI tools, brew como gerenciador universal no macOS.

Dois métodos principais para instalar Node.js no Mac: via Homebrew (brew install node) ou via nvm para gerenciar múltiplas versões.

nvm é preferível para desenvolvedores que trabalham em múltiplos projetos com versões diferentes de Node. Homebrew é mais simples para uso único.

brew install node para instalação direta, nvm para gerenciamento de versões, verificação com node -v e npm -v.

Instalação global do Claude Code no macOS. O processo é idêntico ao Linux, com atenção especial ao Gatekeeper do macOS que pode bloquear executáveis não assinados.

Entender as particularidades do macOS (Gatekeeper, SIP) evita bloqueios inesperados durante a instalação e execução do Claude Code.

npm install -g, possível aviso de permissão do Gatekeeper, verificação com which claude e claude --version.

O macOS usa zsh como shell padrão desde o Catalina. O arquivo .zshrc no diretório home é carregado em cada sessão e é onde variáveis permanentes são configuradas.

Variáveis de API key precisam ser persistentes. Sem configurar o .zshrc, as variáveis precisam ser redefinidas toda vez que abrir o Terminal.app ou iTerm2.

Localização em ~/.zshrc, comando export, source ~/.zshrc para aplicar imediatamente, diferença entre .zshrc (interativo) e .zprofile (login).

Autenticação do Claude Code no macOS, que pode usar o browser nativo para login OAuth no Anthropic Console ou variável de ambiente com API key.

O macOS integra bem com o Safari para autenticação OAuth. Entender o fluxo completo evita confusão entre os diferentes métodos de autenticação.

Login via browser Safari, API key como alternativa, armazenamento seguro em Keychain vs variável de ambiente.

Comparação entre o Terminal.app nativo do macOS e o iTerm2, um emulador de terminal avançado. O Claude Code funciona em ambos, mas o iTerm2 oferece mais recursos.

O iTerm2 com configurações adequadas melhora muito a experiência com o Claude Code: suporte a cores melhorado, divisão de painéis, e melhor suporte a Unicode para emojis.

iTerm2 gratuito e open source, configurar fonte monospace (FiraCode, JetBrains Mono), tema dark para melhor legibilidade de código.

VPS (Virtual Private Server) é um servidor remoto dedicado onde você pode rodar o Claude Code 24/7, sem depender do seu computador pessoal estar ligado.

Uma VPS permite automações contínuas, acesso remoto de qualquer dispositivo, e maior controle sobre o ambiente de execução sem custos de cloud como AWS/GCP.

Oracle Free Tier oferece VPS gratuita, Hetzner tem melhor custo-benefício na Europa, mínimo recomendado: 1 vCPU, 1GB RAM, Ubuntu 22.04.

SSH (Secure Shell) é o protocolo para acessar servidores remotos de forma segura. Chaves SSH são mais seguras que senhas e evitam digitá-la a cada conexão.

SSH é a forma padrão de administrar servidores Linux. Chaves SSH aumentam segurança e conveniência, especialmente para automações que precisam conectar sem intervenção humana.

ssh-keygen para gerar chaves, ssh-copy-id para copiar chave pública ao servidor, arquivo ~/.ssh/config para atalhos de conexão.

Instalação do Node.js em servidor Ubuntu via nvm, sem necessidade de root. Em servidores compartilhados, instalar como usuário normal é a abordagem mais segura.

Em VPS, usar sudo para npm global pode conflitar com outros usuários ou scripts. O nvm instala tudo no diretório do usuário, isolando o ambiente.

curl para instalar nvm, source ~/.bashrc após instalação, nvm install --lts, verificar que node e npm funcionam sem sudo.

Instalação do pacote Claude Code no servidor remoto. O processo é idêntico ao Linux local, mas em ambiente headless (sem interface gráfica).

Servidores não têm browser para autenticação OAuth. É necessário configurar API key como variável de ambiente antes de usar o Claude Code.

npm install -g após nvm configurado, autenticação apenas via API key em servidores, configurar export no .bashrc do servidor.

Em servidores headless, a autenticação é feita exclusivamente via variável de ambiente ANTHROPIC_AUTH_TOKEN com a API key gerada no console.

Servidores Linux não têm browser. Sem configurar a variável de ambiente corretamente, o Claude Code travará tentando abrir uma janela de browser inexistente.

Gerar API key em console.anthropic.com, export permanente no .bashrc, nunca commitar a chave em git, usar .env ou secret managers.

Multiplexadores de terminal como tmux e screen permitem manter sessões ativas no servidor mesmo após desconectar do SSH. O Claude Code continua rodando na sessão.

Sem tmux/screen, fechar a conexão SSH encerra o Claude Code. Para automações longas ou sessões interativas persistentes, um multiplexador é essencial.

tmux new -s nome para criar sessão, Ctrl+B D para desanexar, tmux attach -t nome para reanexar, screen como alternativa mais simples.