command not found, 권한 에러, 로그인 실패, API 키 오류까지. Claude Code 설치와 인증 문제의 원인과 해결법을 케이스별로 정리.
Claude Code 가이드 #19 — Claude Code 설치가 안 되거나 인증이 실패할 때, 이 편 하나로 해결합니다. command not found, 권한 에러, 로그인 실패, API 키 오류까지 — 모든 설치·인증 문제의 원인과 해결법을 케이스별로 정리했습니다.
※ 이 글은 2026년 3월 기준, Claude Code 공식 문서 기반으로 작성됐습니다.
설치·인증 문제는 아래 순서로 진단하면 빠르게 원인을 좋힙니다.
which claude — 명령어가 PATH에 있는지node --version — 18 이상인지claude auth status — 로그인되어 있는지curl -I https://api.anthropic.com — API 접근 가능한지/doctor — 설치 상태 자동 점검각 단계에서 문제가 발견되면 아래 해당 섹션으로 이동하세요.
빠른 진단 명령어 모음# 1. claude 명령어 위치 확인 which claude || echo "claude not found in PATH" # 2. Node.js 버전 확인 (18+ 필요) node --version # 3. 인증 상태 확인 claude auth status # 4. API 접근 확인 curl -I https://api.anthropic.com # 5. 통합 진단 (설치 후 사용 가능) claude /doctor
가장 흔한 설치 문제입니다. 설치는 성공했지만 터미널에서 claude를 입력하면 명령어를 찾을 수 없다고 나옵니다.
원인: 설치 디렉토리가 쉘의 PATH 환경변수에 포함되어 있지 않습니다.
진단 명령어# PATH에 claude가 있는지 확인 which claude echo $PATH # npm 글로벌 경로 확인 (npm 설치인 경우) npm bin -g # 설치 위치 직접 확인 ls ~/.npm-global/bin/claude 2>/dev/null || ls /usr/local/bin/claude 2>/dev/null || echo "not found"
해결 — native installer로 재설치 (권장)# macOS / Linux: native installer로 재설치 (PATH 자동 설정) curl -fsSL https://claude.ai/install.sh | bash # 쉘 재시작 source ~/.zshrc # 또는 source ~/.bashrc
해결 — 수동 PATH 추가# npm 글로벌 경로를 PATH에 추가 export PATH="$HOME/.npm-global/bin:$PATH" # 영구 적용 (쉘 설정 파일에 추가) echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
command not found가 계속된다면 — npm list -g @anthropic-ai/claude-code로 설치 여부를 확인하세요. 출력이 없으면 설치 자체가 누락된 것입니다. native installer로 재설치하세요.npm 설치 시 권한 에러와 curl 설치 중 네트워크 끊김 문제입니다.
EACCES: permission denied가 발생하면 글로벌 npm 디렉토리의 권한 문제입니다.
해결 — npm 권한 수정# 방법 1: npm 디렉토리 소유권 변경 sudo chown -R $(whoami) ~/.npm # 방법 2: npm prefix 변경 (권장) npm config set prefix ~/.npm-global export PATH="$HOME/.npm-global/bin:$PATH" # 방법 3: native installer 사용 (npm 우회) curl -fsSL https://claude.ai/install.sh | bash
sudo npm install -g로 설치하면 이후 업데이트/삭제 시에도 계속 sudo가 필요해집니다. 처음부터 npm prefix를 변경하거나 native installer를 사용하세요.curl: (56) Recv failure: Connection reset by peer가 발생하면 네트워크 불안정, 방화벽, 또는 프록시가 원인입니다.
진단 및 해결# 네트워크 접근 확인 curl -I https://storage.googleapis.com # 프록시 환경인 경우 export HTTPS_PROXY=http://your-proxy:port curl -fsSL https://claude.ai/install.sh | bash # VPN 사용 시도 — 국가/기업 방화벽 우회
storage.googleapis.com과 api.anthropic.com 도메인 허용을 요청하세요. 일시적 끊김이라면 잠시 후 재시도하세요.운영체제나 시스템 환경에 따라 발생하는 설치 문제들입니다.
Claude Code는 Node.js 18 이상을 요구합니다.
진단 및 해결# 현재 버전 확인 node --version # nvm으로 Node.js 18+ 설치 nvm install 18 nvm use 18 # 또는 공식 사이트에서 직접 설치 # https://nodejs.org
Windows에서 Claude Code를 설치하려면 Git for Windows가 필수입니다. Git이 없으면 설치가 실패합니다.
해결 — Windows Git 설치 후 재시도# Git for Windows 설치 후: winget install Anthropic.ClaudeCode # 또는 PowerShell: irm https://claude.ai/install.ps1 | iex
실행 시 Illegal instruction으로 크래시되면 CPU 아키텍처와 바이너리가 불일치하는 것입니다.
진단 — CPU 아키텍처 확인# x86_64 = Intel/AMD, aarch64 = ARM64 uname -m # 우회: npm으로 설치 (네이티브 바이너리 대신) npm install -g @anthropic-ai/claude-code
설치 또는 실행 중 프로세스가 강제 종료되면 시스템 메모리 부족입니다.
진단 및 해결# 메모리 상태 확인 free -h # swap 추가 (메모리 부족 시) sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile
GLIBC_2.xx not found 또는 musl 관련 에러가 발생하면, 시스템의 C 라이브러리와 바이너리가 불일치하는 것입니다.
진단 및 해결# glibc vs musl 확인 ldd /bin/ls 2>&1 | head -1 ls /lib/libc.musl* 2>/dev/null # Alpine Linux (musl 기반) apk add bubblewrap socat # glibc 기반 배포판: 재설치로 올바른 바이너리 자동 감지 curl -fsSL https://claude.ai/install.sh | bash
claude --version으로 확인 후 업데이트하세요.설치는 됐는데 인증에서 막히는 케이스입니다.
인증 화면에서 진행이 안 되거나 에러가 발생합니다. 주요 원인은 구독 없음/만료, 네트워크 문제입니다.
진단 및 해결# 인증 상태 확인 claude auth status # 로그아웃 후 재로그인 claude auth logout claude auth login # 계정 전환 (다른 구독으로 바꿀 때) claude /login
구독 요구사항: Claude Code는 Pro($20/월), Max($100/월), Teams, Enterprise 구독 또는 Console(API 크레딧)이 필요합니다. 무료 플랜에서는 사용할 수 없습니다.
Invalid API Key 에러가 발생하면 키 형식이 맞는지 확인하세요.
API 키 확인 및 설정# API 키 길이 확인 (약 108자) echo $ANTHROPIC_API_KEY | wc -c # 키는 sk-ant- 접두사로 시작해야 함 echo $ANTHROPIC_API_KEY | cut -c1-7 # 출력: sk-ant- # API 키로 직접 인증 (Console 사용자) export ANTHROPIC_API_KEY=sk-ant-...
~/.zshrc)에 직접 넣으면 보안 위험이 있습니다. 대신 claude auth login으로 시스템 자격 증명 저장소를 사용하거나, .env 파일 + .gitignore로 관리하세요.이전에 잘 되던 인증이 갑자기 실패하는 경우입니다. 캐시된 인증 토큰이 만료된 것이 원인입니다.
해결 — 인증 초기화# 로그아웃 후 재로그인 claude auth logout claude auth login # Bedrock/Vertex AI 사용자는 해당 클라우드 자격 증명도 갱신 필요 # AWS: aws sso login # GCP: gcloud auth application-default login
어떤 계정을 써야 하는지 혼란스러운 경우입니다. 둘의 차이를 정리합니다.
| 항목 | Console (API) | 구독 (claude.ai) |
|---|---|---|
| 과금 | 사용량 기반 (선불 크레딧) | 월정액 ($20/$100) |
| 인증 방식 | API 키 (sk-ant-) | OAuth 브라우저 로그인 |
| 적합 대상 | 대량 사용, CI/CD | 개인 개발자 |
| 전환 | /login 명령으로 언제든 전환 가능 | |
402 Payment Required 에러가 발생합니다. console.anthropic.com에서 잔액을 확인하세요. 구독 계정은 월정액이라 이 문제가 없습니다.회사 네트워크나 VPN 환경에서는 설치와 인증 모두 실패할 수 있습니다. Claude Code는 아래 도메인에 접근이 필요합니다.
api.anthropic.com — API 호출claude.ai — OAuth 인증storage.googleapis.com — 설치 바이너리 다운로드프록시 설정 및 접근 확인# 프록시 환경변수 설정 export HTTPS_PROXY=http://your-proxy:port export HTTP_PROXY=http://your-proxy:port # API 접근 확인 curl -I https://api.anthropic.com curl -I https://claude.ai # SSL 인증서 문제 시 (기업 프록시) export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
UNABLE_TO_VERIFY_LEAF_SIGNATURE)가 발생하면, IT 팀에서 발급한 루트 CA 인증서를 NODE_EXTRA_CA_CERTS로 지정하세요.Claude Code에는 설치 상태를 자동으로 점검하는 /doctor 명령이 있습니다. 설치 후 문제가 있다면 가장 먼저 실행해보세요.
/doctor는 다음을 자동 점검합니다:
/doctor 실행# Claude Code 실행 상태에서: claude /doctor # 업데이트가 필요한 경우: # native installer: 자동 업데이트 brew upgrade claude-code # Homebrew winget upgrade Anthropic.ClaudeCode # WinGet npm update -g @anthropic-ai/claude-code # npm
claude --version, OS 버전, 에러 메시지 전문을 포함하면 빠른 답변을 받을 수 있습니다.설치·인증 문제의 80%는 아래 3가지로 해결됩니다:
claude auth logout → claude auth login — 인증 토큰 초기화/doctor 실행 — 통합 진단으로 누락된 문제 발견관련 가이드: