클로드 코드 설치 가이드 (Mac·Windows·Linux)

🎯 학습 목표

이 강을 마치면 macOS·Windows·Linux 각 운영체제에서 클로드 코드(Claude Code)를 설치하고, 첫 로그인부터 첫 명령 실행까지 10분 안에 끝낼 수 있습니다. 또한 npm 설치 방식과 네이티브 설치 방식의 차이를 이해하고 자신의 환경에 맞는 방법을 선택할 수 있게 됩니다.

💡 왜 설치 방법이 여러 가지인가

이 섹션에서는 클로드 코드의 설치 방식이 왜 하나가 아닌지 살펴보겠습니다. 클로드 코드는 크게 두 가지 방식으로 설치할 수 있습니다. 하나는 npm을 통한 설치로, Node.js 개발 환경이 이미 있는 사용자에게 익숙한 방식입니다. 다른 하나는 네이티브 설치 스크립트로, Node.js 없이도 운영체제에 맞는 실행 파일을 바로 내려받아 설치할 수 있습니다.

이미 Node.js 기반 개발을 하고 있거나, 여러 버전을 pin해서 CI 환경에 맞추고 싶다면 npm 방식이 편리합니다. 반면 개발 환경 설정이 익숙하지 않거나 Node.js를 따로 관리하고 싶지 않다면, 네이티브 설치 스크립트가 훨씬 간단합니다. 이번 강의에서는 두 방식을 모두 다루니 자신의 상황에 맞는 쪽을 선택하면 됩니다. 어느 쪽을 선택하든 이후 강의에서 다룰 사용법 자체는 동일하므로, 지금은 설치 방식보다 "일단 설치를 마치고 첫 실행까지 가보는 것"에 집중하시기 바랍니다.

💬 운영체제별 설치 명령어

이 섹션에서는 각 운영체제에서 사용하는 설치 명령어를 정리하겠습니다.

운영체제	방식	명령어
macOS / Linux	네이티브 설치	curl -fsSL https://claude.ai/install.sh | bash
Windows (PowerShell)	네이티브 설치	irm https://claude.ai/install.ps1 | iex
모든 OS	npm 설치 (Node.js 18+ 필요)	npm install -g @anthropic-ai/claude-code

npm 방식을 쓴다면 설치 전 반드시 node --version으로 버전을 확인해야 합니다. Node.js 18 미만이라면 최신 LTS 버전으로 먼저 업그레이드해야 합니다. 또한 npm 전역 설치 시 sudo를 사용하지 않는 것이 중요합니다. sudo로 설치하면 이후 업데이트나 권한 문제가 꼬일 수 있으므로, npm의 전역 설치 경로를 사용자 권한으로 재설정하거나 nvm 같은 버전 관리 도구를 활용하는 것이 안전합니다.

Windows에서는 PowerShell 대신 명령 프롬프트(CMD)를 쓰는 경우 아래 명령어를 사용할 수 있습니다.

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

또한 Windows 환경에서는 클로드 코드가 내부적으로 셸 작업 처리에 Git Bash를 활용하므로, 아직 설치하지 않았다면 Git for Windows를 함께 설치해두는 것을 권장합니다. PowerShell 설치 명령은 관리자 권한 없이 일반 사용자 권한으로 실행해도 충분합니다.

💻 실전 사례 — 설치부터 첫 실행까지

이 섹션에서는 macOS/Linux 기준으로 설치부터 첫 실행까지의 전체 흐름을 살펴보겠습니다.

# 1. 네이티브 설치 스크립트 실행
curl -fsSL https://claude.ai/install.sh | bash

# 2. 설치 확인
claude --version

# 3. 원하는 프로젝트 폴더로 이동 후 실행
cd my-project
claude

claude 명령을 처음 실행하면 브라우저 창이 자동으로 열리며 Claude.ai 계정으로 로그인하라는 안내가 나옵니다. 브라우저가 자동으로 열리지 않는 경우 터미널에서 c 키를 눌러 로그인 URL을 복사한 뒤 직접 브라우저에 붙여넣으면 됩니다. 로그인이 완료되면 별도의 반복 인증 없이 해당 컴퓨터의 모든 프로젝트에서 클로드 코드를 바로 사용할 수 있습니다.

설치를 아예 하지 않고 한 번만 실행해보고 싶다면, npm 환경에서는 다음과 같이 npx로 바로 실행해볼 수도 있습니다.

npx @anthropic-ai/claude-code

이 방식은 전역 설치 없이 그때그때 최신 버전을 내려받아 실행하므로, 먼저 가볍게 체험해보고 싶을 때 유용합니다. 다만 자주 사용할 계획이라면 매번 다운로드하는 것보다 앞서 소개한 방식으로 정식 설치하는 편이 실행 속도 면에서 더 유리합니다.

⚠️ 자주 하는 실수 / 주의점

실수 1 — npm 전역 설치에 sudo를 사용하는 것. "Permission denied" 오류가 나면 sudo로 우회하고 싶은 유혹이 생기지만, 이는 이후 업데이트 시 더 큰 권한 문제를 만듭니다. npm 공식 가이드에 따라 전역 설치 경로를 사용자 홈 디렉터리 하위로 재설정하는 것이 안전합니다.

실수 2 — Node.js 버전을 확인하지 않고 설치를 시도하는 것. npm 방식은 Node.js 18 이상이 필요합니다. 오래된 버전이 설치되어 있으면 설치 자체가 실패하거나 실행 중 오류가 발생할 수 있으므로, 설치 전 node --version 확인이 필수입니다.

실수 3 — 사내망·컨테이너·SSH 환경에서 브라우저 로그인이 막히는 것. WSL2, SSH 원격 접속, 컨테이너 환경에서는 브라우저가 로컬 콜백 서버에 접근하지 못해 로그인이 자동으로 완료되지 않는 경우가 있습니다. 이럴 때는 브라우저에 표시된 로그인 코드를 복사해 터미널의 안내 문구("Paste code here if prompted")에 직접 붙여넣으면 해결됩니다.

🚀 계정 로그인 방식 vs API 키 방식

개인 사용자는 대부분 Claude.ai 계정으로 로그인하는 방식을 사용하지만, 팀이나 조직에서는 Claude Console에서 발급한 API 키(ANTHROPIC_API_KEY)를 환경 변수로 설정해 사용하는 경우도 많습니다. 환경 변수에 API 키가 설정되어 있으면, 클로드 코드는 계정 로그인 절차를 건너뛰고 해당 키를 사용할지 확인하는 절차로 넘어갑니다. 어떤 방식을 쓰든 인증 정보는 프로젝트 단위가 아니라 컴퓨터 전체에 걸쳐 공유되므로, 한 번 로그인하면 이후 다른 프로젝트 폴더에서도 다시 로그인할 필요가 없습니다.

개인 학습이나 소규모 프로젝트라면 계정 로그인 방식만으로 충분하지만, 여러 명이 함께 쓰는 사내 환경이라면 API 키나 Claude for Teams·Enterprise 같은 조직 단위 인증 방식을 고려해볼 수 있습니다. 이런 조직용 인증 방식은 사용량 관리와 권한 통제가 필요한 상황에 특히 적합합니다.

📝 핵심 요약

• 클로드 코드는 네이티브 설치 스크립트와 npm 설치 두 가지 방식으로 설치할 수 있습니다.
• npm 방식은 Node.js 18 이상이 필요하며, sudo 없이 설치하는 것이 안전합니다.
• 설치 후 claude 명령을 실행하면 브라우저를 통한 계정 로그인으로 인증이 완료됩니다.
• 인증은 컴퓨터 전체에 적용되며, API 키를 환경 변수로 설정해 팀·조직 단위로 활용할 수도 있습니다.

다음 강에서는 설치를 마친 뒤 첫 프로젝트를 클로드 코드로 시작하는 방법을 다루겠습니다.

📚 참고 자료

• Authentication — Claude Code 공식 문서