Claude Code 가이드 #19 — Claude Code 설치가 안 되거나 인증이 실패할 때, 이 편 하나로 해결합니다. command not found , 권한 에러, 로그인 실패, API 키 오류까지 — 모든 설치·인증 문제의 원인과 해결법을 케이스별로 정리했습니다. 설치·인증 문제는 아래 순서로 진단하면 빠르게 원인을 좋힙니다.
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 Code 실전 강의 — AI 코딩을 지금 시작하세요
설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.
가장 흔한 설치 문제입니다. 설치는 성공했지만 터미널에서 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 실행 — 통합 진단으로 누락된 문제 발견관련 가이드:
🎓 관련 강의
Claude Code 완전 정복 — 유데미 강의
이 글에서 다룬 내용을 더 체계적으로 배우고 싶다면 강의를 확인해보세요. 실전 예제 중심으로 구성되어 있습니다.
설치·인증 문제는 공식 트러블슈팅 문서(code.claude.com/docs/en/troubleshooting)가 1차 자료입니다. 여기서 native installer 재설치, PATH 설정, /doctor 진단 항목을 그대로 따라 하면 됩니다. 같은 증상이 안 풀리면 GitHub Issues에서 EACCES, GLIBC_2.xx not found, Illegal instruction 같은 에러 메시지를 그대로 검색해 OS·아키텍처별 사례를 찾으세요. 키워드로는 npm prefix 변경, nvm 으로 Node.js 18+ 설치, NODE_EXTRA_CA_CERTS(기업 프록시 SSL), Console과 구독 계정의 인증 차이를 짚어 두면 대부분의 설치·로그인 막힘을 스스로 진단할 수 있습니다.
command not found, EACCES 권한 에러, 로그인 실패, Invalid API Key까지 설치·인증 단계의 막힘을 증상별로 진단하는 글입니다. 핵심 결론은 추측하지 말고 순서대로 점검하라는 것입니다. which claude로 PATH, node --version으로 18+, claude auth status로 로그인, curl로 api.anthropic.com 접근을 차례로 확인하면 됩니다. 그래도 안 잡히면 문제의 80%는 native installer 재설치, claude auth logout 후 재로그인, 그리고 claude /doctor 통합 진단 이 세 가지로 해결됩니다.
설치나 인증이 막히면 추측하지 말고 정해진 진단 순서를 따르는 것이 가장 빠릅니다. which claude로 명령어가 PATH에 있는지, node --version으로 Node.js 18 이상인지, claude auth status로 로그인 상태인지, curl -I https://api.anthropic.com으로 API 접근이 되는지를 차례로 확인하세요. 그래도 원인이 안 잡히면 claude /doctor를 실행하면 버전, 인증, 네트워크, Linux 필수 의존성(bubblewrap, socat)까지 한 번에 점검해 어느 단계가 깨졌는지 알려줍니다. 이 순서면 대부분의 문제를 몇 분 안에 좁힐 수 있습니다.
설치 단계에서 가장 후회하는 실수는 sudo npm install -g로 설치하는 것입니다. 이렇게 깔면 이후 업데이트와 삭제 때도 계속 sudo가 필요해지고 권한이 꼬입니다. 처음부터 npm config set prefix로 사용자 디렉토리에 깔거나 native installer를 쓰는 편이 깔끔합니다. 두 번째 함정은 command not found가 떴을 때 무작정 PATH만 만지는 것입니다. npm list -g @anthropic-ai/claude-code로 설치 자체가 됐는지 먼저 확인해야 합니다. 출력이 없으면 PATH 문제가 아니라 설치 누락이니 재설치가 답입니다. 인증 쪽에서는 API 키를 ~/.zshrc에 평문으로 박아두는 것이 흔한 실수로, claude auth login이나 .env + .gitignore 조합으로 관리하는 것이 안전합니다.
설치 방식부터 보면, macOS와 Linux에서는 PATH와 권한을 한 번에 잡아 주는 native installer(curl install.sh)가 기본으로 적합합니다. 회사 방화벽이나 프록시 뒤라 storage.googleapis.com 접근이 막히는 환경이라면 native 다운로드가 실패하니 npm install -g 쪽이 더 잘 통합니다. Windows는 Git for Windows를 먼저 깔아야 합니다. 계정은 용도로 갈립니다. 혼자 쓰는 개인 개발자라면 월정액이 예측 가능한 구독(Pro/Max)에 OAuth 로그인이 편하고, CI/CD나 대량 자동화처럼 사용량이 크고 키 기반 인증이 필요한 경우엔 sk-ant- API 키를 쓰는 Console이 맞습니다. 둘은 /login 명령으로 언제든 전환할 수 있고, 무료 플랜에서는 어느 쪽도 쓸 수 없다는 점만 기억하면 됩니다.
