Claude Code 시리즈 튜토리얼 5: Claude Code 설치 방법?

어떻게 Claude Code를 설치하나요

Claude Code 설치는 그래픽 인터페이스의 "다음" 버튼이 없으며, 전적으로 명령줄에서 이루어집니다. npm에 익숙하다면 전체 과정이 2분을 넘지 않습니다.

시작하기 전에 다음을 준비하세요:

Node.js 18 이상
확인 방법: 터미널에서 node -v 실행. 버전이 18보다 낮으면 nvm, fnm을 사용하거나 nodejs.org에서 직접 업그레이드하세요.
Anthropic 계정
등록 주소: https://console.anthropic.com. 계정에서 API Key를 제공하며, 설치 후에 필요합니다. 등록 자체는 무료이며, 실제 비용은 사용량에 따라 청구됩니다.
네트워크에서 Anthropic API 엔드포인트에 접근 가능
기본 도메인: api.anthropic.com. 환경에서 프록시 설정이 필요하면 터미널에서 HTTP_PROXY 또는 HTTPS_PROXY를 설정하세요.

가장 일반적인 방법으로, 한 번 설치하면 어디서든 사용할 수 있습니다.

npm install -g @anthropic-ai/claude-code

완료 후 claude --version을 실행하여 버전 번호가 출력되면 설치 성공입니다. 전역 설치 후에는 claude 명령어를 어떤 디렉토리에서도 직접 호출할 수 있습니다.

권한 오류가 발생하면(macOS의 /usr/local/lib 디렉토리에서 흔함), 두 가지 해결 방법이 있습니다:

sudo로 설치 (간편하지만 보안 논란 있음)
npm이 사용자 디렉토리를 사용하도록 설정하여 sudo 회피:
bash mkdir -p ~/.npm-global npm config set prefix '~/.npm-global'
그런 다음 ~/.npm-global/bin을 PATH에 추가하고 터미널을 다시 열면 됩니다.

전역 설치를 원하지 않거나 임시로 사용해보려면 npx가 더 직접적입니다.

npx @anthropic-ai/claude-code

npx는 최신 패키지를 임시로 다운로드하고 실행 후 전역 명령어를 남기지 않습니다. 사용할 때마다 업데이트를 확인하므로 항상 최신 버전을 유지합니다. 단점은 매번 다운로드해야 하므로 약간 느리고, 자동 스크립트에 넣어 자주 호출하기에는 부적합합니다.

적합한 상황: 처음 사용해보기, 다른 사람의 컴퓨터에서 임시 사용, 또는 가끔 한 번 사용.

설치 후 바로 인증하지 마세요. 간단한 명령어로 도구가 실행되는지 확인합니다:

claude --help

도움말 정보가 출력되면 바이너리 파일이 정상입니다. 다음 단계는 계정 연결이며, 이는 이후에 설명합니다.

두 가지 방법으로 설치한 본체는 동일하며, 이후 인증 및 사용 방식은 완전히 같습니다. 편한 방법을 선택하세요.

Node 버전이 너무 낮음
18 미만이면 경고가 아니라 오류가 발생합니다. Node 업그레이드가 가장 직접적인 해결책입니다.
네트워크 타임아웃
npm 패키지 다운로드든 API 연결이든 프록시나 방화벽으로 인해 막힐 수 있습니다. 먼저 curl https://api.anthropic.com이 통하는지 확인한 후 다음 작업을 진행하세요.
Windows에서 기본 cmd 사용
이론적으로 가능하지만, Git Bash, WSL2 또는 Windows Terminal을 사용하여 이상한 경로 이스케이프 문제를 피하는 것이 좋습니다.