파트너식스
AI 아카데미
로그인
슬라이드 열기 (새 창)모바일에서는 새 창에서 열립니다
미리보기

Claude Code 설치

01강 · Claude Code 설치 — 맥·윈도우 양쪽에서 claude 명령이 뜨게 하기

코스: Claude 개발 마스터 — 왕초보에서 SaaS 출시까지 A-Z 차시: 1 / 225 모듈: 1 · 개발 환경 셋업 슬러그: claude-dev-saas-mastery

학습 목표

  • 맥 또는 윈도우 터미널에서 claude --version 명령이 에러 없이 실행되게 만든다
  • Anthropic API 키 또는 Claude Code Plus 구독으로 로그인하고 첫 claude 세션을 연다
  • 설치 중 자주 막히는 5가지 에러(Node.js 버전·PATH·권한·방화벽·로그인 실패)의 원인과 해결법을 안다

도입 — 왜 "claude" 한 글자가 출발점인가

225강짜리 마라톤을 시작한다. 이 마라톤의 첫 발짝은 ChatGPT에게 질문하기가 아니라 내 컴퓨터에서 claude 한 단어를 칠 수 있게 만드는 것이다. Claude Code는 Anthropic이 공식 배포하는 CLI 도구로, ChatGPT의 웹 인터페이스와 달리 내 로컬 파일을 직접 읽고 수정하고 실행한다. 이게 왜 중요하냐 — 앞으로 우리가 만들 SaaS는 파일 수천 개짜리 프로젝트가 된다. 매번 코드를 복붙해서 웹에 붙여넣고 답장 받아서 다시 복붙하는 방식으로는 6개월이 걸려도 MVP가 안 나온다. claude 한 줄만 치면 현재 폴더의 전체 코드베이스를 문맥으로 이해하는 짝코더가 붙는다. 이게 2026년 현재 1인 SaaS의 표준 워크플로다.

많은 왕초보가 여기서 막힌다. "Node.js가 뭐예요" "터미널이 어디예요" "권한 에러가 떠요" 같은 질문이 폭포처럼 쏟아진다. 이 강의는 맥·윈도우·리눅스 세 환경을 클릭·명령어 단위로 훑는다. 한 번에 안 되더라도 실수 5가지 매트릭스를 보면서 자가 진단한다.

핵심 개념

Claude Code는 npm 패키지다. npm install -g @anthropic-ai/claude-code 명령으로 전역 설치하면 터미널 어디서든 claude 명령을 쓸 수 있다. 그러니 npm이 필요하고, npm은 Node.js에 포함돼 있다. 결론: Node.js 20 이상만 깔려 있으면 Claude Code는 5분 안에 설치된다.

인증 방식 두 가지. (1) Anthropic Console에서 발급받는 API 키 — 사용한 만큼 과금 (2) Claude Pro/Max 구독 — 월 정액. 이 강의는 구독 방식 기준(월 $20~$200, 한국 약 2.8~28만원). 초반 연습은 API 키도 충분하지만 강의 중반부터 대규모 리팩터링을 자주 하기에 구독이 유리하다.

PATH 이해. 터미널에서 claude 하나만 쳤을 때 시스템은 "이 명령을 어디서 찾지?"라고 묻는다. 그 답이 PATH 환경변수다. npm 전역 설치 위치(~/.npm-global/bin 또는 /usr/local/bin)가 PATH에 들어있어야 claude가 바로 인식된다. 이게 빠지면 "command not found" 에러가 난다.

실행 단계

맥 (macOS) 설치

# 1) Homebrew 설치 (이미 있으면 스킵)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2) Node.js 20 설치
brew install node@20
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 3) Node·npm 버전 확인 (20 이상이어야 함)
node --version   # v20.x.x
npm --version    # 10.x.x

# 4) Claude Code 전역 설치
npm install -g @anthropic-ai/claude-code

# 5) 버전 확인
claude --version

# 6) 첫 로그인
claude
# → 브라우저 창이 뜨면서 Anthropic 로그인 유도 → 구독 계정으로 로그인

윈도우 설치

