Claude Code는 터미널에서 작동하는 코딩 에이전트입니다. 2026년 기준 설치는 native installer가 권장되며, 과거 npm 글로벌 설치는 deprecated 됐습니다. Windows에서도 2025년 말부터 native로 직접 지원돼 WSL2 없이도 쓸 수 있습니다. 이 가이드는 macOS, Linux, Windows 전부 다룹니다.
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
설치 전에 Claude Code가 무엇이고 일반 챗봇·자동완성과 어떻게 다른지 궁금하다면 Claude Code란? 입문을 먼저 보세요.
구독 플랜 먼저 확인
Claude Code는 무료 플랜에선 사용할 수 없습니다. 다음 중 하나가 필요합니다.
- Pro ($20/월): 개인 일반 사용
- Max 5x ($100/월): 거의 매일 코딩
- Max 20x ($200/월): 풀타임 코딩, 멀티 에이전트
- Team / Enterprise: 조직 단위
- Anthropic Console (API 종량제): API 키로 사용 (구독 대신) — 키 발급 절차는 클로드 코드용 API 키 발급·연결 방법 참고
⚠️ ANTHROPIC_API_KEY 환경 변수가 설정돼 있으면 Pro/Max 구독 대신 API 키로 결제됩니다. 구독 사용을 원하면 키를 unset 하고 실행하세요.
시스템 요구 사항
- macOS: 13.0 (Ventura) 이상
- Linux: Ubuntu 20.04+ 또는 Debian 10+
- Windows: Windows 10 1809+ 또는 Windows Server 2019+ (PowerShell, CMD, Git Bash 또는 WSL2)
- RAM: 최소 4GB (8GB 권장)
- 인터넷: Anthropic 클라우드 API 통신 필요
- GPU: 불필요 (모든 추론은 Anthropic 서버)
1. macOS / Linux 설치 (native, 권장)
가장 빠른 방법입니다. Node.js 같은 의존성 없이 단일 바이너리로 설치되고, 백그라운드 자동 업데이트됩니다.
curl -fsSL claude.ai/install.sh | sh설치 후 새 터미널에서 검증:
claude --version
claude doctorclaude doctor는 설치 상태·PATH·권한·네트워크를 점검해 문제를 알려줍니다. 처음에 가장 먼저 실행해보세요.
2. Windows native 설치 (2025년 말 이후 공식 지원)
PowerShell에서 한 줄로 끝납니다.
irm claude.ai/install.ps1 | iex완료 후 새 PowerShell 창에서:
claude --version
claude doctorGit for Windows가 있으면 Git Bash에서도 동작합니다. 없으면 PowerShell로 자동 폴백합니다.
3. Windows WSL2 설치 (MCP 서버 호환성 우선)
MCP 서버 생태계가 macOS/Linux 기반으로 작성된 게 많아, MCP를 적극 활용한다면 WSL2가 더 안전합니다.
- 관리자 PowerShell에서:
wsl --install(재시작 필요할 수 있음) - Ubuntu가 기본 배포판으로 설치됨. Windows Terminal에서 Ubuntu 탭 열기
- Ubuntu 안에서 macOS/Linux와 같은 native 설치 명령 실행
⚠️ 프로젝트는 Windows 파일시스템(/mnt/c/...) 대신 Linux 파일시스템(~/projects/)에 두세요. 파일 I/O가 5~10배 빨라집니다.
4. npm 설치 (deprecated, 폴백용)
2026년 기준 npm 설치는 더 이상 권장되지 않지만 여전히 가능합니다. 특정 버전 고정이 필요한 경우에만 사용하세요.
npm install -g @anthropic-ai/claude-codev2.1.198부터 npm 패키지는 Node.js 22 이상을 요구합니다(더 낮으면 EBADENGINE 경고가 뜨지만 설치·실행은 됨 — 실행 파일은 네이티브 바이너리라 Node를 쓰지 않음, 2026년 9월 공식 setup 문서 기준). sudo를 절대 쓰지 마세요 — 권한 오류가 나면 sudo가 답이 아니라 nvm 사용이 정답입니다.
첫 실행 + 로그인
cd ~/your-project
claude처음 실행 시 브라우저 창이 자동으로 열리며 Anthropic 계정 로그인을 요구합니다. 로그인 후 터미널로 돌아가면 인증이 완료되고 작업을 시작할 수 있습니다.
자주 발생하는 문제 해결
자주 보고되는 증상과 해결을 먼저 한눈에 본 뒤, 아래에서 상세히 확인하세요.
claude: command not found: 새 터미널 열기 → 안 되면~/.zshrc나~/.bashrc에 PATH 추가 확인- MCP 서버가
spawn npx ENOENT에러: Windows native에서 자주 발생. WSL2로 전환 또는 Node.js LTS 재설치 후 PATH 갱신 - API 키와 구독이 충돌:
echo $ANTHROPIC_API_KEY로 확인. 구독을 쓰려면unset ANTHROPIC_API_KEY - 업데이트 안 됨:
claude update또는 native 재설치 - 권한(EACCES) 오류:
sudo로 설치하지 마세요(오히려 꼬입니다).npm config set prefix ~/.npm-global후~/.npm-global/bin을 PATH에 추가하거나, nvm으로 홈 디렉터리에 Node를 설치하세요 - WSL에서
node: not found:which node결과가/mnt/c/로 시작하면 윈도우의 Node가 새어든 상태입니다. 리눅스 배포판이나 nvm으로 Node를 설치하세요 - 원인을 모를 때 먼저
claude doctor: 설치 경로·인증 상태·권한·Node 버전을 한 번에 진단해 줍니다
다음 단계
설치가 끝났으면:
- CLAUDE.md 작성 가이드 — 프로젝트 컨텍스트를 모델에게 제공하는 방법
- MCP란? — 외부 도구 연결 표준
더 알아보기: Claude Code 권한 설정으로 allow·deny 규칙과 권한 모드를 통제할 수 있습니다.
더 알아보기: Claude Code IDE 연동 가이드 (VS Code·JetBrains)
함께 보면 좋은 글: Claude Code 가격 총정리 — 플랜 포함 범위와 API 요금