Como instalar e configurar Claude Code no macOS

Início » Como instalar e configurar Claude Code no macOS

Se você desenvolve em macOS e quer um assistente de IA direto no terminal, o Claude Code é hoje uma das opções mais potentes para trabalhar com repositórios inteiros, fazer refactors grandes e automatizar tarefas de desenvolvimento. Diferente de um simples chatbot no navegador ou de um plugin de editor, ele roda na linha de comando, entende a estrutura do projeto, acompanha o histórico do Git e consegue orquestrar mudanças em vários arquivos de uma vez.

Instalar o Claude Code no macOS não é complicado, mas existem vários caminhos e alguns detalhes importantes de versão, permissões e autenticação que podem causar dor de cabeça se você pular etapas. A seguir, você vai ver um guia completo em português sobre como colocar o Claude Code para rodar no Mac, cobrindo desde os requisitos, os três métodos de instalação (instalador nativo, Homebrew e npm legado) até como autenticar, configurar o primeiro projeto e resolver os problemas mais comuns.

O que é o Claude Code e o que você precisa antes de instalar

Claude Code é o agente de IA da Anthropic pensado especificamente para rodar no terminal e trabalhar diretamente sobre o seu código local. Ele não é uma extensão de IDE, nem uma interface gráfica no navegador: você chama o comando claude de dentro de qualquer pasta de projeto e interage em um fluxo parecido com um REPL avançado, capaz de ler, escrever e testar código.

Uma das principais diferenças em relação a ferramentas como GitHub Copilot é o nível em que o Claude Code atua. Enquanto o Copilot é focado em autocompletar trechos de código dentro do editor, o Claude Code se comporta mais como um agente: ele lê repositórios inteiros, compreende arquitetura, roda comandos, faz commits e cria branches, sempre pedindo sua confirmação por padrão antes de executar ações potencialmente destrutivas.

Para usar o Claude Code você precisa de uma conta paga da Anthropic ou de crédito via API, não basta o plano gratuito do Claude no navegador. Os planos mais comuns são o Claude Pro (voltado para uso individual intenso, com limite de uso adequado para a maioria dos devs), o Claude Max (com limites bem mais altos para sessões longas e tarefas pesadas) e o acesso via Anthropic Console para quem prefere integrar pela API em pipelines de CI/CD ou automações.

No macOS, os requisitos mínimos são relativamente modestos: macOS 10.15 Catalina ou superior, pelo menos 4 GB de RAM (idealmente 8 GB ou mais para repos muito grandes) e algo em torno de 200-300 MB de espaço em disco. Embora o Claude Code possa funcionar sem Git, é fortemente recomendado que você tenha o Git instalado e inicialize seus projetos, pois o agente usa o histórico de commits para entender a evolução do código e propor alterações mais seguras.

Se você quer confirmar rapidamente se o seu Mac está na versão suportada, basta abrir o Terminal e rodar: sw_vers -productVersion. Se o resultado for 10.15 ou superior (incluindo Apple Silicon como M1, M2, M3, M4), o sistema é compatível; o binário oficial da Anthropic já vem assinado e notarizado para arquitetura arm64, rodando nativamente sem precisar de Rosetta.

Método 1: Instalador nativo para macOS (recomendado)

Hoje a maneira mais simples e recomendada pela Anthropic para instalar o Claude Code no macOS é usar o instalador nativo fornecido via script de instalação. Esse método não exige Node.js, não conflita com outros gerenciadores de pacotes, oferece atualizações automáticas em segundo plano e minimiza problemas de permissões.

Para começar, abra o Terminal (Spotlight → digite “Terminal” ou vá em Aplicativos → Utilitários → Terminal) e execute um único comando: curl -fsSL https://claude.ai/install.sh | bash. O script baixa um binário assinado pela Anthropic, instala na sua home (geralmente em ~/.local/bin/claude ou ~/.claude/bin/claude) e adiciona automaticamente o caminho ao arquivo de configuração do shell, como ~/.zshrc ou ~/.bashrc.

Depois que o script terminar, é importante recarregar o ambiente de shell para que o comando claude seja reconhecido. Você pode simplesmente fechar e abrir de novo a janela do Terminal ou rodar algo como source ~/.zshrc, dependendo do shell que usa. Em seguida, teste se a instalação foi bem-sucedida com claude --version e, logo depois, rode claude doctor para uma checagem mais profunda de saúde da instalação.

O comando claude doctor faz uma varredura rápida da configuração, verificando se o binário está no PATH, se as permissões estão corretas, se há problemas com autenticação e com o estado dos servidores MCP (Model Context Protocol) usados para integrações externas. Sempre que algo “parecer estranho” no comportamento da ferramenta, esse comando é um excelente primeiro passo para diagnosticar a causa.

Uma vantagem importante desse instalador nativo é que o binário já vem assinado pela Anthropic PBC e notarizado pela Apple. Em condições normais, isso significa que você não verá alertas do Gatekeeper ao rodar o comando pela primeira vez; se algum aviso aparecer, geralmente indica uma versão antiga instalada via npm que ficou no sistema e precisa ser substituída pelo binário atual.

Instalação via Homebrew no macOS

Se você já está acostumado a gerenciar praticamente tudo no seu Mac com o Homebrew, também é possível instalar o Claude Code com um simples comando brew. Essa abordagem é conveniente para quem já tem scripts de provisioning ou gosta de manter todas as ferramentas sob o mesmo gerenciador.

Para instalar o app usando o Homebrew, basta rodar no Terminal: brew install --cask claude-code. O Homebrew trata o Claude Code como um cask, instalando o binário em um local padrão do sistema, com permissões adequadas e integração com o Spotlight, se aplicável. Você continua chamando o comando claude no terminal como de costume.

A principal desvantagem desse caminho é que as atualizações não são automáticas como no instalador nativo da Anthropic. Sempre que sair uma nova versão, será necessário executar manualmente brew upgrade claude-code para atualizar. Se você esquecer de fazer isso por meses, vai acabar usando uma release desatualizada, o que pode significar menos recursos, correções de bugs pendentes e, eventualmente, incompatibilidade com o backend.

Do ponto de vista de estabilidade e manutenção, a própria Anthropic indica que o melhor fluxo é o instalador nativo sempre que possível, deixando o Homebrew apenas como alternativa para quem realmente centraliza toda a stack nesse gerenciador. Caso você mude de ideia depois, pode desinstalar o cask com brew uninstall --cask claude-code e voltar ao script oficial.

Método legado: instalação com Node.js e npm

A instalação via npm foi, por um bom tempo, o caminho padrão para colocar o Claude Code para rodar em diferentes sistemas, incluindo macOS. Hoje esse método é considerado legado ou “deprecated” pela Anthropic, e só faz sentido em cenários específicos, como ambientes onde tudo é gerenciado por Node, necessidade de travar uma versão específica ou setups em que a equipe padronizou ferramentas como pacotes globais npm.

Se você optar por esse caminho no macOS, o primeiro passo é garantir que o Node.js instalado tenha versão 18 ou superior. No Terminal, rode node --version para conferir; se o resultado for menor que 18, será preciso atualizar. A forma mais confortável de gerenciar várias versões é com o nvm (Node Version Manager), que permite instalar e alternar entre versões facilmente.

Para instalar o nvm, execute um comando semelhante a: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash, depois recarregue o shell com source ~/.zshrc (ou equivalente) e instale uma versão LTS recente, como nvm install 22 seguido de nvm use 22. A linha de 22.x costuma ser recomendada atualmente para uso com o Claude Code.

Com o Node correto no ar, instale o pacote global do Claude Code pela npm com: npm install -g @anthropic-ai/claude-code. Aqui há um ponto crítico: você não deve usar sudo nesse comando. Forçar sudo npm install -g ... geralmente bagunça permissões no diretório global da npm e abre brecha para problemas de segurança difíceis de reverter depois.

