클로드 코드 설치 자체는 명령 한 줄이고, 실제로 막히는 곳은 그 뒤에 있습니다. 설치를 다룬 글은 대부분 「설치 완료」에서 끝나지만, 한국에서 실행까지 가는 길에는 두 개의 관문이 더 있습니다 — 전역 설치 권한과 로그인·결제. 이 글은 세 단계를 순서대로, 각각 막혔을 때의 해결까지 함께 정리합니다.
1단계 — 설치 (명령 한 줄)
사전 조건은 Node.js 18 이상 하나뿐입니다. macOS, Windows(WSL), Linux 모두 같은 명령을 씁니다.
# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version
# 설치
npm install -g @anthropic-ai/claude-code
# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --versionclaude --version이 버전을 출력하면 설치는 끝난 것입니다. 여기서 멈춘다면 아래 두 절 중 하나에 해당합니다.
2단계 — 권한과 경로 오류
설치 단계에서 가장 흔한 두 가지 오류입니다.
| 증상 | 원인과 해결 |
|---|---|
EACCES 권한 오류 | npm 전역 디렉터리 쓰기 권한 없음 — 전역 경로를 홈으로 옮긴다 |
command not found: claude | npm 전역 bin이 PATH에 없음 — PATH에 추가 후 새 터미널 |
EACCES에 sudo를 붙이는 것은 권장하지 않습니다. 당장은 설치되지만 이후 업데이트마다 같은 문제가 반복되고, 전역 디렉터리의 소유자가 root가 되어 더 꼬입니다. 경로를 홈으로 옮기는 쪽이 깔끔합니다.
# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrcWindows라면 WSL 안에서 설치하세요. 프로젝트 파일도 WSL 파일 시스템에 두어야 파일 감시와 경로 처리가 정상 동작합니다.
3단계 — 로그인과 결제 (한국에서 실제로 막히는 곳)
설치가 끝나고 claude를 실행하면 로그인을 요구합니다. 여기서 멈추는 경우가 한국에서 가장 많고, 원인은 설치와 무관합니다.
- 해외 결제가 차단된 카드 — 구독 결제에서 실패합니다. 카드사 앱이나 홈페이지에서 해외 결제를 허용하면 대부분 해결됩니다.
- 카카오페이·토스 — claude.ai 웹 결제에서는 지원되지 않습니다(모바일 앱 구독의 스토어 결제 수단에만 있음). 국내 간편결제를 기대하고 시도하면 이 단계에서 막힙니다.
- 해외 결제가 되는 카드가 없는 경우 — 웹 구독 경로를 쓸 수 없습니다. 아래의 키 인증은 Kunavo 잔액을 충전해 쓰는데, 결제 화면이 원화로 표시되면 카카오페이·네이버페이·PAYCO·삼성페이와 국내 카드(해외 결제가 열리지 않은 카드)가 결제 수단으로 제공되므로 해외 결제 카드 없이도 충전할 수 있습니다(토스는 미지원).
결제 수단별로 무엇이 되고 무엇이 안 되는지는 클로드 결제 방법에 정리해 두었습니다.
구독 결제가 막혔을 때 — 설치한 그대로 키로 실행하기
클로드 코드는 구독 로그인 외에 API 키 인증도 지원합니다. 아래 두 환경 변수가 설정돼 있으면 로그인 화면을 거치지 않고 실행되고, 변수를 지우면 원래대로 돌아갑니다. 재설치는 필요 없습니다.
# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# 클로드 코드의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 따라가므로,
# Kunavo가 제공하는 모델로 고정해 404를 막습니다. sonnet 별칭은 Kunavo가 제공하지
# 않는 Sonnet 5.5를 요청하므로, 고정하지 않으면 /model sonnet, opusplan의 실행 단계,
# sonnet 서브에이전트가 404로 실패합니다. opus는 Opus 5.5로 고정하며,
# 클로드 코드 v2.1.280 이상이 필요합니다(이전 버전은 claude update).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5
claude이 경로에서는 월정액 대신 실제로 쓴 토큰만큼 청구되므로, 작업하지 않은 달에는 비용이 발생하지 않습니다. 키 발급 절차는 클로드 API 키 발급, 구독과 종량제 중 어느 쪽이 싼지는 클로드 코드 요금에 있습니다.
설치 후 첫 실행 — 확인용 3분
실행되면 프로젝트 디렉터리에서 claude를 띄우고 /init을 한 번 돌려 두세요. 저장소를 읽어 CLAUDE.md를 만들어 주며, 이후 모든 세션에서 자동으로 읽힙니다. 여기서부터의 운용 — 규칙 작성, 권한 설정, 커스텀 명령 — 은 클로드 코드 사용법에 이어집니다.
실행 이후에 나는 오류(401·429·529)는 설치 단계와 원인이 전혀 다릅니다. 구분법은 클로드 코드 오류 정리에 따로 정리해 두었습니다.
자주 묻는 질문
클로드 코드 설치는 어떻게 하나요?
npm 전역 설치 한 줄입니다. npm install -g @anthropic-ai/claude-code를 실행한 뒤 claude --version으로 확인하면 됩니다. 사전 조건은 Node.js 18 이상 하나뿐이며, macOS·Windows·Linux 모두 같은 명령을 씁니다. Windows에서는 WSL 안에서 설치하는 편이 문제가 적습니다.
설치는 됐는데 실행이 안 됩니다. 무엇을 확인해야 하나요?
먼저 claude --version이 출력되는지 보세요. 출력되면 설치는 끝난 것이고 남은 문제는 인증입니다. 명령을 찾지 못한다는 오류라면 npm 전역 경로가 PATH에 없는 경우이며, npm config get prefix로 나온 경로의 bin을 PATH에 추가하고 터미널을 새로 열면 해결됩니다.
설치할 때 EACCES 권한 오류가 납니다.
npm 전역 디렉터리에 쓸 권한이 없다는 뜻입니다. sudo로 설치하면 당장은 되지만 이후 권한 문제가 반복되므로 권장하지 않습니다. npm config set prefix ~/.npm-global로 전역 경로를 홈 디렉터리로 옮기고 PATH에 추가하는 방식이 안전합니다.
설치 후 로그인 단계에서 결제가 실패합니다.
한국에서 가장 자주 막히는 지점입니다. 해외 결제가 차단된 카드는 구독 결제에서 실패하며, 카드사 앱이나 홈페이지에서 해외 결제를 허용하면 대부분 해결됩니다. 카카오페이와 토스는 claude.ai 웹 결제에서는 지원되지 않고, 모바일 앱 구독에 쓰는 App Store·Google Play의 한국 결제 수단 목록에만 있습니다. 결제를 우회해야 한다면 구독 대신 API 키로 인증하는 방법이 있습니다. 이 경로의 Kunavo 잔액 충전은 결제 화면이 원화로 표시되면 카카오페이·네이버페이·PAYCO·삼성페이·국내 카드를 결제 수단으로 제공합니다(토스는 미지원).
구독 없이 클로드 코드를 쓸 수 있나요?
가능합니다. 클로드 코드는 구독 로그인 외에 API 키 인증을 지원하므로, ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN 두 환경 변수를 설정하면 로그인 없이 실행됩니다. 이 경우 월정액 대신 사용한 토큰만큼 청구되고, 쓰지 않은 달에는 비용이 발생하지 않습니다.
Windows에는 어떻게 설치하나요?
WSL(Windows Subsystem for Linux) 안에서 설치하는 방법을 권장합니다. WSL 터미널에서 Node.js 18 이상을 설치한 뒤 동일한 npm 명령을 실행하면 됩니다. 이때 작업할 프로젝트도 WSL 파일 시스템 안에 두어야 파일 감시와 경로 처리가 정상 동작합니다.