설치·설정·인증 완벽 정리 | 클로드 코드 완벽 마스터: AI 개발 워크플로우

설치·설정·인증 — 처음 한 번만 제대로 하기

Claude Code 설정에서 막히는 지점은 대부분 세 곳입니다: API 키 발급, 환경변수 설정, 그리고 프로젝트 폴더에서 인식이 안 되는 경우. 이 강에서는 각 단계를 OS별로 구체적으로 설명하고, 흔한 오류 해결법까지 포함합니다.

1단계: Node.js 버전 확인

Claude Code는 Node.js 18 이상이 필요합니다. 먼저 버전을 확인하세요.

node --version
# v18.0.0 이상이어야 함

# 낮은 버전이면 nvm으로 업그레이드 (Mac/Linux)
nvm install 20
nvm use 20

# Windows (winget)
winget install OpenJS.NodeJS.LTS

2단계: Claude Code 설치

# 전역 설치 (권장)
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

# 권한 오류 시 (Mac/Linux)
sudo npm install -g @anthropic-ai/claude-code
# 또는 npm 전역 경로 변경 (더 안전한 방법)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3단계: Anthropic API 키 발급

Claude Code는 Anthropic API를 사용합니다. API 키가 없으면 작동하지 않습니다.

console.anthropic.com 접속 → 계정 생성 또는 로그인
좌측 메뉴 → API Keys → Create Key
키 이름 입력 (예: "claude-code-dev") → 생성
생성된 키를 즉시 복사 (다시 볼 수 없음)

요금 정책: Claude Code는 API 사용량에 따라 과금됩니다. Claude Opus 4 기준 입력 토큰 $15/1M, 출력 토큰 $75/1M. 일반적인 개발 작업에서 하루 $1~3 수준이며, 대화가 길어지면 비용이 증가합니다. console.anthropic.com → Usage에서 실시간 확인 가능합니다.

4단계: 환경변수 설정

# Mac / Linux (.bashrc 또는 .zshrc에 추가)
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"

# 적용
source ~/.zshrc  # 또는 source ~/.bashrc

# Windows (PowerShell — 영구 설정)
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-xxx", "User")

# 또는 Windows 시스템 환경변수 UI
# 제어판 → 시스템 → 고급 시스템 설정 → 환경 변수

환경변수 대신 첫 실행 시 대화형으로 입력할 수도 있습니다. claude를 처음 실행하면 API 키 입력을 요청합니다.

5단계: 첫 실행과 인증 확인

# 프로젝트 폴더로 이동
cd ~/Projects/my-project

# 대화형 모드 시작
claude

# 정상 작동 확인용 첫 명령
> 이 프로젝트의 파일 구조를 간략히 설명해줘

# 헤드리스 모드로 빠른 테스트
claude -p "현재 디렉토리의 파일 목록을 보여줘" --allowedTools "Bash(ls*)"

IDE 연동 (VS Code)

터미널 외에도 VS Code 내장 터미널에서 바로 사용할 수 있습니다. 별도 익스텐션 없이 VS Code 터미널에서 claude를 실행하면 됩니다.

# VS Code에서 터미널 열기: Ctrl+` (백틱)
# Claude Code 실행
claude

# 파일 편집 후 Claude에게 리뷰 요청
> 방금 수정한 파일 중 개선할 부분 있어?

JetBrains IDE(IntelliJ, WebStorm 등)도 동일하게 내장 터미널에서 사용합니다.

흔한 오류와 해결법

# 오류: command not found: claude
→ npm 전역 경로가 PATH에 없음
→ which npm으로 경로 확인 후 ~/.bashrc에 추가

# 오류: AuthenticationError: invalid x-api-key
→ API 키 복사 오류 (공백 포함 여부 확인)
→ echo $ANTHROPIC_API_KEY 로 현재 설정값 확인

# 오류: RateLimitError
→ API 크레딧 소진 또는 분당 요청 한도 초과
→ console.anthropic.com에서 잔액 확인

# 오류: Context length exceeded
→ 대화가 너무 길어짐 → /clear 로 컨텍스트 초기화

설정 파일 위치 정리

~/.claude/                     # 전역 Claude Code 설정
~/.claude/settings.json        # 전역 권한·훅 설정
~/.claude/commands/            # 개인 전역 슬래시 명령

프로젝트루트/.claude/          # 프로젝트 전용 설정
프로젝트루트/.claude/settings.json  # 프로젝트 권한·훅
프로젝트루트/.claude/commands/ # 프로젝트 슬래시 명령
프로젝트루트/CLAUDE.md         # 프로젝트 컨텍스트 문서

설치 후 가장 먼저 할 것: 자주 사용하는 프로젝트 폴더에서 claude를 실행하고 "이 프로젝트가 뭘 하는 프로젝트인지 파악해줘"라고 입력해보세요. Claude가 파일들을 읽고 프로젝트를 파악하는 과정을 보면 이 도구의 가능성을 직관적으로 이해하게 됩니다.

핵심 정리

Node.js 18+ → npm install -g @anthropic-ai/claude-code → ANTHROPIC_API_KEY 환경변수 설정 — 3단계로 완료
설정 파일 두 층: ~/.claude/(전역) + 프로젝트/.claude/(프로젝트별) — 프로젝트별 다른 권한·명령 설정 가능
API 비용은 사용량 기반 — console.anthropic.com에서 실시간 모니터링, 하루 $1~3 수준이 일반적

관련 검색어 · 클로드 코드 설치 · Claude Code 설치법 · Anthropic API 키 · 클로드 코드 설정 · Claude Code 환경변수 · 클로드 코드 인증 · AI 개발 도구 설치