Se ao tentar instalar você topar com erros de permissão do tipo EACCES, o ideal é configurar a npm para utilizar um diretório global dentro da sua home, que pertence ao seu usuário. Você pode fazer isso criando a pasta ~/.npm-global, rodando npm config set prefix '~/.npm-global' e adicionando uma linha como export PATH="$HOME/.npm-global/bin:$PATH" no seu ~/.zshrc (ou shell equivalente). Depois de recarregar esse arquivo com source ~/.zshrc, repita a instalação global sem sudo.

Passo a passo de instalação para iniciantes no macOS

Se você nunca mexeu com terminal, Node.js ou Git no Mac, pode seguir um fluxo mais detalhado orientado a iniciantes, partindo do download do Node até a verificação final do Claude Code. Embora o instalador nativo dispense Node.js, ainda há muitos materiais e vídeos tutoriais que ensinam o caminho via npm, então vale conhecer esse roteiro mais guiado.

O primeiro passo é baixar o instalador do Node diretamente pelo navegador. Abra o Safari, Chrome ou Firefox, acesse https://nodejs.org e clique no botão verde de download da versão LTS para macOS (arquivo .pkg). O arquivo cai na pasta Downloads com um nome parecido com node-v24.x.x.pkg, variando conforme a versão.

Em seguida, abra o Finder, vá na pasta Downloads, dê um duplo clique no .pkg do Node e siga as etapas do instalador gráfico. Normalmente é só clicar em “Continuar” algumas vezes, aceitar a licença, escolher ou confirmar o local padrão de instalação e informar a senha de administrador do macOS quando solicitado. Em poucos minutos você verá a mensagem de sucesso e poderá fechar o instalador, movendo-o para o Lixo se quiser.

Com o Node instalado, volte ao Terminal (Command + Espaço → “Terminal”) e rode node --version e npm --version para ter certeza de que tudo foi configurado. Se aparecerem números de versão, você está pronto para a próxima etapa; se surgir a mensagem “command not found”, feche o Terminal, abra novamente e teste outra vez, ou reinicie o Mac em casos mais teimosos.

Uma vez que o Node esteja ok, a instalação do Claude Code via npm no Mac segue o comando global: em muitos tutoriais antigos você vai ver algo como sudo npm install -g @anthropic/claude-code, mas a prática atual mais segura é evitar o sudo e, se necessário, ajustar o prefixo global da npm para um diretório na sua home, como explicado antes para o caso de erros EACCES. Após terminar a instalação, verifique com claude --version se o comando ficou disponível.

Caso a instalação global falhe com mensagens sobre “permission denied” ao tentar criar pastas em /usr/local/lib/node_modules, é forte indício de que a npm está apontando para um local do sistema que requer privilégios elevados. Ao corrigir o prefixo para ~/.npm-global e garantir que esse caminho apareça antes no seu PATH, você evita recorrer ao sudo e deixa o ambiente mais previsível.

Autenticação: conectando o Claude Code à sua conta

Não basta ter o binário do Claude Code instalado; você ainda precisa vincular o terminal à sua conta Anthropic, seja via assinatura Claude Pro/Max, seja via chave de API. Esse processo é feito uma única vez por máquina (ou periodicamente, quando o token expira) e pode seguir dois fluxos principais: OAuth no navegador ou autenticação direta com chave de API.

Com tudo instalado, abra o Terminal, navegue até qualquer pasta (por exemplo, sua home) e rode simplesmente claude. Na primeira execução, o programa tenta abrir automaticamente uma página do navegador para você fazer login. Se o navegador não abrir sozinho, copie o URL mostrado no terminal e cole manualmente na barra de endereços.

Ao acessar esse link, faça login com a mesma conta associada ao seu plano Claude Pro ou Max, autorize o acesso e copie o código de verificação exibido na tela. Volte ao Terminal, cole esse código (mesmo que o texto não apareça enquanto você digita ou cola) e pressione Enter. Se tudo der certo, você verá uma mensagem confirmando que a sessão foi autenticada e já poderá começar a usar o agente.

