Solução de problemas de códigos de erro do Claude Code

Causa comum: O diretório de instalação não está no PATH ou o shell atual não recarregou sua configuração.

Correção: Abra um novo terminal ou adicione o diretório de instalação do Claude Code ao PATH e recarregue a configuração do shell.

export PATH="$PATH:$HOME/.local/bin"
source ~/.zshrc

Causa comum: A versão do Node está abaixo do requisito oficial, ou o WSL está chamando o Node do lado do Windows.

Correção: Atualize o Node ou use o instalador nativo oficial. No WSL, confirme o caminho com which node / which npm para garantir que ele vem do ambiente Linux.

node -v
which node
which npm

Causa comum: O diretório global do npm pertence ao root, ou uma instalação anterior com sudo deixou as permissões em mau estado.

Correção: Não instale o Claude Code com sudo. Mude o prefixo do npm para um diretório de usuário ou use o instalador nativo.

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Causa comum: O callback de OAuth do navegador não está chegando à CLI local - comum com SSH remoto, devcontainers, firewalls restritivos ou callbacks de localhost bloqueados.

Correção: Confirme que o navegador e a CLI conseguem se comunicar na mesma máquina. Se necessário, faça logout, reinicie o Claude Code e conclua a autenticação novamente.

/logout
# 关闭 Claude Code 后重新运行
claude

Causa comum: Um proxy corporativo ou gateway de segurança está injetando uma CA autoassinada em que o Node não confia por padrão.

Correção: Peça ao TI o pacote de CAs corporativas e indique-o por meio de NODE_EXTRA_CA_CERTS.

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

Causa comum: As variáveis de proxy estão configuradas incorretamente, o protocolo do proxy não é suportado, NO_PROXY está sobrescrevendo o domínio de destino ou um firewall corporativo está bloqueando o acesso.

Correção: O Claude Code usa as variáveis de ambiente padrão de proxy HTTP/HTTPS; a documentação informa que proxies SOCKS não são suportados. Teste de novo primeiro com HTTPS_PROXY.

export HTTPS_PROXY=http://proxy.example.com:8080
echo $HTTPS_PROXY
echo $NO_PROXY

Causa comum: A organização não ativou o Claude Code, a lista de permissões corporativa não inclui a saída atual, há restrições de conta/região/política ou o proxy está sendo rejeitado.

Correção: Para contas pessoais, confirme primeiro as regiões com suporte e o status da conta; para contas corporativas, peça a um administrador que verifique as permissões do Claude Code, o SSO, a allowlist de IP e as regras de firewall.

Causa comum: As requisições são muito frequentes, a concorrência é alta demais, ou o plano da conta ou a organização atingiu um limite de taxa.

Correção: Reduza a concorrência externa, interrompa os loops de repetição e aguarde a redefinição do limite. Não envolva o Claude Code com vários workers para forçar velocidade.

Causa comum: A chave de API veio de outro shell, uma chave do Console conflita com uma sessão OAuth, ou a organização exige login via SSO.

Correção: Verifique se ANTHROPIC_API_KEY está definida no shell atual. Contas corporativas devem seguir o fluxo de login Console/SSO exigido pelo administrador.

echo $ANTHROPIC_API_KEY