Claude Code 사용법: 설치부터 첫 실행까지 5분 가이드
claude code 설치 한 줄 요약
지금 기준 claude code 사용법은 native install부터 잡는 게 제일 빨라요. macOS·Linux·WSL은
curl -fsSL https://claude.ai/install.sh | bash, Windows는 PowerShell에서irm https://claude.ai/install.ps1 | iex를 쓰고, 설치 뒤claude를 치면 브라우저 로그인으로 이어집니다. npm 설치는 아직 되지만 deprecated라서 호환성 이유가 있을 때만 쓰는 게 맞고, Claude Code는 무료 Claude.ai 플랜만으로는 못 써요.
처음 설치할 때 제일 헷갈렸던 게 그거였어요. 예전 기억 때문에 npm install -g부터 치려다가, 지금 공식 흐름이 native install 중심으로 바뀐 걸 뒤늦게 봤거든요. 거기서 한 번, 로그인만 하면 바로 무료로 돌아갈 거라 생각했다가 또 한 번 멈췄어요. 2026년 4월 기준 claude code 사용법은 설치 명령보다 계정 종류와 셸부터 맞추는 게 먼저예요. Windows는 Git Bash나 WSL 준비가 빠지면 금방 막히고, macOS나 Linux는 PATH나 로그인 쪽부터 보는 게 빠르더라고요.
전체 흐름이 먼저 필요하면 Claude Code vs Codex: 직접 비교하고 정리한 선택 기준부터 보고 오세요. 여기선 당장 터미널 열고 붙이는 것만 다룹니다.
claude code 사용법 전에 먼저 체크할 것
OS 조건이 안 맞으면 설치 명령이 아무 소용 없어요. 공식 setup 기준으로 macOS 13+, Windows 10 1809+, Ubuntu 20.04+, Debian 10+, Alpine 3.19+, 4GB RAM 이상이 필요하고, Windows는 Git for Windows나 WSL이 필수입니다.
설마 설치 명령부터 치고 계정이나 셸 때문에 다시 되돌아갈 건 아니죠? 아래 다섯 줄 먼저 확인하고 넘어가세요.
- 내 OS가 지원 범위 안이다
- Windows면 Git for Windows 또는 WSL을 먼저 깔았다
- native install로 갈지, npm 호환 경로로 갈지 먼저 정했다
- npm 경로라면 Node.js 18+가 있다
- 로그인에 쓸 계정이 Pro, Max, Team, Enterprise, Console 중 하나다
체크 기준은 공식 setup과 quickstart를 요약한 거예요. 도구 포지션부터 보고 싶으면 Claude Code vs Codex: 직접 비교하고 정리한 선택 기준에서 큰 그림부터 잡아두세요.
claude code 설치 2026년 기준 빠른 경로
지금 공식 quickstart와 setup은 native install을 먼저 권장해요. macOS·Linux·WSL은 shell script, Windows는 PowerShell이나 CMD installer, 대안으로 Homebrew와 WinGet을 안내합니다.
셸만 맞추면 됩니다.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# 설치 뒤 실행
claude
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# 설치 뒤 실행
claude
:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
:: 설치 뒤 실행
claude
native 설치는 백그라운드 자동 업데이트가 붙고, Homebrew와 WinGet은 직접 업그레이드해야 해요. && separator 에러가 뜨면 CMD 명령을 PowerShell에서 돌린 거라 셸부터 바꿔야 합니다. IDE 쪽이 더 편한지 헷갈리면 claude code vs cursor 가격과 워크플로우 비교도 같이 보면 선택이 빨라요.
클로드 코드 사용법에서 npm 경로가 필요한 때
npm 경로가 완전히 사라진 건 아니에요. 공식 setup은 npm 설치를 deprecated로 두고, 호환성 이유가 있을 때만 Node.js 18+와 함께 쓰라고 적습니다.
이미 global npm CLI 흐름에 익숙하거나, 구형 dotfiles에 전역 설치가 묶여 있으면 이 경로가 편할 때가 있어요. 근데 새로 설치하는 사람이라면 굳이 여기서 시작할 이유는 적어요.
# Node 18 이상일 때만
node -v
# npm 전역 설치
npm install -g @anthropic-ai/claude-code
# 버전과 상태 확인
claude --version
# 출력 예: claude-code v1.x.x
claude doctor
여기서 sudo npm install -g는 빼세요. 권한 에러가 나면 npm 권한 씨름보다 native로 갈아타는 쪽이 보통 더 빨라요. 기존 npm 설치에서 native로 넘어갈 땐 claude install이나 native installer 뒤 npm uninstall -g @anthropic-ai/claude-code 흐름을 쓰면 됩니다. 전역 CLI 다루는 감은 Codex CLI 사용법: 설치부터 첫 코드 생성까지 읽을 때도 그대로 이어져요.
로그인하고 첫 세션 여는 흐름
설치보다 로그인에서 더 많이 막혀요. claude를 치면 브라우저 인증으로 이어지고, 무료 Claude.ai 플랜은 Claude Code access가 없어서 Pro, Max, Team, Enterprise나 Console 계정 중 하나가 필요합니다.
설치만 끝났다고 바로 무료로 다 붙을 거라 생각하면 여기서 막히죠?
# 첫 로그인 시작
claude
# 계정 전환이 필요할 때
/login
# 지금 어떤 인증이 붙었는지 보기
/status
# 예전 API 키가 구독 로그인을 덮어쓸 때
unset ANTHROPIC_API_KEY
claude
# WSL2에서 브라우저가 안 열릴 때
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude
WSL2에서 브라우저가 안 열리면 BROWSER를 잡거나 로그인 프롬프트에서 c를 눌러 URL을 복사해 수동으로 열 수 있어요. ANTHROPIC_API_KEY가 남아 있으면 구독 로그인 대신 그 키가 먼저 잡히니 /status로 지금 붙은 인증을 꼭 봐두세요. IDE 안에서 할지 터미널에서 할지 헷갈리면 claude code vs cursor 가격과 워크플로우 비교 글이 판단하기 편합니다.
claude code 시작하기 첫 작업은 이렇게
처음 세션은 큰 일부터 맡기지 말고, 읽기 질문 두세 개랑 작은 수정 한 건으로 감을 잡는 게 낫습니다. 공식 quickstart도 프로젝트 설명, 엔트리 포인트, 간단한 코드 변경, Git 상태 질문부터 시작하라고 잡아줘요.
처음부터 앱 전체 리팩터링 던지면 진짜 잘 될까요?
작은 테스트에선 반듯한데 실전 repo 붙이면 갑자기 답이 흐트러지는 순간이 오거든요. 그래서 첫 세션은 절대 크게 안 던져요. 프로젝트 설명 → 엔트리 포인트 → 작은 수정 한 건. 이 순서가 제일 덜 헤맸습니다. 차이가 꽤 큽니다.
1단계: 저장소에서 시작
# 작업할 프로젝트 폴더로 이동
cd /path/to/your/project
# 대화형 세션 시작
claude
2단계: 읽기 질문부터 던지기
# 프로젝트 전체 파악
what does this project do?
# 진입점 찾기
where is the main entry point?
# 폴더 구조 설명
explain the folder structure
3단계: 작은 변경 한 건만 맡기기
# 작은 코드 변경 요청
add a hello world function to the main file
# 변경 내역 확인
what files have I changed?
Claude Code는 수정 전에 제안 변경을 보여주고 승인부터 받는 흐름이라서, 첫 세션에서 diff 읽는 감을 같이 익히면 좋아요. 콘텐츠 repo에 붙여볼 생각이면 AI 블로그 브리프 자동 생성: 실전 파이프라인 구축기 같은 작은 작업부터 붙여보세요.
claude code 설치 에러와 요금 포인트
막히는 패턴은 생각보다 뻔해요. PATH, 잘못된 셸 명령, Git Bash 누락, WSL 브라우저 연결, API 키 충돌, 그리고 무료 플랜 오해가 거의 전부입니다.
아래 표에 자주 나오는 에러를 정리했어요. 돈 얘기도 여기서 같이 보는 게 좋아요. 설치는 끝났는데 계정 때문에 다시 막히는 경우가 많거든요.
| 증상 | 먼저 볼 것 | 첫 조치 |
|---|---|---|
claude 명령이 안 뜸 |
PATH에 ~/.local/bin 또는 %USERPROFILE%\\.local\\bin이 있는지 |
셸 설정 파일이나 User PATH에 경로 추가 후 claude --version |
&& separator 에러 |
PowerShell에서 CMD 명령을 친 건지 | PowerShell 명령 irm ... | iex로 다시 실행 |
irm not recognized |
CMD에서 PowerShell 명령을 친 건지 | CMD installer로 바꾸거나 PowerShell 열기 |
| Windows에서 git-bash 경고 | Git for Windows 설치 여부 | Git 설치 뒤 재시작, 안 잡히면 CLAUDE_CODE_GIT_BASH_PATH 지정 |
| WSL2에서 로그인 브라우저가 안 열림 | BROWSER 환경변수 |
Windows Chrome 경로 잡거나 c로 URL 복사 |
npm EACCES |
npm 권한 문제인지 native installer로 전환 가능한지 | native install로 갈아타기, 아니면 ~/.local 권한 점검 |
증상 표는 공식 troubleshooting과 setup에서 자주 터지는 항목만 추린 겁니다.
솔직히 처음부터 큰 저장소를 통째로 맡기면 사용량이 생각보다 빨리 닳아요. 그래서 초반엔 확인용 질문과 작은 수정으로 감을 보는 편이 안전했어요.
| 플랜 | 개인 기준 요금 | Claude Code | 메모 |
|---|---|---|---|
| Free | $0 | 없음 | 채팅 체험용 |
| Pro | $20/월 또는 $17/월 연간 결제 | 있음 | 가볍게 시작할 개인용 |
| Max 5x | $100/월 | 있음 | 사용량이 빠르게 늘어나는 편 |
| Max 20x | $200/월 | 있음 | 큰 repo를 자주 붙이는 쪽 |
공식 pricing 기준으로 Pro는 Claude Code를 포함하고, Max는 5x와 20x tiers로 나뉘며 가격과 사용량 정책은 바뀔 수 있어요. 무료 플랜은 Claude Code access가 없고, 세금은 별도일 수 있습니다. 돈 쓰기 전에 작업 스타일부터 가늠하고 싶으면 Claude Code vs Codex: 직접 비교하고 정리한 선택 기준부터 보고 오세요.
자주 묻는 질문
Q1: Claude Code 무료로 쓸 수 있나요?
A: 지금 기준 무료 Claude.ai plan에는 Claude Code access가 없어요. 개인은 Pro 또는 Max, 팀은 Team이나 Enterprise, 아니면 Console 선불 크레딧 계정으로 붙어야 하거든요.
Q2: Windows에서도 되나요? WSL이 꼭 필요한가요?
A: 됩니다. Git for Windows만 깔면 PowerShell, CMD, Git Bash 다 돼요. WSL은 선택인데 — sandboxing은 WSL 2만 되거든요. 이 차이 꽤 큽니다.
Q3: 설치했는데 claude 명령이 안 먹어요. 뭐부터 보면 되죠?
A: PATH부터 보세요. native 설치는 macOS/Linux에 ~/.local/bin/claude, Windows에 %USERPROFILE%\.local\bin\claude.exe를 두거든요. 이 경로가 빠지면 바로 안 잡힘. claude --version이 찍히면 넘어가도 됩니다.
Q4: Pro나 Max, Console 로그인 중 뭐로 붙는지 어떻게 보죠?
A: 예전 ANTHROPIC_API_KEY가 셸에 남아 있으면 구독 로그인보다 그 키가 먼저 잡힐 수 있어요. unset ANTHROPIC_API_KEY 뒤 다시 claude를 띄우고, 세션 안에서 /status를 봐두면 현재 인증 방식이 보입니다.
Q5: 테스트에선 잘 되는데 실전 태스크에선 왜 갑자기 답이 흐트러지죠?
A: 처음부터 큰 문제를 통째로 던지면 문맥이 금방 퍼져요. 프로젝트 설명, 엔트리 포인트, 작은 수정 한 건처럼 잘게 끊어 던지는 쪽이 훨씬 덜 헤매더라고요.
일단 설치하고 작은 질문 두세 개 던져보세요. 익숙해지면 Claude Code vs Codex: 직접 비교하고 정리한 선택 기준에서 내 작업 스타일에 뭐가 맞는지 비교해보면 됩니다. 막히는 지점이 있으면 댓글로 남겨주세요.