Para uso voltado à API, principalmente em ambientes headless, servidores remotos ou integrações com Azure Foundry, você pode configurar variáveis de ambiente com a chave de API. Um exemplo típico é exportar ANTHROPIC_API_KEY=sk-ant-... no shell e, em cenários com Azure, definir variáveis como CLAUDE_CODE_USE_FOUNDRY=1, ANTHROPIC_FOUNDRY_RESOURCE, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_FOUNDRY_API_KEY com os valores correspondentes ao recurso e aos deployments usados.

Vale lembrar que o token de autenticação armazenado localmente (geralmente em ~/.claude/config.json, com criptografia AES-256) costuma permanecer válido por cerca de 30 dias sem uso. Se, em algum momento, você cair em um “loop” de autenticação ou tiver problemas com o fluxo via navegador, pode rodar claude auth logout seguido de claude auth login ou ainda usar a opção claude auth login --headless para receber um link manual e um código de verificação para colar de volta no terminal.

Configurando o primeiro projeto no macOS

Depois que o Claude Code estiver instalado e autenticado no Mac, o próximo passo é levá-lo para dentro de um repositório real e começar a usá-lo como parceiro de desenvolvimento. Navegue até a pasta do projeto com cd (por exemplo, cd ~/Projects/meu-projeto) e rode claude para abrir a interface interativa no terminal.

Ao iniciar em uma pasta com código, o Claude Code faz uma análise rápida da estrutura do repositório, geralmente em poucos segundos para projetos com até cerca de 50 mil arquivos. Ele detecta pastas, arquivos relevantes, tecnologias envolvidas e já começa a responder perguntas como “explique a arquitetura deste projeto” ou “onde estão concentrados os pontos de tratamento de erro”.

No dia a dia, você pode usar o Claude Code tanto de forma interativa quanto em modo não-interativo. Interativamente, você conversa em linguagem natural pedindo, por exemplo: “adicione um teste unitário para a função processPayment”. Em scripts ou pipelines, é possível chamar o comando com parâmetros como -p e --output-format json, por exemplo: claude -p "verifique vulnerabilidades de SQL injection em controllers/" --output-format json.

Uma prática altamente recomendada após a instalação é criar um arquivo CLAUDE.md na raiz do projeto. Esse arquivo funciona como um conjunto de instruções persistentes que o Claude Code lê sempre que é iniciado naquele repositório. Ali você pode documentar padrões de código, decisões arquiteturais, comandos padrão de build e testes, convenções de estilo, requisitos de segurança e qualquer contexto que não queira repetir a cada sessão.

Se o seu repositório for um monorepo com múltiplos pacotes, é possível adicionar um CLAUDE.md em cada subdiretório relevante, combinando regras globais na raiz com orientações específicas em partes do projeto. Além disso, convém inicializar o Git (caso ainda não tenha feito) com git init, git add . e git commit -m "initial commit", porque o Claude Code faz bom uso do histórico de commits para propor alterações em branches separados e oferecer um “rede de segurança” para qualquer mudança maior.

Resolvendo problemas comuns de instalação e uso

Mesmo seguindo o passo a passo no macOS, alguns problemas aparecem com frequência, mas quase todos têm solução simples. Saber identificar o sintoma e a causa mais provável economiza bastante tempo, principalmente em ambientes corporativos mais restritos.

Um erro clássico é o “command not found: claude” logo após a instalação pelo script nativo. Em geral, isso indica que o PATH do shell atual ainda não foi atualizado com o diretório onde o binário foi instalado. Normalmente, basta fechar a janela do Terminal e abrir outra, ou rodar source ~/.zshrc. Se isso não resolver, abra o arquivo de configuração do shell (como ~/.zshrc) e verifique se a linha adicionando ~/.local/bin ou ~/.claude/bin ao PATH realmente está lá.

