이 Claude 사용 튜토리얼은 Claude Code만 다룹니다. 설치부터 첫 실행, API Key 바인딩, 계정 전환, 그리고 구독 및 흔한 오류 점검까지 단계대로 따라 하면 로컬 터미널에서 Claude Code를 실행할 수 있습니다. 문서의 명령은 Windows/macOS/Linux에 모두 적용되며, 가능한 한 함정 포인트를 앞에 적어 시행착오를 줄였습니다.
1) Claude Code 설치: 환경 준비와 첫 실행
Claude Code는 Node.js에 의존하므로, 먼저 Node.js 18 이상 버전을 설치하고 터미널에서 npm을 사용할 수 있는지 확인하는 것을 권장합니다. 이후 전역 설치를 실행합니다:
npm install -g @anthropic-ai/claude-code
설치 후
claude --version
으로 버전 번호가 출력되는지 확인하세요.
Claude Code를 처음 실행할 때는 보통 Anthropic API Key 설정을 요구하는 안내가 뜹니다. 시스템에 환경변수 ANTHROPIC_API_KEY를 미리 설정한 뒤 Claude Code를 시작하면, 반복 입력을 줄일 수 있습니다.
2) 계정 바인딩과 전환: API Key로 관리하는 것이 가장 간편
Claude Code의 “로그인” 핵심은 API Key 바인딩입니다. 하나의 Key는 하나의 과금 및 권한 출처에 대응합니다. 계정을 전환하려면 가장 확실한 방법은 ANTHROPIC_API_KEY를 교체하는 것입니다(또는 Claude Code 첫 실행 시 생성되는 설정 파일에서 Key를 바꾸는 방법도 있으며, 구체 경로는 초기화 때 안내됩니다).
회사 계정과 개인 계정 사이를 전환해야 한다면, 서로 다른 터미널 세션에 각각 환경변수를 설정하는 것을 권장합니다. 전역 설정에 Key를 고정해 두는 것을 피하면 오용 및 유출 위험을 줄일 수 있습니다.
3) 요금제 차이와 절약 전략: 사용 시나리오에 맞게 선택
Claude 관련 구독은 보통 Pro와 Max가 있으며(가격과 혜택은 공식 정책에 따라 변경될 수 있음), 웹에서의 고빈도 대화에 더 적합합니다. 반면 Claude Code의 비용은 대개 API 호출량에서 발생합니다. 개발자 관점에서는 큰 작업을 1~2일에 몰아서 끝내고, 나머지 시간에는 작은 수정만 하는 편이 “장기간 고빈도로 계속 켜두는 것”보다 보통 더 절약됩니다.
국내 사용자가 결제 또는 네트워크 제한을 겪는 경우, 우선 규정에 맞는 API 결제 채널이나 기업/팀의 일괄 정산 방식을 선택하세요. 출처가 불분명한 Key 사용은 권장하지 않으며, 리스크 관리(보안/사기 탐지)에 걸려 Claude Code가 사용 도중 중단될 수 있습니다.
4) 자주 발생하는 문제와 오류 점검: 구독 실패, 요청 오류, 계정 잠금
구독 실패는 결제 수단, 지역, 또는 청구 정보가 맞지 않을 때 자주 발생합니다. 카드의 3DS 인증, 청구지 주소, 통화 지원을 먼저 확인하세요. Claude Code만 사용할 계획이라면, 실제로 구독이 필요한지, 아니면 사용 가능한 API Key와 한도만 있으면 되는지부터 확인하세요.
요청 오류(예: 타임아웃/중단)는 보통 네트워크 불안정, 과도한 동시성, 또는 너무 긴 컨텍스트 때문에 발생합니다. 처리 순서는 다음을 권장합니다: 더 안정적인 네트워크로 변경 → 한 번에 입력하는 내용과 변경 범위를 줄이기 → Claude Code가 단계별로 수행하도록 하기(먼저 분석, 그다음 수정, 그다음 테스트).
계정이 잠기거나 Key가 무효화되면, 먼저 콘솔에서 Key가 폐기되었는지, 한도를 소진했는지, 비정상 호출이 발생했는지 확인하세요. 새 API Key로 교체한 뒤 Claude Code를 재시작하면 보통 복구됩니다. 오류가 계속되면, 로컬 프록시/인증서 인터셉트 및 시스템 시간이 올바른지도 추가로 점검하세요.
