클로드 코드 설치 — 명령 한 줄과, 그 뒤에 막히는 두 곳

클로드 코드 설치 자체는 명령 한 줄이고, 실제로 막히는 곳은 그 뒤에 있습니다. 설치를 다룬 글은 대부분 「설치 완료」에서 끝나지만, 한국에서 실행까지 가는 길에는 두 개의 관문이 더 있습니다 — 전역 설치 권한과 로그인·결제. 이 글은 세 단계를 순서대로, 각각 막혔을 때의 해결까지 함께 정리합니다.

1단계 — 설치 (명령 한 줄)

사전 조건은 Node.js 18 이상 하나뿐입니다. macOS, Windows(WSL), Linux 모두 같은 명령을 씁니다.

# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version

# 설치
npm install -g @anthropic-ai/claude-code

# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --version

claude --version이 버전을 출력하면 설치는 끝난 것입니다. 여기서 멈춘다면 아래 두 절 중 하나에 해당합니다.

2단계 — 권한과 경로 오류

설치 단계에서 가장 흔한 두 가지 오류입니다.

EACCES에 sudo를 붙이는 것은 권장하지 않습니다. 당장은 설치되지만 이후 업데이트마다 같은 문제가 반복되고, 전역 디렉터리의 소유자가 root가 되어 더 꼬입니다. 경로를 홈으로 옮기는 쪽이 깔끔합니다.

# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

Windows라면 WSL 안에서 설치하세요. 프로젝트 파일도 WSL 파일 시스템에 두어야 파일 감시와 경로 처리가 정상 동작합니다.

3단계 — 로그인과 결제 (한국에서 실제로 막히는 곳)

설치가 끝나고 claude를 실행하면 로그인을 요구합니다. 여기서 멈추는 경우가 한국에서 가장 많고, 원인은 설치와 무관합니다.

• 해외 결제가 차단된 카드 — 구독 결제에서 실패합니다. 카드사 앱이나 홈페이지에서 해외 결제를 허용하면 대부분 해결됩니다.
• 카카오페이·토스 — 결제 수단으로 지원되지 않습니다. 국내 간편결제를 기대하고 시도하면 이 단계에서 막힙니다.
• 해외 발행 카드가 없는 경우 — 구독 경로 자체를 쓸 수 없습니다. 이때는 아래의 키 인증이 유일한 실행 방법입니다.

결제 수단별로 무엇이 되고 무엇이 안 되는지는 Claude API 가격·결제에 정리해 두었습니다.

구독 결제가 막혔을 때 — 설치한 그대로 키로 실행하기

클로드 코드는 구독 로그인 외에 API 키 인증도 지원합니다. 아래 두 환경 변수가 설정돼 있으면 로그인 화면을 거치지 않고 실행되고, 변수를 지우면 원래대로 돌아갑니다. 재설치는 필요 없습니다.

# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

claude

이 경로에서는 월정액 대신 실제로 쓴 토큰만큼 청구되므로, 작업하지 않은 달에는 비용이 발생하지 않습니다. 키 발급 절차는 클로드 API 키 발급, 구독과 종량제 중 어느 쪽이 싼지는 클로드 코드 요금에 있습니다.

설치 후 첫 실행 — 확인용 3분

실행되면 프로젝트 디렉터리에서 claude를 띄우고 /init을 한 번 돌려 두세요. 저장소를 읽어 CLAUDE.md를 만들어 주며, 이후 모든 세션에서 자동으로 읽힙니다. 여기서부터의 운용 — 규칙 작성, 권한 설정, 커스텀 명령 — 은 클로드 코드 사용법에 이어집니다.

실행 이후에 나는 오류(401·429·529)는 설치 단계와 원인이 전혀 다릅니다. 구분법은 클로드 코드 오류 정리에 따로 정리해 두었습니다.

자주 묻는 질문