이 10가지 문제는 Claude Code 설치 및 인증 관련 지원 티켓의 대부분을 차지합니다. 각 항목에는 가장 신뢰할 수 있는 해결 방법이 포함되어 있습니다.
1. claude: command not found 설치 직후 발생.
설치 프로그램이 claude를 PATH에 추가했지만 현재 셸이 아직 이를 인식하지 못했습니다. 새 터미널을 열거나 source ~/.zshrc (또는 ~/.bashrc)를 실행하세요. Windows에서는 PowerShell을 닫았다가 다시 여세요.
2. npm install이 EACCES / 권한 거부 오류로 실패.
이는 보통 설치가 sudo로 실행되었거나 전역 npm 디렉토리가 root 소유라는 의미입니다. sudo를 사용하지 마세요. 대신 네이티브 설치 프로그램(curl -fsSL https://claude.ai/install.sh | bash)을 사용하거나 npm config set prefix ~/.npm-global로 npm의 접두사를 수정한 후 해당 bin 디렉토리를 PATH에 추가하세요.
3. "Node version not supported" 또는 실행 시 조용한 충돌.
Claude Code는 Node 18 이상이 필요합니다. node -v로 버전을 확인하세요. 더 오래된 버전이면 nvm install --lts로 최신 버전을 설치하거나 자체 런타임을 포함하고 이 문제를 완전히 피하는 네이티브 설치 프로그램을 사용하세요.
4. WSL: claude가 Linux Node 대신 Windows Node를 실행.
Windows PATH가 WSL로 유입되어 nvm을 재정의합니다. ~/.bashrc에서 Linux node를 PATH 앞에 추가하세요: export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"
5. 설치 프로그램이 기업 네트워크 뒤에서 중단되거나 실패.
다운로드 호스트(storage.googleapis.com)가 차단되었을 가능성이 높습니다. 먼저 export HTTPS_PROXY=http://proxy.example.com:port로 프록시를 설정한 후 설치 프로그램을 다시 실행하세요. 불가능하면 IT 팀에 오프라인 패키지를 요청하세요.
6. SELF_SIGNED_CERT_IN_CHAIN 또는 기타 TLS 오류.
회사에서 자체 인증서를 주입합니다. Node를 기업 CA 번들로 지정하세요: export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem 셸 프로필에 추가하여 유지되도록 하세요.
7. /login이 브라우저를 열지만 터미널이 완료되지 않음("인증 대기 중…").
이는 보통 localhost 콜백이 차단되었다는 의미이며, 원격 SSH, devcontainer 또는 엄격한 방화벽 뒤에서 흔합니다. 대신 수동 흐름을 사용하세요: 터미널에 인쇄된 URL을 복사하고 모든 브라우저에서 로그인을 완료한 후 반환된 코드를 터미널에 다시 붙여넣으세요.
8. ANTHROPIC_API_KEY를 설정했는데도 "인증되지 않음".
일반적인 원인 3가지: 키가 다른 셸에서 내보내졌음(echo $ANTHROPIC_API_KEY로 확인), Claude Code가 아직 이 키를 신뢰하도록 설정되지 않음(첫 사용 시 한 번 프롬프트 표시; 승인할 때까지 ANTHROPIC_API_KEY는 OAuth 세션보다 우선하며 승인 후에만 적용), 또는 키가 Console 키이지만 조직에서 SSO 로그인이 필요함.
9. Bedrock / Vertex: "자격 증명을 로드할 수 없습니다."
Claude Code는 표준 공급자 SDK를 사용하므로 해결 방법은 AWS/GCP CLI 도구와 동일합니다. Bedrock의 경우 aws sts get-caller-identity가 작동하고 AWS_REGION이 모델이 활성화된 지역으로 설정되어 있는지 확인하세요. Vertex의 경우 gcloud auth application-default login이 실행되었고 ANTHROPIC_VERTEX_PROJECT_ID와 CLOUD_ML_REGION이 설정되어 있는지 확인하세요.
10. 설치 및 인증은 완료되었지만 모든 요청이 403 / "모델을 사용할 수 없음" 오류로 실패.
계정은 존재하지만 Claude Code가 요청하는 모델에 대한 액세스 권한이 없습니다. Enterprise 시트의 경우 조직의 관리자 설정에서 시트가 활성화되어 있는지 확인하세요. Bedrock 또는 Vertex에서 특정 Claude 모델이 해당 지역 또는 프로젝트에서 활성화되어 있는지 확인하세요. 빠른 해결 방법으로 /model을 실행하고 액세스 권한이 있는 모델을 선택하세요.
여전히 막혔나요?
일반 셸에서 claude doctor를 실행하세요(Claude 세션 내부가 아님). 지원 티켓에 첨부할 수 있는 진단 보고서를 인쇄합니다. 알려진 문제의 전체 목록은 문제 해결 가이드를 참조하세요.