Claude Code를 처음 접하면 “그냥 npm으로 설치하면 되는 거 아닌가?”싶지만, 설치 방법에 따라 업데이트 방식이 달라지고 이게 나중에 은근히 불편해진다. 이번 글에서는 설치 전 알아두면 좋은 것들과, 실제 초기 설정까지 순서대로 정리한다
시작 전에: Node.js가 필요한 이유
Claude Code는 JavaScript 기반으로 동작하기 때문에 Node.js가 먼저 설치되어 있어야 한다. Node.js는 브라우저 밖에서도 JavaScript를 실행할 수 있게 해주는 런타임 환경이다
설치 후 터미널에서 아래 두 명령어로 정상 설치 여부를 확인한다
node -v npm -v
버전 번호가 출력되면 준비 완료다. Node.js를 설치하면 패키지 매니저인 npm도 함께 설치된다
Claude Code 설치 – 어떤 방법을 선택해야 할까
macOS 기준으로 설치 방법은 두 가지이다. 공식 네이티브 설치와 Homebrew 설치다
결론부터 말하면, 특별한 이유가 없다면 공식 문서에서 권장하는 네이티브 설치를 사용하는 게 좋다
이유는 단순하다. Homebrew로 설치하면 Claude Code가 새 버전으로 올라갈 때마다 직접 업그레이드 명령어를 실행해줘야 한다. 반면 네이티브 설치는 백그라운드에서 자동으로 업데이트되어 항상 최신 버전을 유지한다. 보안 패치나 새 기능을 놓치지 않으려면 자동 업데이트 쪽이 훨씬 편하다
curl -fsSL https://claude.ai/install.sh | bash
설치가 완료되면 아래와 같은 메시지를 확인할 수 있다
✔ Claude Code successfully installed! Version: 2.1.92 Location: ~/.local/bin/claude
설치 확인 – version
설치가 끝났다면 두 가지 명령어로 상태를 확인한다
claude -v 2.1.92 (Claude Code)
버전 번호가 출력되면 설치는 성공이다
claude doctor
claude doctor는 현재 Claude Code의 상태를 진단해주는 명령어다. 설치 방법, 현재 버전, 설치 경로, 자동 업데이트 활성화 여부, 안정 버전과 최신 버전 정보까지 한눈에 확인할 수 있다
Diagnostics └ Currently running: native (2.1.92) └ Config install method: native Updates └ Auto-updates: enabled └ Auto-update channel: latest └ Stable version: 2.1.85 └ Latest version: 2.1.92
Auto-updates: enabled가 보이면 자동 업데이트가 켜진 것이다
초기 설정 – 프로젝트 폴더부터 만들어야 한다
Claude Code를 처음 실행하기 전에 중요한 점이 하나 있다
반드시 프로젝트 폴더 안에서 실행해야 한다
Claude Code는 실행된 폴더 안에서만 파일을 읽고 쓸 수 있다. 홈 디렉터리처럼 범위가 넓은 곳에서 실행하면 의도치 않은 파일에 접근할 수 있기 때문에, 작업할 프로젝트 폴더를 먼저 만들고 그 안에서 실행하는 것이 안전하다
예시
mkdir -p ~/workspaces/my-project cd ~/workspaces/my-project claude
로그인 방법 선택
처음 claude를 실행하면 테마 선택 후 로그인 방법을 고르는 화면이 나온다
테마 선택
로그인 방법
현재 (2026년 4월) 기준으로 세 가지 옵션이 있다
- Claude 계정 구독 방식: 매달 일정 금액을 내고 Claude Code를 사용하는 방식이다. 정기적으로 사용한다면 이 방법이 가장 경제적이다
- Anthropic Console 계정 방식: 크레딧을 충전한 뒤 사용한 만큼만 차감되는 방식이다. 간헐적으로 쓰는 경우에 적합하다
- Third-party Platform 방식: Amazon Bedrock, Microsoft Foundry, Vertex AI 같은 클라우드 플랫폼을 통해 접속하는 방식이다. 기업 환경에서 주로 사용하며, 개인 사용자라면 신경 쓰지 않아도 된다
특별한 상황이 아니라면 1번을 선택하면 된다.
브라우저에서 연결
로그인 성공
신뢰 설정과 보안 공지
로그인 후 Claude Code는 두 가지를 안내한다
첫째, “Claude도 실수할 수 있으니 항상 실행 전에 검토하라”는 보안 공지다. 이건 단순한 안내가 아니다. Claude Code는 파일을 직접 생성하고 수정하고 명령어를 실행하는 도구이기 때문에, 작업 내용을 확인하고 승인하는 습관이 실제로 중요하다
둘째, 현재 디렉터리에서 파일을 읽고 쓰고 실행해도 되는지 신뢰 여부를 확인한다. 1번을 선택해 신뢰를 승인하면 설정이 완료된다
폴더에 클로드 코드 접속 성공
종료와 재실행
Claude Code 안에서 터미널로 돌아가고 싶다면 /exit를 입력하면 된다
/exit
다시 실행하려면 해당 프로젝트 폴더에서 claude를 입력하면 된다. 로그인 상태는 유지되기 때문에 매번 다시 로그인할 필요는 없다
클로드 코드를 실행하여 현재 시스템에 설치된 개발 도구들의 버전을 확인
현재 시스템에 설치된 다음 도구들의 버전을 확인해주세요: 1. Node.js 2. npm 3. Git 4. Claude Code 각 도구의 버전을 터미널 명령어로 확인하고 결과를 보여주세요.
Do you want to proceed?” 질문은 클로드 코드가 터미널 명령을 실행하기 전에 허가를 요청한다. 보안상 기본 동작이라 정상이이며 매번 묻는 게 번거로우면 “Yes, and don’t ask again” 을 선택, 이후엔 묻지 않는다
프로젝트 폴더 안에서 클로드 코드를 실행하여 현재 시스템에 설치된 개발 도구들의 버전을 확인 요청하였고 그 결과를 잘 보여줍니다.
정리
Claude Code 설치에서 기억해둘 것은 두 가지다
하나, 자동 업데이트를 위해 Homebrew가 아닌 공식 네이티브 방법으로 설치한다. 둘, 실행은 항상 프로젝트 폴더 안에서 한다
설치 자체는 명령어 하나로 끝나지만, 이 두 가지 원칙을 지키는 것이 이후 작업을 훨씬 편하게 만든다