Playbook do Claude

Sintomas: o download nunca termina; arquivo baixado está corrompido; tela branca com código estranho (HTML) em vez do instalador; "Falha na conexão" ou "Tempo esgotado".

Causas e soluções:

1. Internet instável — teste outros sites.
2. Rede bloqueando (WiFi de empresa/escola/hotel) — conecte no 4G/5G do celular e tente de novo. Se funcionar, era o WiFi.
3. País não suportado ou VPN estranha — desligue VPN. Se receber "App unavailable in region", seu país não é suportado.
4. Alternativa no Mac:
   Copiar

   brew install --cask claude-code

5. Alternativa no Windows (PowerShell):
   Copiar

   winget install Anthropic.ClaudeCode

Tela azul "O Windows protegeu seu PC" (SmartScreen).

1. Clique em Mais informações (pequeno, no canto).
2. Clique em Executar assim mesmo.
3. Siga a instalação normalmente.

Se o antivírus corporativo bloqueou, peça ao TI para liberar.

Sintomas: abre e fecha imediatamente, tela fica em branco/cinza, trava no logo.

Tente na ordem:

1. Feche completamente e abra de novo.
   • Windows: Ctrl+Shift+Esc → Gerenciador de Tarefas → "Claude" → Finalizar tarefa.
   • Mac: Cmd+Option+Esc → Claude → Forçar saída.
2. Reinicie o computador. Parece bobagem — resolve metade dos casos.
3. No Mac: saiu em "tela cheia" antes? Bug conhecido — quando aparecer a tela branca, aperte Ctrl+Cmd+F para sair da tela cheia.
4. No Mac: macOS antigo demais? Precisa de macOS 13 ou mais novo. Verifique em 🍎 → Sobre este Mac.
5. Reinstale o app.

Sintomas: o navegador não abre; faz login mas volta para a tela de login (loop); "Invalid authorization"; "Invalid code"; "403 Forbidden"; "Request not allowed".

1. Navegador não abriu automaticamente — procure um botão "Copy URL" na tela, cole em qualquer navegador.
2. "Invalid code" — o código expirou. Refaça rápido: feche a janela, clique Entrar, complete sem demorar.
3. Loop de login — saia do Claude. Limpe cookies do claude.ai no navegador. Tente de novo.
4. "403 Forbidden" — verifique se o plano está ativo em claude.ai/settings.
5. No Mac: Keychain bloqueado — abra Acesso às Chaves, chaveiro "login", desbloqueie com a senha do Mac.

Mensagens típicas: Git is required ou Claude Code on Windows requires git-bash.

No Windows (caso mais comum):

1. Instale o Git em git-scm.com/downloads/win.
2. Marque "Add to PATH" durante a instalação.
3. Feche o Claude completamente (Gerenciador de Tarefas → Finalizar tarefa).
4. Abra o Claude de novo.

Se ainda não funcionar, o Git foi instalado em lugar exótico — edite ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Descubra o caminho exato com where.exe git.

No Mac:

xcode-select --install

Principal causa: você está no Windows Home.

A aba Cowork precisa do Hyper-V, que não existe no Windows 10 Home nem no Windows 11 Home.

Como saber:

1. Pressione Windows + R, digite winver, Enter.
2. Se aparecer "Windows 10 Home" ou "Windows 11 Home" → Cowork não vai funcionar.

Soluções: use só Chat e Code, ou atualize para Windows Pro.

Outras causas: bug após update (feche/reabra ou reinstale); no Mac, atualize o app para a versão mais recente.

Só acontece em Windows Pro/Enterprise. Você precisa ligar três coisas.

Passo 1 — Ligar virtualização na BIOS

Reinicie o computador e aperte repetidamente:

Procure: "Virtualization", "Intel VT-x", "AMD-V" ou "SVM Mode". Ative, salve e saia (F10).

Passo 2 — Ligar recursos do Windows

1. Menu Iniciar → "Ativar ou desativar recursos do Windows".
2. Marque: ✅ Hyper-V, ✅ Plataforma de Máquina Virtual, ✅ Plataforma do Hipervisor do Windows.
3. OK → Reinicie.

Passo 3 — Testar

Abra o Claude. Cowork vai baixar uma VM (alguns minutos). Desligue a VPN antes de testar.

Soluções em ordem:

1. Inicie uma nova sessão — conversas longas ficam pesadas.
2. Não peça arquivos gigantes de uma vez — divida em partes.
3. Feche outros programas pesados.
4. Reinicie o Claude.
5. Reinicie o computador.

Sintomas: conectou mas o Claude não usa; "No MCP servers configured"; conecta mas dá erro ao usar.

1. Feche e abra o Claude completamente. MCPs só carregam na inicialização.
2. Confirme que o conector está "conectado" em Configurações → Conectores.
3. Peça ao Claude para diagnosticar: digite /doctor na conversa.
4. Se configurou MCP editando arquivo: veja as perguntas da categoria MCP abaixo.

Resolvem mais da metade dos casos. Antes de tudo, tente:

1. Feche completamente o Claude e abra de novo.
   • Windows: Ctrl+Shift+Esc → Gerenciador de Tarefas → "Claude" → Finalizar tarefa.
   • Mac: Cmd+Q (não minimize, feche de verdade).
2. Reinicie o computador. Um restart limpo antes de pedir ajuda.

Causa: %USERPROFILE%\.local\bin não está no PATH.

Solução (PowerShell):

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Depois feche e reabra o terminal.

Mesma causa da anterior, mas em ambiente PowerShell. Aplique a solução do PATH acima.

Causa: você está rodando no CMD um comando de PowerShell.

Solução: abra "Windows PowerShell" no menu Iniciar e cole o comando, ou use o instalador CMD:

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

Causa: você está rodando no PowerShell um comando de CMD.

Solução:

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

Causa: você colou um comando de macOS/Linux no Windows.

Solução: use o comando oficial de PowerShell ou CMD documentado em code.claude.com/docs/en/setup.

Causa: Git for Windows não instalado ou não está no PATH.

1. Instale em git-scm.com/downloads/win com "Add to PATH" marcado.
2. Reinicie o terminal.
3. Se ainda falhar, edite ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Descubra o caminho exato com where.exe git.

Causa: você abriu "Windows PowerShell (x86)" em vez da normal.

Verificar:

[Environment]::Is64BitOperatingSystem

Se True, feche a janela x86 e abra a PowerShell sem "(x86)". Se False, o SO é 32 bits e não é suportado.

Sintoma: claude abre o app gráfico em vez da CLI.

Solução: atualize o Claude Desktop para a versão mais recente.

Causa: firewall corporativo bloqueando a verificação de revogação de certificado.

Solução (CMD):

curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Ou use winget install Anthropic.ClaudeCode.

Causa: ~/.local/bin fora do PATH.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --version

Causa: macOS mais antigo que 13.0.

Solução: atualize o macOS, ou tente:

brew install --cask claude-code

Causa conhecida (bug): o npm via Homebrew cria symlink incorreto.

npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

Causa: restos de .DS_Store bloqueando rename.

npm uninstall -g @anthropic-ai/claude-code
rm -rf $(npm root -g)/@anthropic-ai
npm install -g @anthropic-ai/claude-code

security unlock-keychain ~/Library/Keychains/login.keychain-db

Se não resolver, abra Acesso às Chaves → chaveiro "login" → Edit → Change Password, sincronize com a senha da conta.

Causa: WSL usando o npm do Windows.

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check

Nunca use sudo.

Causa: node veio do Windows em /mnt/c/....

which node
which npm

Se mostrar /mnt/c/..., instale Node no Linux via nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc
nvm install --lts

Adicione ao ~/.bashrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

Ou pressione c no prompt para copiar a URL manualmente.

Causa: I/O penalty em /mnt/c/....

Solução: mover o projeto para /home/usuario/... (sistema de arquivos do Linux) ou usar Windows nativo.

Atualize para WSL2 (no PowerShell do Windows):

wsl --set-version Ubuntu 2

node --version

Para atualizar:

• Windows: baixe LTS em nodejs.org.
• macOS: brew install node ou nvm.
• nvm: nvm install --lts && nvm use --lts.

Solução correta (sem sudo):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

Causas e correções:

• .npmrc com optional=false → remova.
• Instalação com --omit=optional → reinstale sem a flag.
• Plataforma não suportada → veja code.claude.com/docs/en/setup.
• Mirror corporativo incompleto → peça ao TI para espelhar todos os 8 pacotes @anthropic-ai/claude-code-*.

which -a claude         # macOS/Linux
where.exe claude        # Windows PowerShell
npm -g ls @anthropic-ai/claude-code