# 1) PowerShell 관리자 권한으로 열기
# 2) Scoop 또는 NVM for Windows로 Node 설치
winget install OpenJS.NodeJS.LTS
# 또는 https://nodejs.org 에서 LTS 직접 다운로드 & 설치

# 3) 재부팅 또는 새 PowerShell 열기 후 확인
node --version
npm --version

# 4) Claude Code 설치
npm install -g @anthropic-ai/claude-code

# 5) PowerShell 실행 정책 확인 (권한 에러 시)
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

# 6) 첫 로그인
claude

첫 세션 열기

# 아무 폴더나 만들어서 들어가기
mkdir ~/claude-test
cd ~/claude-test

# claude 실행
claude

# 프롬프트: "안녕. 이 폴더에 hello.md 파일 만들어서 '안녕하세요 Claude입니다' 한 줄 써줘"
# Claude가 파일을 만들면 성공

Good vs Bad 설치 진행

Good

  • node --version이 v20.x.x 이상
  • npm install -g @anthropic-ai/claude-code가 권한 에러 없이 끝남
  • claude --version이 바로 응답
  • claude 명령 후 브라우저에서 로그인이 성공

Bad (자주 발생)

  • node --version이 v16 또는 에러 — 오래된 Node (업그레이드 필요)
  • npm install -g 실행 시 EACCES: permission denied — 전역 경로 권한 문제
  • claude: command not found — PATH 등록 실패
  • 브라우저가 안 뜨고 명령이 멈춤 — 방화벽·프록시·Windows Defender 차단
  • "Rate limit exceeded" 뜸 — API 키 할당 초과 (Plus 구독 전환 권장)

흔한 실수 + 처방

#실수증상처방
1Node 16 이하SyntaxError: Unexpected tokennvm install 20 && nvm use 20
2전역 설치 권한EACCES /usr/local/libnpm 전역 경로 바꾸기: npm config set prefix ~/.npm-global + PATH 추가
3PATH 미등록claude: command not found~/.zshrc 또는 ~/.bashrc에 export PATH=~/.npm-global/bin:$PATH 추가 후 source
4방화벽 차단브라우저가 로그인창을 못 엶회사망·VPN 의심. 개인 네트워크로 전환
5Windows 경로 공백한글 유저명·공백 있는 경로에서 설치 에러C:\dev 같은 영문 경로에서 설치
6터미널 캐시설치했는데 명령이 인식 안 됨터미널 완전 닫고 새로 열기 (PATH 재로드)
7잘못된 셸zsh 설정에 적었는데 bash에서 안 됨echo $0로 현재 셸 확인 후 해당 셸 설정파일 수정

실습 체크리스트

  • 터미널에서 node --version이 v20.x.x 이상인지 확인했다
  • claude --version이 정상 출력되는 것을 확인했다
  • ~/claude-test 폴더에서 claude 세션을 열고 hello.md 파일을 생성했다
  • 설치 중 발생한 에러를 1개 이상 메모장에 기록했다 (나중에 복습용)
  • Claude Pro 또는 Max 구독 상태를 확인했거나 API 키가 발급돼 있다
  • 터미널 테마·글꼴을 최소한 자기 눈에 편한 수준으로 바꿔봤다 (6개월 동안 쳐다볼 화면)

정리 & 다음 강의 hook

claude 한 명령이 뜨는 순간 225강의 80%는 끝났다고 본다. 앞으로 매 강의에서 등장할 "이 명령을 Claude에게 시켜라"는 지시는 전부 이 한 줄 위에 서 있다. 02강에서는 claude 세션에서 실제로 뭘 시켜서 5분 안에 "Hello World" 웹페이지를 만들고 브라우저에서 여는지 해본다. 코딩이 아니라 지시의 기술을 먼저 익힌다.

복붙 명령: npm install -g @anthropic-ai/claude-code && claude · 예상 설치 시간: 맥 10분 / 윈도우 15분 / 에러 대응 20분 · 참고: Anthropic 공식 설치 가이드

강의 자료(PPT) 다운로드
다음: Claude 세션 기본 조작