Claude Code 가이드

Claude Code 가이드 #19 — 설치~인증 트러블슈팅

command not found, 권한 에러, 로그인 실패, API 키 오류까지. Claude Code 설치와 인증 문제의 원인과 해결법을 케이스별로 정리.

2026-03-06

Claude Code 가이드 #19 — Claude Code 설치가 안 되거나 인증이 실패할 때, 이 편 하나로 해결합니다. command not found, 권한 에러, 로그인 실패, API 키 오류까지 — 모든 설치·인증 문제의 원인과 해결법을 케이스별로 정리했습니다.

※ 이 글은 2026년 3월 기준, Claude Code 공식 문서 기반으로 작성됐습니다.

이 편의 사용법 — 진단 순서

설치·인증 문제는 아래 순서로 진단하면 빠르게 원인을 좋힙니다.

설치 확인: which claude — 명령어가 PATH에 있는지
Node.js 버전: 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

command not found: claude

가장 흔한 설치 문제입니다. 설치는 성공했지만 터미널에서 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

⚠️ 막히는 케이스: PATH를 수정했는데도 command not found가 계속된다면 — npm list -g @anthropic-ai/claude-code로 설치 여부를 확인하세요. 출력이 없으면 설치 자체가 누락된 것입니다. native installer로 재설치하세요.

권한 에러와 네트워크 문제

npm 설치 시 권한 에러와 curl 설치 중 네트워크 끊김 문제입니다.

npm install 권한 에러 (EACCES)

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 설치 중 끊김 (Broken pipe)

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 사용 시도 — 국가/기업 방화벽 우회

⚠️ 막히는 케이스: 회사 네트워크에서 설치가 반복 실패한다면, IT 팀에 storage.googleapis.com과 api.anthropic.com 도메인 허용을 요청하세요. 일시적 끊김이라면 잠시 후 재시도하세요.

OS 및 환경별 설치 문제

운영체제나 시스템 환경에 따라 발생하는 설치 문제들입니다.

Node.js 버전 부족 (18 미만)

Claude Code는 Node.js 18 이상을 요구합니다.

진단 및 해결
# 현재 버전 확인
node --version

# nvm으로 Node.js 18+ 설치
nvm install 18
nvm use 18

# 또는 공식 사이트에서 직접 설치
# https://nodejs.org

Windows: Git 미설치

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 크래시

실행 시 Illegal instruction으로 크래시되면 CPU 아키텍처와 바이너리가 불일치하는 것입니다.

진단 — CPU 아키텍처 확인
# x86_64 = Intel/AMD, aarch64 = ARM64
uname -m

# 우회: npm으로 설치 (네이티브 바이너리 대신)
npm install -g @anthropic-ai/claude-code

OOM Killed (메모리 부족)

설치 또는 실행 중 프로세스가 강제 종료되면 시스템 메모리 부족입니다.

진단 및 해결
# 메모리 상태 확인
free -h

# swap 추가 (메모리 부족 시)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

glibc/musl 라이브러리 오류 (Linux)

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

⚠️ 막히는 케이스: RHEL 8 등 구버전 glibc 환경에서는 Claude Code v2.1.50 이상이 필요합니다. claude --version으로 확인 후 업데이트하세요.

설치는 됐는데 인증에서 막히는 케이스입니다.

로그인 실패

인증 화면에서 진행이 안 되거나 에러가 발생합니다. 주요 원인은 구독 없음/만료, 네트워크 문제입니다.

진단 및 해결
# 인증 상태 확인
claude auth status

# 로그아웃 후 재로그인
claude auth logout
claude auth login

# 계정 전환 (다른 구독으로 바꿀 때)
claude /login

구독 요구사항: Claude Code는 Pro($20/월), Max($100/월), Teams, Enterprise 구독 또는 Console(API 크레딧)이 필요합니다. 무료 플랜에서는 사용할 수 없습니다.

API Key 형식 오류

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-...

⚠️ 막히는 케이스: API 키를 쉘 설정 파일(~/.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 vs 구독 혼동

어떤 계정을 써야 하는지 혼란스러운 경우입니다. 둘의 차이를 정리합니다.

항목	Console (API)	구독 (claude.ai)
과금	사용량 기반 (선불 크레딧)	월정액 ($20/$100)
인증 방식	API 키 (`sk-ant-`)	OAuth 브라우저 로그인
적합 대상	대량 사용, CI/CD	개인 개발자
전환	`/login` 명령으로 언제든 전환 가능

⚠️ 막히는 케이스: Console 계정의 크레딧이 소진되면 402 Payment Required 에러가 발생합니다. console.anthropic.com에서 잔액을 확인하세요. 구독 계정은 월정액이라 이 문제가 없습니다.

VPN/프록시 환경에서의 인증 문제

회사 네트워크나 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

💡 팁: 기업 프록시에서 SSL 인증서 오류(UNABLE_TO_VERIFY_LEAF_SIGNATURE)가 발생하면, IT 팀에서 발급한 루트 CA 인증서를 NODE_EXTRA_CA_CERTS로 지정하세요.

/doctor로 한 번에 진단하기

Claude Code에는 설치 상태를 자동으로 점검하는 /doctor 명령이 있습니다. 설치 후 문제가 있다면 가장 먼저 실행해보세요.

/doctor는 다음을 자동 점검합니다:

Node.js 버전
Claude Code 버전 및 업데이트 상태
인증 상태
네트워크 접근성
필수 의존성 (Linux: bubblewrap, socat)

/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

💡 팁: 문제가 해결되지 않으면 GitHub Issues에 버그 리포트를 제출하세요. claude --version, OS 버전, 에러 메시지 전문을 포함하면 빠른 답변을 받을 수 있습니다.

요약 및 관련 편

설치·인증 문제의 80%는 아래 3가지로 해결됩니다:

native installer로 재설치 — PATH, 권한, 업데이트 문제를 한 번에 해결
claude auth logout → claude auth login — 인증 토큰 초기화
/doctor 실행 — 통합 진단으로 누락된 문제 발견