Claude Code가 설치되지 않거나 로그인이 안 될 때, 원인은 대부분 정해진 몇 가지 범주에 들어갑니다. 이 글은 Claude 공식 문제 해결 문서에서 확인된 항목만 추려 정리합니다. (기준 시점: 2026년 6월. 명령·요건은 변동될 수 있으니 공식 문서에서 최신 정보를 확인하세요.)
먼저 확인할 기본
- Node 버전: Claude Code는 Node 18 이상이 필요합니다.
node -v로 확인하세요(설치 시점의 정확한 최소 버전은 공식 문서로 확인 권장). - 서비스 상태: 광범위한 장애가 의심되면 status.claude.com에서 상태를 확인하세요.
- 인터넷 연결: Claude Code는 Anthropic 서버에 접속해야 동작합니다.
설치 문제
- "command not found" / claude 명령이 안 잡힘: 설치가 PATH에
claude를 추가했지만 현재 셸이 아직 반영하지 못한 경우입니다. 새 터미널을 열거나source ~/.zshrc(또는~/.bashrc)를 실행하세요. Windows는 PowerShell을 닫았다 다시 엽니다. - 권한 오류: 보통
sudo로 설치했거나 글로벌 npm 디렉토리가 root 소유일 때 발생합니다. sudo를 쓰지 마세요. 대신 native installer를 쓰거나, npm prefix를~/.npm-global로 바꾸고 그 bin 경로를 PATH에 추가하세요. - Node 버전이 낮음:
nvm install --lts로 최신 LTS를 설치하거나, 자체 런타임을 번들하는 native installer를 쓰면 이 문제를 피할 수 있습니다. - 다운로드가 막힘: 회사 네트워크가 다운로드 호스트를 차단했을 수 있습니다. 프록시를 먼저 설정(
export HTTPS_PROXY=...)한 뒤 재설치하거나, IT팀에 오프라인 패키지를 요청하세요. - 회사 인증서: 사내에서 자체 인증서를 주입하면 Node가 인증서를 거부할 수 있습니다.
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem로 사내 CA 번들을 가리키게 하고, 셸 프로필에 추가해 유지하세요.
# Node 버전 확인 (18 이상 필요)
node -v
# sudo 없이 설치 (권한 오류 회피). 둘 중 하나:
curl -fsSL https://claude.ai/install.sh | bash # native installer
npm config set prefix ~/.npm-global # 또는 npm prefix 수정
# 회사 네트워크: 프록시 / 사내 인증서
export HTTPS_PROXY=http://proxy.example.com:port
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem
# API 키가 인식되는지 확인
echo $ANTHROPIC_API_KEY인증·로그인 문제
- 브라우저가 자동으로 안 열림: 로그인 중 브라우저가 안 열리면
c를 눌러 OAuth URL을 클립보드에 복사한 뒤, 아무 브라우저에서 열어 로그인하세요. - localhost 콜백이 막힘: 원격 SSH·devcontainer·엄격한 방화벽 환경에서 흔합니다. 자동 흐름 대신 수동 흐름을 쓰세요 — 터미널에 출력된 URL을 복사해 브라우저에서 로그인하고, 반환된 코드를 다시 터미널에 붙여넣습니다. 헤드리스 환경(CI/CD·Docker)이면
ANTHROPIC_API_KEY를 설정해 OAuth를 우회할 수 있습니다. - API 키가 인식되지 않음: 키가 다른 셸에서 export되었을 수 있으니
echo $ANTHROPIC_API_KEY로 현재 셸에서 보이는지 확인하세요. 또 Claude Code가 이 키를 신뢰하도록 첫 사용 시 한 번 확인 프롬프트가 뜹니다. - 그래도 안 되면 깨끗한 재인증: 로그인이 실패하고 원인이 불분명하면, 재인증으로 대부분 해결됩니다.
claude를 다시 실행해 인증 과정을 처음부터 다시 진행하세요. - IDE에서만 안 됨: 터미널에선 되는데 VS Code·JetBrains 확장에서 안 되면, IDE 프로세스가 셸 환경변수를 상속하지 못한 경우입니다. IDE 자체 설정에 환경변수를 지정하거나, 변수가 이미 export된 터미널에서 IDE를 실행하세요.
성능·안정성
공식 문제 해결 문서는 높은 CPU/메모리 사용과 명령이 멈추거나 얼어붙는(hang/freeze) 경우도 별도 항목으로 다룹니다. 일반적인 예방책으로는 Node를 최신으로 유지하고, 안정적인 인터넷을 쓰고, 막혔을 때 세션을 재시작하는 것이 권장됩니다. 구체적인 진단·해법은 환경에 따라 다르므로 공식 문서의 해당 섹션을 참고하세요.
정리
핵심 점검 순서: ① Node 18 이상·서비스 상태·인터넷부터 확인, ② 설치 문제는 PATH 새로고침 → sudo 금지 → native installer, ③ 인증 문제는 수동 OAuth 흐름 또는 API 키, 안 되면 재인증, ④ 성능 문제는 Node 최신화·세션 재시작. 더 자세한 항목은 Claude Code 공식 문제 해결 문서를 참고하세요.
이 글의 해법은 Claude 공식 문서(support.claude.com, code.claude.com)에서 확인한 항목만 담았습니다. 환경(OS·네트워크·IDE)에 따라 증상과 해법이 다를 수 있으므로, 해결되지 않으면 공식 문서와 지원 채널을 이용하세요. (공식 출처: docs.claude.com)