이 포스팅은 로컬 환경(Windows 11, macOS, Ubuntu 22.04 등)에서 Claude Code(클로드 코드) CLI를 설치하고 초기 설정하는 방법을 안내합니다. 설치 방식은 Native Install(권장)과 npm Install 두 가지가 있으며, 본인의 환경에 맞는 방법을 선택할 수 있습니다.
중요 요약
- 설치 방법: Native Install(권장) 또는 Node.js(npm) 방식 중 선택.
- Native 방식: 별도 런타임 없이
curl등으로 간편 설치, 자동 업데이트 지원. - npm 방식: Node.js 환경에서 npm 패키지로 관리 (Node.js 설치 필요).
- 계정 요건: Claude 구독(Pro/Max/Teams/Enterprise) 또는 Claude Console 계정(활성 결제)로 로그인합니다.
- 설치 후 초기 설정을 통해 계정을 연동하고 사용합니다.
설치 방법 선택 (Installation Methods)
Claude Code는 사용자의 환경과 선호에 따라 두 가지 설치 방식을 제공합니다.
- Native Install (권장): 별도의 Node.js 설치 없이 실행 파일 형태로 간편하게 설치합니다. 백그라운드 자동 업데이트를 지원하며 가장 빠르고 편리한 방식입니다.
- npm Install (레거시): Node.js 환경에서 npm 패키지로 설치합니다. 공식 문서에서는 더 이상 사용되지 않는 방식(deprecated) 으로 분류하며, 가능하면 Native 설치를 권장합니다.
방법 1: Native Install (권장)
이 방식은 시스템에 직접 실행 가능한 바이너리를 설치합니다. Node.js를 미리 설치할 필요가 없습니다.
macOS, Linux, WSL
터미널에서 다음 명령어를 실행하여 설치 스크립트를 다운로드하고 실행합니다.
curl -fsSL https://claude.ai/install.sh | bash
Windows (PowerShell)
PowerShell을 실행하고 다음 명령어를 입력하세요.
irm https://claude.ai/install.ps1 | iex
Windows (CMD)
CMD를 사용하는 경우 다음 명령어를 사용합니다.
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Native 설치의 장점: 설치된 Claude Code는 백그라운드에서 자동으로 최신 버전으로 업데이트되므로, 별도의 업데이트 명령을 수행할 필요가 없습니다.
방법 2: npm Install (Node.js 필요)
기존에 Node.js 개발 환경이 세팅되어 있거나, npm을 통해 전역 패키지를 관리하는 것을 선호하는 경우 이 방법을 사용합니다.
참고: Claude Code 공식 문서에서는 npm 설치를 더 이상 사용되지 않는(deprecated) 방식으로 안내합니다. 신규 설치라면 Native Install을 우선 고려하세요.
1단계: Node.js 설치 확인
왜 필요한가요?
@anthropic-ai/claude-code는 npm 패키지로도 배포됩니다. 이 방식으로 설치하려면 Node.js 런타임이 필수입니다.
공식 문서 기준으로는 Node.js 18+가 필요합니다(레거시 npm 설치에만 해당).
Windows에서 설치하기
- 공식 설치 프로그램 사용: https://nodejs.org/ 에서 LTS 버전 설치
- 또는 nvm-windows 사용: https://github.com/coreybutler/nvm-windows
macOS / Ubuntu(리눅스)에서 설치하기
nvm(Node Version Manager) 사용을 권장합니다.
# nvm 설치 예시
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
# 설치 후 터미널 재시작 혹은 설정 로드 후
nvm install --lts
설치 확인
node -v
npm -v
2단계: 클로드 코드 패키지 설치 및 확인
Node.js가 준비되었다면 터미널에서 다음 명령어로 전역 설치합니다.
npm install -g @anthropic-ai/claude-code
-g옵션: 시스템 전역에서claude명령을 사용하기 위함입니다.
설치 후 버전 확인:
claude --version
초기 설정(필수): 계정 연동 (터미널 인터랙티브)
아래 절차는 claude 명령을 처음 실행하여 인터랙티브로 계정 연동과 기본 설정을 진행하는 흐름입니다. 각 단계는 예시 이미지(setting_1 ~ setting_7)를 참고하세요.
- 터미널에서
claude명령을 처음 실행합니다.
claude
- 컬러(테마) 설정 프롬프트가 나오면 원하는 컬러/테마를 선택합니다.
- 웹 브라우저가 열리며 로그인/계정 연동 화면으로 이동합니다. 브라우저에서 로그인 후 연동을 허용하세요.
- 웹에서 승인(Authorize) 버튼을 클릭합니다. 승인 후 터미널로 돌아옵니다.
- 터미널에서 다음 단계로 진행하려면 엔터(Enter)를 누릅니다.
- 안내 문구(예: “실수를 할 수 있습니다” 또는 사용 제한에 대한 경고)가 표시되면 내용을 확인하고 계속하려면 엔터를 누릅니다.
- 워크스페이스 신뢰(trust workspace) 관련 안내가 나오면 필요에 따라
Trust또는Yes를 선택합니다.
- 종료 시
Ctrl + c두번을 통해 종료하거나,exit명령어를 입력하면 종료할 수 있습니다.
- 설정이 완료되면 간단한 테스트 명령으로 연동을 확인합니다. 예시:
claude whoami
또는 패키지에 제공되는 테스트/diagnostic 커맨드가 있다면 해당 명령을 실행해 연결 유효성을 확인하세요.
참고: 실제 메시지와 화면 흐름은 claude CLI의 버전이나 배포 설정에 따라 다를 수 있습니다. 이미지를 참고해 각 프롬프트에 맞춰 진행하면 됩니다.
검증 가능한 체크리스트
- 설치 확인: 터미널에서
claude --version명령이 정상적으로 실행되고 버전이 출력되는가? - (npm 방식인 경우)
node -v와npm -v가 정상 출력되는가? - 계정 연동:
claude명령 실행 후 브라우저 연동이 정상적으로 완료되었는가? - 기능 동작:
claude whoami또는 간단한 대화 입력 시 응답이 오는가?
참고 및 레퍼런스
Node.js: https://nodejs.org/
nvm: https://github.com/nvm-sh/nvm
nvm-windows: https://github.com/coreybutler/nvm-windows
(패키지) npm: https://www.npmjs.com/package/@anthropic-ai/claude-code
Claude Code 공식 문서(개요): https://code.claude.com/docs/ko/overview
Claude Code 공식 문서(설정/요구사항/설치): https://code.claude.com/docs/ko/setup
마무리하며
이번 포스팅에서는 Anthropic의 새로운 CLI 도구인 Claude Code의 설치 및 초기 설정 과정을 살펴보았습니다. 터미널 환경에서 AI와 직접 소통하며 개발 효율을 극대화해 보시기 바랍니다. 추가로 궁금한 점이나 막히는 부분이 있다면 공식 문서를 참고하거나 댓글로 소통해 주세요!
댓글남기기