Instalação, autenticação e diagnóstico

Field Note

Terça-feira, 10h. A pessoa instalou o Claude Code, abriu o projeto e as respostas vieram estranhas: erro de autenticação intermitente, MCP que não conecta, comando que "não existe". A conclusão no grupo do time foi rápida: "essa IA é ruim". Ninguém rodou diagnóstico. O problema era uma variável ANTHROPIC_API_KEY esquecida no .zshrc, de uma organização desativada, passando na frente da assinatura.

Conceito

Instalar é a parte fácil. O que dá trabalho é saber qual instalação está rodando, qual credencial está sendo usada e se alguma customização está quebrando a sessão. Três blocos.

1. Instalação. O método recomendado pela doc oficial é o instalador nativo, que se atualiza sozinho em segundo plano:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

No Windows CMD, o comando é curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. No Windows nativo, a doc recomenda instalar o Git for Windows para o Claude Code usar a ferramenta Bash. Sem ele, o Claude Code usa PowerShell.

Alternativas: brew install --cask claude-code (Homebrew), winget install Anthropic.ClaudeCode (WinGet), repositórios apt, dnf e apk, ou npm com npm install -g @anthropic-ai/claude-code (pede Node.js 22 ou mais novo). Detalhe que pega muita gente: Homebrew, WinGet e gerenciadores de pacote Linux não atualizam sozinhos por padrão. E a doc proíbe explicitamente sudo npm install -g.

Requisitos mínimos listados: macOS 13+, Windows 10 1809+, Ubuntu 20.04+, Debian 10+, Alpine 3.19+, 4 GB de RAM e internet.

2. Autenticação. Na primeira execução de claude, abre o navegador para login. Se o navegador não abrir, aperte c para copiar a URL. O Claude Code exige conta Pro, Max, Team, Enterprise ou Console. O plano gratuito do claude.ai não inclui Claude Code. Também dá para usar via Amazon Bedrock, Google Cloud’s Agent Platform ou Microsoft Foundry.

O ponto crítico é a ordem de precedência. Quando existem várias credenciais, a doc lista a prioridade: credenciais de provedor de nuvem, depois ANTHROPIC_AUTH_TOKEN, depois ANTHROPIC_API_KEY, depois apiKeyHelper, depois CLAUDE_CODE_OAUTH_TOKEN, e só no fim o login da assinatura via /login. Ou seja: uma API key no ambiente, aprovada uma vez, passa na frente da sua assinatura e começa a cobrar por token. Para conferir o que está ativo, /status. Para voltar à assinatura, unset ANTHROPIC_API_KEY.

3. Diagnóstico. São dois doctors diferentes:

• claude doctor, no shell: diagnóstico somente leitura, sem abrir sessão. Mostra saúde da instalação, erros de validação nos arquivos de settings, resultado da última atualização e elegibilidade para Remote Control. Use quando claude nem abre.
• /doctor, dentro da sessão: checkup completo de instalação, settings, extensões e CLAUDE.md, que propõe correções e aplica depois que você confirma.

E o safe mode: claude --safe-mode abre uma sessão com todas as customizações desligadas (CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos e agentes customizados, auto memory). Autenticação, modelo, ferramentas nativas e permissões continuam normais. Se o problema some no safe mode, o culpado é uma customização. Aí você investiga com /mcp (servidores e status), /hooks (hooks registrados), /context (o que carregou) e claude --debug.

Quando usar

• Primeira instalação em máquina nova, antes de abrir qualquer projeto importante.
• Depois de atualizar, trocar de método de instalação ou de conta.
• Quando a sessão fica lenta, trava, ignora instrução ou um MCP some.
• Quando o consumo parece errado (pode ser credencial errada ativa).

Quando não usar

• Não use safe mode como modo de trabalho do dia a dia. Ele desliga justamente o que deixa o agente útil no seu projeto.
• Não reinstale às cegas a cada erro. Rode o diagnóstico antes. Reinstalar sem entender costuma criar uma segunda instalação concorrendo com a primeira.
• Não teste instalação nova direto no repositório de produção.

Faça agora

1. Instale pelo método nativo do seu sistema (comandos acima).
2. Abra um terminal novo e confirme:

claude --version

Deve imprimir um número de versão seguido de (Claude Code). Se aparecer command not found, o diretório de instalação não está no PATH. No macOS, Linux e WSL, verifique se não há instalações concorrentes com which -a claude.

3. Rode o diagnóstico de fora da sessão:

claude doctor

4. Prepare um repositório de teste numa branch separada:

cd caminho/do/repositorio-de-teste
git switch -c teste-claude-code
claude

5. Faça login no navegador. Dentro da sessão, rode /status e confira o método de login e a conta. Se aparecer API key quando você esperava assinatura, pare e resolva antes de seguir.
6. Rode /doctor e leia as propostas antes de aceitar qualquer correção.
7. Se algo estiver estranho, saia e teste com claude --safe-mode. Anote se o problema persiste.
8. Guarde a saída do diagnóstico como evidência do Ambiente validado.

Armadilhas

• API key fantasma. ANTHROPIC_API_KEY no perfil do shell passa na frente da assinatura. A doc avisa que isso pode causar falha de autenticação se a chave for de organização desativada ou expirada.
• Duas instalações. npm antigo mais instalador nativo, ou Homebrew mais nativo. claude roda uma, a atualização vai para a outra. which -a claude mostra.
• Homebrew parado no tempo. Sem auto-update. Rode brew upgrade claude-code de vez em quando.
• Confundir os doctors. claude doctor só lê. /doctor propõe e aplica correção depois que você confirma.
• MCP de projeto "sumido". Servidor definido em .mcp.json exige aprovação única. Se o prompt foi ignorado, ele fica desligado até você aprovar em /mcp.
• Settings no arquivo errado. ~/.claude.json guarda estado do app. Permissões, hooks e env vão em ~/.claude/settings.json. São arquivos diferentes.
• Login em WSL, SSH ou container. Se o navegador mostrar um código em vez de voltar sozinho, cole no terminal no prompt Paste code here if prompted.

Material para levar

Checklist de ambiente validado:

[ ] claude --version imprime versão (Claude Code)
[ ] which -a claude mostra uma instalação só (macOS/Linux/WSL)
[ ] claude doctor sem erro crítico
[ ] /status mostra o método de login esperado (assinatura ou Console)
[ ] Nenhuma ANTHROPIC_API_KEY esquecida no ambiente, a menos que seja intencional
[ ] /doctor rodado e propostas revisadas
[ ] /mcp sem servidor em falha
[ ] Repositório de teste em branch separada
[ ] Se houve problema: comportamento em claude --safe-mode anotado

Ordem de investigação quando der ruim:

1. claude doctor          (instalação e settings, sem abrir sessão)
2. /status                (qual conta e qual credencial)
3. /doctor                (checkup com correções propostas)
4. claude --safe-mode     (some o problema? é customização)
5. /mcp, /hooks, /context (qual customização)
6. claude --debug         (log detalhado)