Solución de códigos de error de Claude Code

Causa común: El directorio de instalación no está en el PATH, o el shell actual no ha recargado su configuración.

Solución: Abre una terminal nueva, o añade el directorio de instalación de Claude Code al PATH y recarga la configuración del shell.

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

Causa común: La versión de Node es inferior al requisito oficial, o WSL está usando el Node del lado de Windows.

Solución: Actualiza Node o usa el instalador nativo oficial. En WSL, confirma la ruta con which node / which npm para asegurarte de que proviene del entorno Linux.

node -v
which node
which npm

Causa común: El directorio global de npm pertenece a root, o una instalación anterior con sudo dejó los permisos en mal estado.

Solución: No instales Claude Code con sudo. Cambia el prefijo (prefix) de npm a un directorio de usuario, o usa el instalador nativo.

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

Causa común: El callback de OAuth del navegador no llega a la CLI local; es habitual con SSH remoto, devcontainers, firewalls estrictos o callbacks a localhost bloqueados.

Solución: Confirma que el navegador y la CLI pueden comunicarse en el mismo equipo. Si hace falta, cierra sesión, reinicia Claude Code y vuelve a completar la autenticación.

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

Causa común: Un proxy corporativo o una puerta de enlace de seguridad está inyectando una CA autofirmada en la que Node no confía de forma predeterminada.

Solución: Pide a TI el paquete de CA corporativo e indícalo mediante NODE_EXTRA_CA_CERTS.

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

Causa común: Las variables de proxy están mal configuradas, el protocolo del proxy no es compatible, NO_PROXY anula el dominio de destino o un firewall corporativo bloquea el acceso.

Solución: Claude Code usa las variables de entorno estándar de proxy HTTP/HTTPS; la documentación indica que no admite proxies SOCKS. Vuelve a probar primero con HTTPS_PROXY.

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

Causa común: La organización no ha habilitado Claude Code, la lista de permitidos corporativa no incluye la salida actual, hay restricciones de cuenta / región / política o se está rechazando el proxy.

Solución: En cuentas personales, confirma primero las regiones admitidas y el estado de la cuenta; en cuentas de empresa, pide a un administrador que revise los permisos de Claude Code, el SSO, la lista de permitidos de IP y las reglas del firewall.

Causa común: Las solicitudes son demasiado frecuentes, la concurrencia es demasiado alta, o el plan de la cuenta o la organización ha alcanzado un límite de solicitudes.

Solución: Reduce la concurrencia externa, detén los bucles de reintento y espera a que se restablezca el límite. No envuelvas Claude Code con varios workers para forzar la velocidad.

Causa común: La clave de API viene de otro shell, una clave de Console entra en conflicto con una sesión de OAuth, o la organización exige iniciar sesión con SSO.

Solución: Comprueba si ANTHROPIC_API_KEY está definida en el shell actual. Las cuentas de empresa deben seguir el flujo de inicio de sesión por Console/SSO que exija el administrador.

echo $ANTHROPIC_API_KEY