Claude Code 사용 튜토리얼: Windows/macOS에서 한 번에 설치하고 바로 시작하기

이 Claude 사용 튜토리얼은 Claude Code에 집중합니다: 설치, 검증, API Key 바인딩부터 흔한 오류 점검까지. 단계대로 따라 하면 10분 안에 터미널에서 Claude Code를 실행해 코드 생성, 오류 수정, 간단한 개발 협업에 활용할 수 있습니다.

1. 설치 전 준비: Node.js 버전 함정 피하기

Claude Code는 Node.js 환경에 의존하므로, 먼저 Node.js 18 이상 버전을 설치한 뒤 새 터미널 창을 여는 것을 권장합니다. Windows 사용자는 설치 파일로 ‘다음’만 눌러 진행하면 되고, macOS는 공식 설치 패키지 또는 패키지 관리자로 설치할 수 있습니다. 설치 후 터미널에서 node -v를 입력해 버전 번호가 정상인지 확인하세요.

2. Claude Code 설치: npm 전역 설치와 국내 미러

터미널에서 전역 설치 명령을 실행합니다: npm install -g @anthropic-ai/claude-code. 이것이 가장 일반적인 Claude Code 설치 방식입니다. 네트워크 환경상 npm 공식 레지스트리 접근이 느리다면 미러 레지스트리를 사용할 수 있습니다: npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com. 설치가 끝나면 터미널을 다시 열고 claude --version을 입력해 Claude Code를 사용할 수 있는지 확인하세요.

3. 첫 실행과 API Key 바인딩: Claude Code를 실제로 사용 가능하게 만들기

Claude Code는 Anthropic API Key 인증이 필요하며, 처음 claude를 실행할 때 보통 Key 설정을 안내합니다. 더 확실한 방법은 시스템에 환경 변수 ANTHROPIC_API_KEY를 먼저 설정한 뒤 Claude Code를 실행하는 것으로, 매번 반복 입력하는 일을 피할 수 있습니다. 설정을 마친 뒤 프로젝트 디렉터리에서 터미널을 열고 자연어로 작업을 설명하면 됩니다. 예를 들어 Claude Code에 오류를 분석하게 하고, 수정 패치를 생성한 다음 검증 방법을 안내하게 할 수 있습니다.

4. Claude Code 자주 발생하는 문제: 멈춤, 오류, 중단은 어떻게 처리하나

Claude Code에서 요청 실패 또는 잦은 중단이 발생하면, 먼저 네트워크 안정성과 서버 측 속도 제한(레이트 리밋)에 걸렸는지 여부를 확인하세요. 더 안정적인 네트워크 환경으로 바꾸면 대개 눈에 띄게 개선됩니다. 설치 오류는 대부분 Node.js 버전이 너무 낮거나 전역 권한 문제와 관련이 있으므로, Node.js를 업그레이드하고 관리자 권한/sudo로 재설치하면 해결되는 경우가 많습니다. claude --version에 출력이 없다면 전역 npm 경로가 PATH에 추가되어 있는지 확인하고, 새 터미널에서 Claude Code를 다시 실행해 보세요.