Mantenha só ~/.local/bin/claude e desinstale o resto:

npm uninstall -g @anthropic-ai/claude-code
brew uninstall --cask claude-code

Se node --version muda entre terminais, padronize um único gerenciador: nvm em macOS/Linux, instalador oficial em Windows.

Ocorre em pendrives, pastas compartilhadas ou montadas em rede.

git config --global --add safe.directory "C:/caminho/do/projeto"

Edite ~/.claude/settings.json:

{ "env": { "CLAUDE_CODE_GIT_BASH_PATH": "D:\\Apps\\Git\\bin\\bash.exe" } }

Causa: repositório não inicializado.

git init
git add .
git commit -m "inicial"

Instale o Git LFS (Homebrew no Mac ou baixando o instalador no Windows) e rode:

git lfs install

Reinicie o Claude.

Pressione c no prompt para copiar a URL, cole em qualquer navegador e complete o login por lá.

O código expirou. Refaça rapidamente o fluxo de login.

• Verifique plano em claude.ai/settings.
• Conta Console precisa de role "Claude Code" ou "Developer".
• Proxy corporativo pode interferir — veja as perguntas da categoria Rede.

Causa clássica: variável ANTHROPIC_API_KEY antiga no shell profile.

unset ANTHROPIC_API_KEY

Remova de ~/.zshrc, ~/.bashrc, ~/.profile. Confirme com /status.

Relógio do sistema fora de sincronia. Ative a sincronização automática de horário nas configurações do SO.

Verifique nesta ordem de prioridade:

1. Flag --model com typo.
2. Variável ANTHROPIC_MODEL antiga.
3. model em .claude/settings.local.json.
4. model em .claude/settings.json.
5. model em ~/.claude/settings.json.

Remova o valor antigo e deixe cair no default.

Checklist:

1. Arquivo em ~/.claude.json (não em ~/.claude/settings.json)?
2. JSON válido? Valide em jsonlint.com.
3. Escopo correto (user, project, local)?
4. Servidor aninhado em mcpServers: { "nome": {...} }?
5. Rode /doctor — aponta conflitos de mesmo nome em escopos diferentes.

Logs específicos:

~/.claude/logs/mcp-server-<NOME>.log

Causas típicas:

• Comando com caminho relativo → use caminho absoluto.
• Variáveis de ambiente ausentes → passe via campo env.
• Permissão de execução faltando → chmod +x.

Bug conhecido. Workaround:

• Mover para ~/.claude.json (escopo usuário).
• Atualizar o Claude Code para a versão mais recente.

Política corporativa desabilitou MCPs. Converse com o admin do ambiente.

Sintoma: configurações ignoradas ou /doctor alerta "malformed JSON".

Solução: valide em jsonlint.com. Vírgulas sobrando são o erro número 1.

• Quebre em arquivos menores por pasta.
• Mova detalhes para skills ou subagentes.
• Mantenha CLAUDE.md com menos de 500 linhas.

Dentro da sessão:

/permissions

Permita tools específicas para não ter que confirmar toda vez.

• /compact periodicamente.
• Reinicie a sessão entre tarefas grandes.
• Adicione node_modules, dist, .venv ao .gitignore.
• /heapdump gera um dump em ~/Desktop para debug.

1. Leia por ranges: "leia linhas 1-200 de foo.ts".
2. /compact keep only the plan and the diff.
3. Delegue leitura pesada a um subagente.
4. /clear se a conversa anterior não é mais necessária.

• Ctrl+C para cancelar.
• Se não responder, feche o terminal e reabra.
• Rode claude doctor após reiniciar.

Instale o ripgrep do sistema:

# Windows
winget install BurntSushi.ripgrep.MSVC
# macOS
brew install ripgrep

No .env ou settings.json:

USE_BUILTIN_RIPGREP=0

Teste:

curl -sI https://downloads.claude.ai

Com proxy:

export HTTPS_PROXY=http://proxy.empresa.com:8080
export HTTP_PROXY=http://proxy.empresa.com:8080
curl -fsSL https://claude.ai/install.sh | bash

Causa: inspeção TLS corporativa.

export NODE_EXTRA_CA_CERTS=/caminho/para/ca-corporativa.pem

Peça o bundle ao TI.

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install ca-certificates

macOS:

brew install ca-certificates