클로드 코드(Claude Code)를 써보고 싶은데 막상 설치 화면에서 막히는 경우가 많습니다. 공식 문서가 영어 위주라 명령어를 그대로 따라 치기 애매한 경우가 많기 때문입니다. macOS 기준으로 설치부터 로그인, 자주 발생하는 오류까지 직접 겪은 과정 그대로 순서대로 정리했습니다.
설치 전에 준비할 것
설치 자체는 명령어 한 줄이면 끝나지만, 아래 세 가지는 미리 확인해두는 게 좋습니다.
- 터미널을 열 수 있는 환경 (macOS 기본 터미널.app)
- Node.js 18 이상 (npm으로 설치할 경우에만 필요, 네이티브 설치는 불필요)
- Claude.ai 계정(Pro·Max 등 구독) 또는 Anthropic Console API 키 — 로그인 방식에 따라 하나만 있으면 됩니다
설치 방법 두 가지, 뭐가 다른가요?
클로드 코드는 크게 두 가지 방법으로 설치할 수 있습니다. 아래 표를 보고 본인 상황에 맞는 쪽을 고르면 됩니다.
| 방식 | 특징 | 추천 대상 |
|---|---|---|
| 네이티브 설치 | curl 스크립트로 설치, Node.js 없이도 동작, 자체 업데이트 지원 | Node.js 개발 환경이 따로 없는 사용자 |
| npm 설치 | npm install 명령어 한 줄, 이미 있는 Node.js 환경 그대로 사용 | Node.js를 이미 쓰고 있는 개발자 |
네이티브 설치로 설치하는 법 (curl)
1단계. Spotlight(Cmd + Space)에서 '터미널'을 검색해 실행합니다.
2단계. 아래 명령어를 터미널에 붙여넣고 Enter를 누릅니다.
curl -fsSL https://claude.ai/install.sh | bash3단계. 설치가 끝나면 아래 명령어로 버전이 뜨는지 확인합니다.
claude --versionnpm으로 설치하는 법
Node.js 개발 환경이 이미 있다면 npm으로 설치하는 게 더 간단합니다.
npm install -g @anthropic-ai/claude-code설치 후 claude --version으로 버전이 표시되면 정상 설치된 것입니다.
설치 후 로그인하는 법
1단계. 터미널에 claude만 입력하고 Enter를 누릅니다.
claude2단계.브라우저 창이 자동으로 열리면서 로그인 화면이 뜹니다. Claude.ai 계정(Pro·Max 구독)으로 로그인하거나, Anthropic Console에서 발급받은 API 키를 입력하는 방식 중 하나를 선택합니다.
3단계. 로그인이 끝나면 터미널로 돌아와 바로 대화를 시작할 수 있습니다.
설치가 잘 됐는지 확인하는 법
claude doctor 명령어를 실행하면 설치 상태, 버전, 인증 여부를 한 번에 점검해줍니다.
claude doctor설치 중 자주 발생하는 문제
command not found: claude
설치는 됐는데 명령어가 안 먹힌다면 PATH에 아직 반영이 안 된 경우입니다. 터미널을 완전히 껐다가 다시 열어보세요. 그래도 안 되면 쉘 설정 파일(.zshrc, .bashrc 등)을 다시 불러와야 할 수 있습니다.
Node.js 버전이 낮다는 오류
npm 설치 방식을 쓸 때만 해당합니다. node -v로 현재 버전을 확인하고, 18 미만이라면 Node.js를 최신 LTS 버전으로 업데이트한 뒤 다시 설치합니다.
macOS에서 Permission denied 오류
npm 전역 설치 권한 문제일 가능성이 높습니다. sudo를 붙여 강제로 설치하기보다는, npm 전역 설치 경로를 사용자 폴더로 바꾸는 방법을 먼저 시도하는 걸 추천합니다.
설치가 끝났다면 이어서 클로드 코드 이전 세션 불러오는 법도 확인해보세요. 작업을 이어서 하고 싶을 때 유용합니다.
설치 자체는 명령어 한두 줄이면 끝나니, 막히는 부분 없이 처음 실행까지 한 번에 끝내보세요.