클로드 코드 설치, 막막하셨죠? (저도 그랬습니다)
저는 개발자가 아닙니다. 그래서 처음 “터미널에 명령어를 치라”는 말을 들었을 때 겁부터 났어요. 그런데 막상 해보니 Node.js 설치 → 명령어 한 줄 → 실행, 딱 세 단계면 끝나더라고요. 이 글에서는 제가 윈도우에서 실제로 설치하며 막혔던 부분(그 유명한 PATH 오류까지)을 그대로 공유하면서, 윈도우와 맥 각각의 설치법을 단계별로 알려드리겠습니다.
Node.js(노드JS — 자바스크립트를 컴퓨터에서 실행하게 해주는 프로그램)만 먼저 깔려 있으면, 나머지는 정말 명령어 한 줄로 끝납니다.
설치 전 필수 확인: 시스템 요구사항
Claude Code를 설치하기 전에 아래 조건을 먼저 확인하세요.
| 항목 | 요구사항 |
|---|---|
| Node.js 버전 | 22 이상 권장 |
| 운영체제 | Windows 10/11, macOS 12 이상 |
| 계정 | Claude Pro/Max/Teams 구독 또는 API 콘솔 계정 |
| 인터넷 연결 | 설치 시 필수 |
Node.js란? 자바스크립트(JavaScript) 코드를 웹 브라우저 밖에서도 실행할 수 있게 해주는 런타임 환경(실행 프로그램)입니다. Claude Code가 이 위에서 동작합니다.
1단계: Node.js 설치하기 (윈도우·맥 공통)
🪟 윈도우 (Windows)
- nodejs.org 공식 사이트에 접속합니다.
- LTS(Long Term Support — 장기 지원 버전) 버튼을 클릭해 설치 파일을 받습니다.
- 다운로드된
.msi파일을 실행하고 “다음 → 다음 → 설치” 순서로 진행합니다. - 설치 완료 후, PowerShell 또는 명령 프롬프트(cmd)를 새로 열어 버전을 확인합니다:
node -v
npm -v
v22.x.x 형태로 버전이 출력되면 성공입니다.
🍎 맥 (macOS)
맥에서도 nodejs.org에서 .pkg 파일을 받아 설치할 수 있습니다. 다만 Homebrew(홈브루 — 맥용 패키지 관리자)를 사용하는 방법이 더 편리합니다:
# Homebrew 설치 (이미 있으면 건너뜁니다)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Node.js 설치
brew install node
설치 후 터미널에서 node -v로 버전을 확인하세요.
2단계: Claude Code 설치하기 (npm 명령어 한 줄)
Node.js 설치가 완료됐다면, 이제 Claude Code를 설치할 차례입니다. npm(Node Package Manager — Node.js에서 사용하는 패키지 설치 도구)을 이용해 전역(컴퓨터 어디서든 실행 가능하도록) 설치합니다.
윈도우 PowerShell 또는 맥 터미널에서 아래 명령어를 실행하세요:
npm install -g @anthropic-ai/claude-code
⚠️ 중요 주의사항: 맥·리눅스에서
sudo를 절대 붙이면 안 됩니다.sudo npm install -g는 권한 문제와 보안 오류를 일으킬 수 있습니다.
설치 후 아래 명령어로 정상 설치 여부를 확인합니다:
claude --version
버전 번호가 출력되면 설치 성공입니다!
3단계: 첫 실행 및 계정 로그인
설치 후 작업할 프로젝트 폴더로 이동해 claude를 실행합니다.
cd 내_프로젝트_폴더
claude
처음 실행 시 Anthropic 계정 로그인 화면이 나타납니다. 브라우저가 자동으로 열리며 로그인 절차가 진행됩니다.
- Claude Pro/Max 구독자: claude.ai 계정으로 로그인
- API 사용자: Anthropic Console 계정으로 로그인 후 API 키 입력
로그인이 완료되면 터미널에 > 프롬프트가 뜨고, 이제 Claude Code와 대화를 시작할 수 있습니다!
claude로 첫 실행까지.제가 설치하며 실제로 막혔던 부분 (PATH 오류)
솔직히 저는 한 번에 되지 않았습니다. 윈도우에서 설치를 다 끝냈는데도 claude를 치니 “명령을 찾을 수 없습니다”가 떴어요. 알고 보니 PATH(프로그램 위치를 운영체제에 알려주는 설정)가 아직 적용되지 않은 거였습니다. 터미널을 완전히 닫았다가 새로 여니 바로 해결됐습니다. 저처럼 헤매지 마시라고, 이런 흔한 오류들을 아래 FAQ에 정리해 뒀습니다.
윈도우 vs 맥, 이것만 주의하세요
| 구분 | 윈도우 주의사항 | 맥 주의사항 |
|---|---|---|
| 터미널 | PowerShell 권장 | 기본 터미널 또는 iTerm2 |
| Git | 별도 설치 필요 (git-scm.com) | Xcode Command Line Tools로 설치 |
| sudo | 사용 안 함 | 절대 사용 금지 |
| 흔한 오류 | PATH 환경변수 설정 오류 | npm 권한(permission) 오류 |
| 업그레이드 | npm install -g @anthropic-ai/claude-code@latest |
동일 |
Git이란? 코드 변경 이력을 관리하는 버전 관리 도구입니다. Claude Code가 Git 기능을 활용하므로 함께 설치해 두는 것을 권장합니다.
자주 묻는 질문 (FAQ)
Q. claude 명령어를 쳤는데 “명령을 찾을 수 없습니다” 오류가 납니다.
A. Node.js를 설치했어도 PATH 환경변수(프로그램 위치를 운영체제에 알려주는 설정)가 아직 적용되지 않은 경우입니다. 윈도우에서는 터미널을 완전히 닫고 새로 열어보세요. 맥에서는 source ~/.zshrc 또는 source ~/.bash_profile을 실행한 뒤 다시 시도하면 해결되는 경우가 많습니다.
Q. npm install 중 EACCES 또는 permission denied 오류가 납니다.
A. 절대 sudo를 붙이지 마세요. 대신 npm 전역 설치 경로를 사용자 폴더로 변경하면 됩니다. 터미널에 npm config set prefix ~/.npm-global을 실행한 후, PATH에 ~/.npm-global/bin을 추가하면 해결됩니다.
Q. Node.js 버전이 20인데 설치 가능한가요?
A. 기술적으로 설치는 되지만 Node.js 22 이상을 권장합니다. 버전이 낮으면 EBADENGINE 경고 메시지가 뜨고 일부 기능이 불안정할 수 있습니다. nvm(Node Version Manager — 노드 버전 관리 도구)을 사용하면 버전 전환이 간편합니다.
한 줄 요약: Node.js 22 설치 → npm install -g @anthropic-ai/claude-code → claude 실행 → 로그인, 이 네 단계면 클로드 코드 설치가 완료됩니다. 설치 후 뭘 할 수 있는지는 클로드 코드란? ChatGPT와 뭐가 다를까 완전 비교 편을 함께 보시면 좋습니다.
참고 자료
– Claude Code 공식 설치 문서 (code.claude.com)
– @anthropic-ai/claude-code npm 공식 패키지 페이지
– Claude Code GitHub 공식 저장소 (anthropics/claude-code)