이 10가지 문제는 Claude Code 설치 및 인증 관련 지원 티켓의 대부분을 차지합니다. 각 항목에는 가장 안정적인 해결 방법이 포함되어 있습니다.
1. 설치 직후 "claude: command not found"
설치 프로그램이 claude를 PATH에 추가했지만 현재 셸이 아직 이를 인식하지 못했습니다. 새 터미널을 열거나 source ~/.zshrc (또는 ~/.bashrc)를 실행하세요. Windows에서는 PowerShell을 닫았다가 다시 여세요.
2. npm install이 EACCES / 권한 거부 오류로 실패합니다.
이는 보통 설치가 sudo로 실행되었거나 전역 npm 디렉토리가 root 소유라는 의미입니다. sudo를 사용하지 마세요. 대신 curl 설치 프로그램을 사용하거나 npm config set prefix ~/.npm-global로 npm의 접두사를 수정한 후 해당 bin 디렉토리를 PATH에 추가하세요.
3. "Node version not supported" 또는 시작 시 무음 충돌
Claude Code는 Node 18 이상이 필요합니다. node -v로 버전을 확인하세요. 더 오래된 버전이면 nvm install --lts로 현재 버전을 설치하거나 curl 설치 프로그램을 사용하세요. curl 설치 프로그램은 자체 런타임을 포함하고 이 문제를 완전히 피합니다.
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://your-proxy: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, devcontainers 또는 엄격한 방화벽 뒤에서 흔합니다. 대신 수동 흐름을 사용하세요: 터미널에 인쇄된 URL을 복사하고 모든 브라우저에서 로그인을 완료한 후 반환된 코드를 터미널에 다시 붙여넣으세요.
8. ANTHROPIC_API_KEY를 설정했는데도 "인증되지 않음"
일반적인 원인 3가지: 키가 다른 셸에서 내보내졌습니다(echo $ANTHROPIC_API_KEY로 확인), 이전에 /login을 실행했고 OAuth 세션이 우선순위를 가집니다(/logout을 먼저 실행), 또는 키가 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이 실행되었고 GOOGLE_CLOUD_PROJECT가 설정되어 있는지 확인하세요.
10. 설치 및 인증되었지만 모든 요청이 403 / "모델을 사용할 수 없음" 오류로 실패합니다.
계정은 존재하지만 Claude Code가 요청하는 모델에 액세스할 수 없습니다. Enterprise 시트의 경우 조직의 관리자 설정에서 시트가 활성화되어 있는지 확인하세요. Bedrock 또는 Vertex에서 해당 지역 또는 프로젝트에서 특정 Claude 모델이 활성화되어 있는지 확인하세요. 빠른 해결 방법으로 /model을 실행하고 액세스 권한이 있는 모델을 선택하세요.
여전히 막혔나요?
Claude 세션 내부가 아닌 일반 셸에서 claude doctor를 실행하세요. 지원 티켓에 첨부할 수 있는 진단 보고서를 인쇄합니다.