한국어 튜토리얼 대부분은 아직 npm install -g @anthropic-ai/claude-code로 시작한다. 그런데 2026년 4월 현재 공식이 권장하는 claude code 설치 방식은 다르다. native installer라는 단일 바이너리가 1순위로 올라왔고, npm은 “Advanced installation options”로 강등됐다. 이 글은 그 변화를 반영한 클로드 코드(Claude Code) 입문 절차다. macOS·Windows·WSL 모두 다루고, Pro 구독으로 OAuth만 통과하면 5분 안에 첫 명령까지 닿는다.
TL;DR
- 공식 권장 설치는 native installer — npm 글로벌은 advanced 옵션으로 강등됐다
- Pro/Max/Team/Enterprise/Console 계정 필수 — 무료 Claude.ai 플랜으론 사용 불가
- 첫 명령은 빈 폴더 대신 분석할 파일이 있는 디렉토리에서
claude→what does this project do?- 환경변수
ANTHROPIC_API_KEY가 떠 있으면 Pro 구독을 덮어쓴다 — 인증이 안 잡히면 가장 먼저 의심할 곳
1. Claude Code란 — 터미널에 사는 코딩 에이전트
공식 GitHub README는 “Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster…”로 정의한다. 출처: GitHub anthropics/claude-code
자연어 명령으로 파일 편집·git 워크플로·테스트 실행을 모두 터미널 안에서 처리한다.
claude.ai 웹의 Projects 기능과는 별개 제품이라 헷갈리지 말자. 웹은 브라우저 업로드 방식, Claude Code는 터미널 CLI다. Cursor 같은 IDE 도구와의 비교는 별도 글에서 다룰 예정이라 여기선 “CLI냐 에디터 내장이냐” 차이만 짚는다. 본 글은 터미널 CLI 한정이고, 데스크톱 앱·VS Code 통합·Slack 등 다른 인터페이스는 공식 페이지를 참조.
2. 설치 전 준비 — 시스템 요구사항·계정
| 항목 | 요구사항 |
|---|---|
| OS | macOS 13.0+ / Windows 10 1809+ 또는 Server 2019+ / Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+ |
| 하드웨어 | 4 GB+ RAM, x64 또는 ARM64 |
| 셸 | Bash, Zsh, PowerShell, CMD 중 아무거나 |
| Windows 추가 | Git for Windows 필요 (WSL은 불필요) |
| 위치 | Anthropic 지원 국가 — 한국은 지원 국가 |
Node.js 요구사항은 설치 방식에 따라 갈린다. native installer는 단일 바이너리라 Node.js가 필요 없고, npm 글로벌 설치만 Node 18+를 요구한다. 공식 docs 원문대로 npm 패키지가 깔아주는 바이너리도 결국 같은 native 바이너리라 Node는 실행에 쓰이지 않는다.
계정은 Pro·Max·Team·Enterprise·Console 중 하나가 필수다. 무료 Claude.ai 플랜은 Claude Code를 쓸 수 없다고 공식이 명시한다. Windows 네이티브에서 sandboxing은 미지원이니 격리가 필요하면 WSL2 쪽이 안전하다.
3. Claude Code 설치 — 공식 권장 native installer + 대안
3-1. macOS·Linux·WSL — native installer (권장)
curl -fsSL https://claude.ai/install.sh | bash
이 한 줄로 끝난다. native installation은 백그라운드에서 자동 업데이트된다. 설치 위치는 ~/.local/bin/claude.
그림 1. macOS 터미널의 native installer 실행 출력
3-2. Windows — PowerShell / CMD
PowerShell:
irm https://claude.ai/install.ps1 | iex
CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Windows는 둘 다 1-tier 정식 지원이다. 설치 위치는 %USERPROFILE%\.local\bin\claude.exe. WSL은 불필요하지만 Git for Windows는 사전 설치돼 있어야 한다.
3-3. Homebrew·WinGet (선택)
패키지 매니저를 선호하면 이 쪽도 된다.
brew install --cask claude-codewinget install Anthropic.ClaudeCode대신 자동 업데이트가 안 돼서 새 버전이 나오면 brew upgrade claude-code 또는 winget upgrade Anthropic.ClaudeCode로 직접 올려야 한다. 자주 잊어버리는 게 단점.
그림 2. 공식 setup 페이지의 native install 안내
3-4. npm 글로벌 (레거시·Advanced)
npm install -g @anthropic-ai/claude-code명령은 여전히 동작하지만, 공식 docs가 이 방식을 “Advanced installation options” 섹션으로 배치했고 GitHub README는 native를 “(Recommended)”로 명시한다. README엔 “(Deprecated)” 라벨도 있지만 공식 docs 본문에 deprecated 단어는 직접 등장하지 않는다. “공식이 native를 우선 권장하고 npm은 레거시 호환 옵션” 정도로 이해하면 된다. 그리고 공식이 굵게 경고하는 한 줄.
“Do NOT use
sudo npm install -gas this can lead to permission issues and security risks.” — 공식 setup 페이지
sudo로 권한 에러를 우회하는 게 가장 흔한 잘못이다. 권한 거부가 뜨면 native installer로 갈아타거나 nvm으로 사용자 디렉토리에 Node를 다시 까는 게 정답. apt·dnf·apk 같은 Linux 패키지 매니저 설치는 공식 페이지 “Linux package managers” 섹션 참조.
4. 설치 검증 — claude --version, claude doctor
설치 직후엔 두 명령으로 확인한다.
claude --version2.1.x 형태의 버전이 뜨면 성공이다. 발행 시점(2026-04) npm registry dist-tags.latest는 2.1.119. 더 자세한 진단은 claude doctor로 PATH·인증·네트워크 상태를 한꺼번에 확인할 수 있다. command not found: claude가 뜨면 PATH 문제이고, 해결법은 8번 섹션에 모았다.
5. 인증 — Pro 구독 OAuth + API 키 함정
claude를 처음 실행하면 자동으로 브라우저가 열린다. Pro·Max 구독 계정이나 Console 계정으로 통과하면 끝. 별도 API 키 발급은 필요 없다.
사내 망이나 원격 SSH 세션처럼 브라우저가 안 열리는 환경에선 공식 우회 절차가 있다. “If the browser doesn’t open automatically, press c to copy the login URL to your clipboard, then paste it into your browser.” 출처: authentication 페이지
로그인 후 화면에 코드만 뜨면 터미널의 Paste code here if prompted 프롬프트에 붙여넣는다.
그림 3. 첫 실행 시 OAuth 안내 화면
여기서 한국 사용자가 자주 밟는 함정이 인증 우선순위다. Claude Code는 6단계로 자격증명을 찾는데, 환경변수가 구독보다 위에 있다.
| 순위 | 자격증명 |
|---|---|
| 1 | 클라우드 제공자 자격증명 (Bedrock·Vertex·Foundry) |
| 2 | ANTHROPIC_AUTH_TOKEN 환경변수 |
| 3 | ANTHROPIC_API_KEY 환경변수 |
| 4 | apiKeyHelper 스크립트 출력 |
| 5 | CLAUDE_CODE_OAUTH_TOKEN 환경변수 |
| 6 | /login으로 받은 구독 OAuth |
회사 PC에 ANTHROPIC_API_KEY가 ~/.zshrc에 박혀 있으면 Pro 구독으로 로그인해도 환경변수가 우선이다. 결과적으로 토큰 단가 종량제 API 모드로 동작한다. 나도 처음 깔았을 때 OAuth는 통과했는데 Pro 구독이 잡히질 않아서 한참 헤맸다. 회사에서 다른 프로젝트용으로 박아둔 환경변수가 발목을 잡고 있었다. 해결은 한 줄.
unset ANTHROPIC_API_KEY그 뒤 REPL의 /status로 활성 인증 방식을 확인한다. 자격증명 자체는 macOS는 Keychain, Linux·Windows는 ~/.claude/.credentials.json에 저장된다.
6. 첫 명령 — 안전한 입문 프롬프트 한 번
작업할 폴더로 이동하는 것부터 시작한다. 빈 디렉토리에서도 동작은 하지만 응답이 빈약하다. 본인 사이드 프로젝트나 clone한 작은 레포가 좋다.
cd ~/Projects/my-side-project
claudeclaude 입력 직후 환영 화면(welcome screen)이 뜬다. 여기서부터는 자연어로 친다. 처음엔 공식 quickstart가 권장하는 안전 프롬프트로 시작하는 편이 마음 편하다.
what does this project do?또는
explain the folder structure수동으로 파일을 첨부할 필요가 없다. “Claude Code reads your project files as needed.” 출처: 공식 quickstart
처음 작은 사이드 프로젝트에서 이 한 줄을 던졌더니 5초 만에 폴더 구조를 짚어내고 핵심 진입점까지 잡아냈다. 인풋이 한 줄이었던 게 좀 놀라웠다.
그림 4. 첫 안전 프롬프트의 응답 화면
Claude Code는 수정 전에 매번 권한을 묻기 때문에 위험하진 않지만, 첫 시도엔 분석·요약 류로 감을 잡는 편이 안심된다. 종료는 exit 또는 Ctrl+D.
자주 쓰는 보조 명령은 이 정도면 시작 단계엔 충분하다.
| 명령 | 동작 |
|---|---|
claude | 인터랙티브 모드 진입 |
claude "task" | 1회성 작업 |
claude -p "query" | 1회 질의 후 종료 |
claude -c | 최근 대화 이어가기 |
/clear | 대화 히스토리 초기화 |
/help | 명령어 보기 |
exit 또는 Ctrl+D | Claude Code 종료 |
7. 비용 체감 — Pro 합산 사용량 + API 모드 차이
입문자가 가장 먼저 불안해하는 지점이 비용이다. Pro·Max 구독자가 꼭 알아둘 한 가지.
“Both Pro and Max plans offer usage limits that are shared across Claude and Claude Code…” — Pro/Max 사용 한도 헬프센터
Claude.ai 웹 대화량과 Claude Code 사용량이 합산된다는 뜻이다. 정확한 토큰 한도는 공식이 비공개라 본인 사용 패턴은 사용량 알림으로 확인하는 게 안전하다. Pro 가격이나 한도 숫자는 시점별로 변동될 수 있어 이 글엔 박지 않았다. 상세 비용은 별도 글에서 다룰 예정이며, 모델별 토큰 단가는 Claude Opus·Sonnet·Haiku 차이 정리을 먼저 보면 감이 잡힌다. Console(API 키) 모드는 첫 로그인 시 “Claude Code” 워크스페이스가 자동 생성되고, 사용량은 토큰 단가 종량제다.
8. 트러블슈팅 — 5가지 흔한 막힘
command not found: claude
PATH에 native installer 디렉토리가 없을 때 뜬다.
# Zsh (macOS 기본)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Bash라면 ~/.bashrc로 바꾼다.
npm 권한 거부 (sudo 없이 안 됨)
공식이 명시한 대로 sudo npm install -g는 쓰지 말 것. 권장 해결은 native installer로 갈아타기.
curl -fsSL https://claude.ai/install.sh | bash
인증 실패
/logout → Claude Code 종료 → claude 재실행 순서로 재인증. 안 되면 환경변수 함정 의심.
unset ANTHROPIC_API_KEY
claude
REPL 안에서 /status로 활성 인증 방식 확인.
사내 프록시·CA 인증서
공식이 정식 안내하는 환경변수다.
export HTTPS_PROXY=http://proxy.example.com:8080
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
설정 후 native installer를 다시 실행한다. SOCKS 프록시는 공식이 명시적으로 미지원으로 표시한다. NTLM·Kerberos 같은 인증 프록시는 공식이 직접 지원을 보증하지 않으니 사내 환경이면 별도 확인이 필요하다. 회사가 LLM Gateway를 운영한다면 그쪽 우회가 더 깔끔하다.
Windows 흔한 에러
irm is not recognized→ CMD에서 PowerShell 명령을 실행한 경우Claude Code on Windows requires git-bash→ Git for Windows 설치Claude Code does not support 32-bit Windows→ x86 PowerShell 닫고 일반 PowerShell 재시작
9. 다음 단계
설치·인증·첫 명령 동선이 끝났다. 본격적으로 쓰기 시작하면 다음 영역이 차례로 필요해진다.
- 프로젝트 메모리(
CLAUDE.md) — 프로젝트마다 컨텍스트·코딩 컨벤션·금지 사항을 미리 정의하는 파일 (별도 글 준비 중) - Slash 명령 — 자주 쓰는 워크플로를
/명령어로 등록 (별도 글 준비 중) - MCP 서버 연결 — 외부 도구·DB·API를 물려 도구 사용 능력 확장 (별도 글 준비 중)
- Hooks — 도구 호출 전후 자동 실행 훅. 정책 검사·로깅에 유용 (별도 글 준비 중)
10. 자주 묻는 질문 (FAQ)
Q1. Claude Code 설치하려면 무엇이 필요한가요? macOS 13+ / Windows 10 1809+ / Ubuntu 20.04+, 4 GB+ RAM, Pro·Max·Team·Enterprise·Console 계정 중 하나. native installer는 Node.js 불필요, npm 글로벌만 Node 18+ 추가로 필요하다.
Q2. Pro 구독자도 API 키가 따로 필요한가요?
아니다. claude 첫 실행 시 OAuth 로그인으로 Pro·Max 구독이 그대로 인증된다. 단 ANTHROPIC_API_KEY 환경변수가 떠 있으면 그쪽이 우선이니 /status로 활성 모드를 확인하자.
Q3. Windows에서 Claude Code를 쓸 수 있나요? PowerShell·CMD 모두 네이티브 정식 지원이다. Git for Windows를 사전 설치하면 WSL 없이 동작. sandboxing이 필요하면 WSL2 권장.
Q4. Claude Code 첫 명령은 어떻게 실행하나요?
분석할 파일이 있는 폴더로 이동 후 claude를 입력하면 REPL이 뜬다. what does this project do? 같은 자연어 프롬프트로 시작. 종료는 exit 또는 Ctrl+D.
Q5. Claude Code를 무료로 쓸 수 있나요? 무료 Claude.ai 플랜으로는 사용 불가라고 공식이 명시한다. Pro 이상 구독이나 Console API 키가 필요하다.
Q6. Node.js 버전이 안 맞으면 어떻게 하나요?
native installer를 쓰면 Node.js 자체가 필요 없다. 굳이 npm 글로벌이라면 nvm으로 18 이상을 깐다. sudo npm install -g는 공식이 금지.
Q7. Claude Code 비용은 얼마나 나가나요? Pro·Max는 정액이고 사용량이 Claude.ai 웹과 합산된다. Console API는 토큰 단가 종량제. 정확한 한도·단가는 시점별 변동이라 별도 글에서 다룰 예정.
Q8. Claude Code와 Cursor는 뭐가 다른가요? Claude Code는 CLI 에이전트, Cursor는 IDE(VS Code 포크) 기반. 동작 모델 차이가 커서 비교는 별도 글로 분리한다.
마무리
여기까지 따라왔다면 5분 안에 첫 응답을 받았을 거다. 다음 걸음은 프로젝트별 CLAUDE.md 정의로 넘어가거나, Pro 구독을 한 달 굴려보며 사용량 합산을 체감해보는 두 갈래. 어느 쪽이든 설치에서 막힌 사람보단 한 발 앞서 있다.
관련 글
- Claude Projects 사용법 완벽 정리: 파일 업로드부터 팀 공유까지 (2026) — claude.ai 웹의 Projects (CLI인 Claude Code와는 별개 도구)
- Claude Opus vs Sonnet vs Haiku 차이 완벽 정리 (2026년 4월 최신) — Claude Code가 기본으로 부르는 모델 결정 트리
- Cursor vs Claude Code (추후 발행) — IDE·코딩 도구 비교
- Claude API 비용 계산 가이드 (추후 발행) — Claude Code API 모드 종량제 시뮬레이션