Quando o Gatekeeper bloqueia a execução do Claude Code, quase sempre há uma instalação antiga via npm ainda presente no sistema. O binário oficial da Anthropic, assinado e notarizado, não costuma disparar alertas. Nesses casos, remova a instalação anterior (por exemplo, desinstalando o pacote global npm) e reinstale usando o método nativo.

No cenário da instalação via npm, os erros EACCES ao rodar npm install -g são quase sempre vinculados a permissões em diretórios de sistema como /usr/local. A solução é evitar o uso de sudo e, em vez disso, mover o diretório global da npm para dentro da pasta do usuário com o truque do ~/.npm-global, conforme descrito antes. Isso resolve tanto no macOS quanto em outras plataformas Unix-like.

Outro ponto que pode atrapalhar são projetos extremamente grandes com enormes pastas node_modules, diretórios de build ou monorepos com dezenas de milhares de arquivos. Se você notar lentidão ou travamentos na etapa de análise inicial, crie um arquivo .claudeignore na raiz do projeto, usando a mesma sintaxe do .gitignore, para excluir pastas como node_modules/, dist/, .next/ e arquivos de log. Isso reduz significativamente a quantidade de arquivos que o Claude Code tenta inspecionar.

Problemas recorrentes de autenticação, como loops ao tentar logar ou falhas na abertura do navegador, podem estar relacionados a proxies corporativos, firewalls ou bloqueios na URL de callback. Nesses ambientes, uma boa alternativa é usar claude auth login --headless para receber um link simples e um código de verificação, ou então partir para a autenticação com chave de API, que costuma contornar a maior parte das restrições de navegador.

Fluxos de trabalho e boas práticas com Claude Code no macOS

Depois de tudo configurado, o grande ganho vem de aprender a combinar o Claude Code com o seu fluxo de trabalho de desenvolvimento no Mac. Ele não substitui o Git, os testes nem o bom senso de revisão de código, mas pode acelerar refactors, investigar bugs em regiões grandes e documentar partes pouco claras do sistema.

Um recurso importante é o modelo de permissões: por padrão, o Claude Code não sai executando comandos ou reescrevendo arquivos sem pedir sua confirmação. Sempre que o agente propõe rodar um comando no terminal ou aplicar um conjunto de mudanças, você enxerga o plano e aprova ou recusa. Isso torna mais seguro usar a ferramenta em código de produção, especialmente se você trabalhar em time.

Para aumentar a autonomia sem perder completamente o controle, existe ainda o chamado “Auto Mode” do Claude Code, que permite que o agente execute sequências de ações com menos prompts de confirmação. É uma opção interessante para sessões de desenvolvimento intensivo em que você quer fluxo mais contínuo, mas ainda assim com guardrails projetados para não comprometer o projeto inteiro em um único comando mal interpretado.

Outra frente essencial, especialmente se você pensa em custo e performance, é entender como a janela de contexto funciona. Sessões muito longas, com muitos arquivos e historicamente carregadas, podem consumir mais tokens e encarecer o uso (quando feito via API) ou bater nos limites de uso dos planos Claude Pro/Max. Gerenciar o que entra de contexto, resetar sessões quando necessário e aproveitar recursos como servidores MCP para acesso pontual a dados externos ajuda a manter o agente focado e mais barato de rodar.

Por fim, mesmo com um agente poderoso como o Claude Code, boas práticas de engenharia continuam valendo: mantenha branches separados para grandes mudanças, valide os testes antes de dar merge em produção e use o histórico do Git como ferramenta de segurança. O Claude Code foi projetado para trabalhar lado a lado com esse fluxo, não para substituí-lo completamente.

Com o Claude Code devidamente instalado e autenticado no seu macOS, você passa a ter um assistente de IA que entende seu repositório, atua diretamente no terminal, respeita seu fluxo de Git e ainda oferece ferramentas de automação avançadas como MCP, modos de esforço diferentes e configuração via CLAUDE.md, o que torna o desenvolvimento diário muito mais fluido sem exigir mudanças drásticas na sua stack atual.