Claude Code 설치 방법 완벽 가이드 2026 (macOS/Windows/Linux)

Claude Code 설치는 npm install -g @anthropic-ai/claude-code 한 줄이면 됩니다. Node.js 18 이상이 필요하며, 설치 후 claude 명령어로 즉시 실행됩니다. 이 가이드는 macOS, Windows, Linux 모두 커버합니다.

사전 요구사항

Node.js 설치 (아직 없는 경우)

# macOS — Homebrew
brew install node

# Windows — winget
winget install OpenJS.NodeJS

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 설치 확인
node --version  # v20.x.x 이상 출력되면 OK

Claude Code 설치

npm install -g @anthropic-ai/claude-code

설치 확인:

claude --version
# claude-code/x.x.x 출력

권한 오류 발생 시 (macOS/Linux): sudo npm install -g @anthropic-ai/claude-code 대신 npx를 사용하거나 npm 글로벌 경로를 수정하세요 (아래 트러블슈팅 참고).

API 키 설정

방법 1: 환경변수 (권장)

# macOS/Linux — ~/.zshrc 또는 ~/.bashrc에 추가
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")

방법 2: claude 실행 시 자동 설정

claude
# 첫 실행 시 API 키 입력 프롬프트가 뜸
# 입력하면 ~/.claude/config.json에 저장

API 키 발급 방법

1. console.anthropic.com 접속
2. API Keys → Create Key
3. 키 이름 입력 후 생성 (예: claude-code-dev)
4. 생성된 sk-ant-api03-... 키를 복사

주의: API 키는 한 번만 보여집니다. 반드시 즉시 복사해서 안전한 곳에 저장하세요.

첫 실행

cd ~/my-project
claude

정상 실행 시:

Claude Code v1.x.x
Type /help to see available commands
>

첫 번째 명령 테스트:

> 이 프로젝트의 파일 구조를 설명해줘

운영체제별 특이사항

macOS

# Homebrew로 설치한 Node.js는 권한 문제 없음
# nvm 사용 시 — 현재 nvm 버전에서 설치
nvm use 20
npm install -g @anthropic-ai/claude-code

Apple Silicon (M1/M2/M3/M4) 지원: 완전 지원. Rosetta 불필요.

Windows

# PowerShell (관리자 모드)에서 실행
npm install -g @anthropic-ai/claude-code

# 실행 정책 오류 시
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

WSL2 권장: Windows에서 Claude Code를 가장 원활하게 사용하려면 WSL2(Ubuntu) 환경을 권장합니다.

# WSL2에서 설치
wsl
sudo apt-get update && sudo apt-get install -y nodejs npm
npm install -g @anthropic-ai/claude-code

Linux

# Ubuntu/Debian
sudo npm install -g @anthropic-ai/claude-code
# 또는 권한 없이
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

CLAUDE.md 초기 설정

프로젝트 디렉토리에서 실행:

cd ~/my-project
claude
/init

/init은 프로젝트 구조를 분석해 CLAUDE.md를 자동 생성합니다. 생성된 파일을 팀 Git 저장소에 커밋하면 팀 전체 컨텍스트 공유가 됩니다.

# 생성된 CLAUDE.md 예시
## 프로젝트: my-app
- 스택: Next.js 15, TypeScript, Tailwind
- 빌드: bun run build
- 테스트: bun test
- 배포: vercel --prod

IDE 통합

VS Code

# VS Code에서 Claude Code 터미널 열기
Ctrl+` (터미널 열기)
claude

Claude Code는 VS Code의 파일 시스템에 직접 접근합니다. 별도 확장 불필요.

Cursor

Cursor의 AI 기능과 Claude Code를 함께 사용하는 패턴:

• Cursor: 파일 편집, 자동완성
• Claude Code: 프로젝트 전체 작업, 멀티파일 리팩토링

트러블슈팅

"EACCES: permission denied" 오류

# npm 글로벌 디렉토리 권한 수정
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

"command not found: claude" 오류

# 설치 위치 확인
npm root -g
# /usr/local/lib/node_modules 또는 ~/.npm-global/lib/node_modules

# PATH 확인
echo $PATH
# npm 글로벌 bin 디렉토리가 PATH에 있어야 함

API 키 인증 실패

# 키 확인
echo $ANTHROPIC_API_KEY

# 키 직접 설정
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# 현재 셸에서만 적용. 영구 설정은 ~/.zshrc에 추가

Node.js 버전 미달

# 현재 버전 확인
node --version  # v16.x면 업그레이드 필요

# nvm으로 버전 관리
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20
npm install -g @anthropic-ai/claude-code

요금 안내

Claude Code 자체는 무료입니다. Anthropic API 사용 비용만 발생합니다.

하루 4시간 개발 기준 월 평균 $5-20 (Sonnet 기준). /model haiku로 반복 작업 처리 시 더 절약 가능.

Frequently Asked Questions

Claude Code 설치에 관리자 권한이 필요한가요?

macOS/Linux에서 ~/.npm-global에 설치하면 관리자 권한 불필요. Windows는 PowerShell 관리자 모드 또는 WSL2 권장.

Claude Code와 Claude.ai의 차이는?

Claude.ai는 웹 브라우저에서 사용하는 챗 인터페이스입니다. Claude Code는 터미널에서 실행하며 파일 시스템 직접 접근, 코드 실행, 멀티파일 편집이 가능한 개발자용 CLI 도구입니다.

오프라인에서 사용할 수 있나요?

아니요. Claude Code는 Anthropic API에 연결되므로 인터넷 연결이 필요합니다.

회사 프록시 환경에서 사용할 수 있나요?

export HTTPS_PROXY=http://proxy.company.com:8080
claude

프록시 환경변수 설정 후 사용 가능합니다.

무료로 사용할 수 있나요?

Claude Code CLI는 무료이나 API 비용이 발생합니다. Anthropic은 신규 가입 시 일부 무료 크레딧을 제공합니다.

관련 가이드: Claude Code 완전 가이드 한국어 · Claude Code 슬래시 커맨드 한국어 · Claude API 비용 계산 한국어

P1 Claude Code Power Prompts 300 — 설치 후 바로 쓸 수 있는 300개 검증 프롬프트. 개발 속도 3배 향상. 지금 확인 →