터미널용 Claude Code 설치 완전 따라하기 — 윈도우·맥 초보자용

개발 환경 세팅 시리즈 4편입니다. 앞선 글에서 VS Code(1편)와 WSL(2편)을 깔고, Git·GitHub(3편)까지 연결했다면, 이제 터미널에서 바로 일을 시키는 코딩 도구를 붙일 차례입니다. 이번 주인공은 Claude Code, 터미널 안에서 파일을 읽고 고치고 명령까지 실행해주는 코딩 비서입니다.

결론부터 말하면, Claude Code는 윈도우에서 WSL 없이 PowerShell 한 줄로 깔리고, 맥에서는 터미널 한 줄이면 끝납니다.

다만 시작 전에 알아둘 게 하나 있습니다. Claude Code는 무료 플랜으로는 못 쓰고, 최소 Claude Pro 구독(월 $20, 연간 결제 시 월 $17)이나 Console API 크레딧이 있어야 합니다. (2026년 7월 18일 기준, claude.com/pricing)

VSCode 설치부터 첫 사용까지 — 윈도우 초보자 완전 따라하기

 

WSL2 우분투 설치 완전 따라하기 — 윈도우에서 리눅스 개발 환경 만들기

Git 설치와 GitHub 가입·연동 완전 따라하기 — 첫 push까지 한 번에

 

이 글을 끝까지 따라오면 설치 명령 실행부터 버전 확인, 브라우저 로그인, 첫 질문 던지기까지 한 번에 마칩니다. 처음 하는 분 기준으로 20분 안팎이면 됩니다.

Claude Code는 무료 플랜으로는 못 씁니다. Pro 이상 구독이나 Console 크레딧이 있으면,
윈도우는 PowerShell에 irm https://claude.ai/install.ps1 | iex,
맥은 터미널에 curl -fsSL https://claude.ai/install.sh | bash 한 줄로 설치가 끝납니다.

Claude Code가 대체 무엇인가

Claude Code는 터미널에서 실행하는 AI 코딩 도구입니다.

비유하자면 터미널 안에 코딩 비서 한 명을 채용하는 셈입니다.

코드를 한 줄씩 자동완성해주는 도구가 아닙니다.

프로젝트 폴더의 파일을 직접 읽고, 필요한 곳을 고치고, 명령까지 실행합니다.

"이 프로젝트가 무슨 일을 하는지 설명해줘" 같은 말을 그냥 한국어나 영어로 입력하면 됩니다.

개인적으로는 초보자일수록 이런 대화형 도구가 오히려 진입장벽을 낮춰준다고 봅니다. 명령어를 외우는 대신 하고 싶은 일을 말로 풀면 되니까요.

설치 전에 준비할 것

설치야 명령 한 줄이지만, 그 전에 아래 다섯 가지를 확인해두면 중간에 막힐 일이 없습니다.

☐ 지원 OS인지 확인 (맥 macOS 13.0 이상 / 윈도우 10 1809 버전 이상)

☐ 인터넷 연결

☐ Claude Pro 이상 구독 또는 Console API 크레딧 (무료 플랜은 사용 불가)

☐ (윈도우, 선택) Git for Windows — Bash 도구를 쓰려면. 없어도 설치는 됩니다

☐ 터미널 앱 — 맥은 터미널(Terminal), 윈도우는 PowerShell 또는 Windows Terminal

Claude Code 공식 문서 기준으로 설치에 관리자 권한은 필요 없습니다.

왜 npm이 아니라 네이티브 설치인가

설치 방식은 크게 두 가지입니다.

공식 문서가 권장하는 쪽은 네이티브 설치이고, npm 설치는 고급 옵션으로 밀려 있습니다.

초보자라면 고민할 것 없이 네이티브 설치를 쓰면 됩니다.

가장 큰 이유는 Node.js가 필요 없다는 점입니다.

npm 설치는 Node.js 22 버전 이상을 미리 깔아야 하지만, 네이티브 설치는 그 과정이 통째로 빠집니다.

구분	네이티브 설치 (권장)	npm 설치
Node.js	필요 없음	22 버전 이상 필요
업데이트	백그라운드 자동 업데이트	수동 관리
구성	단일 바이너리	Node 패키지
추천 대상	대부분의 사용자, 특히 초보자	Node 환경을 이미 쓰는 사람

참고로 맥에서 Homebrew를, 윈도우에서 WinGet을 쓰는 분은 그 방식으로도 설치할 수 있습니다.

다만 이 두 방식은 자동 업데이트가 안 돼서 직접 brew upgrade나 winget upgrade를 해줘야 합니다.

자동 업데이트가 되는 건 네이티브 설치뿐입니다.

Step 1. 설치 명령 실행하기

터미널에 명령 한 줄을 붙여넣어 Claude Code 본체를 내 컴퓨터로 내려받는 단계입니다.

OS와 터미널 종류에 따라 명령이 다릅니다. 본인 환경에 맞는 것 하나만 쓰면 됩니다.

먼저 윈도우 PowerShell을 쓰는 경우입니다.

irm https://claude.ai/install.ps1 | iex

윈도우에서 명령 프롬프트(CMD)를 쓴다면 이 명령을 씁니다.

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

맥이나 리눅스, WSL이라면 터미널에 이 한 줄입니다.

curl -fsSL https://claude.ai/install.sh | bash

✅ 이렇게 보이면 성공 — 설치가 끝나면 "설치 완료" 안내와 함께 다음 단계 메시지가 뜹니다.

⚠️ 이게 안 되면 — 윈도우에서 'irm' is not recognized가 뜨면 지금 창이 CMD라는 뜻입니다. PowerShell을 새로 열거나 위의 CMD용 명령을 쓰세요.

반대로 The token '&&' is not a valid statement separator가 뜨면 지금 창이 PowerShell입니다. irm 명령을 쓰면 됩니다.

구분법은 간단합니다. 프롬프트가 PS C:\로 시작하면 PowerShell, C:\로 시작하면 CMD입니다.

Step 2. 제대로 깔렸는지 확인하기

설치가 끝났으면 버전 번호로 잘 깔렸는지 확인합니다.

claude --version

✅ 이렇게 보이면 성공 — 2.x.x (Claude Code) 형태로 버전 번호와 (Claude Code)라는 표시가 함께 출력됩니다. (버전 숫자는 설치 시점마다 다릅니다)

조금 더 자세히 점검하고 싶다면 이 명령도 있습니다.

claude doctor

이 명령은 세션을 시작하지 않고 설치 상태와 설정 오류, 경고를 읽기 전용으로 훑어봅니다.

⚠️ 이게 안 되면 — command not found나 'claude' is not recognized가 뜨면 설치는 됐는데 경로(PATH) 인식이 안 되는 것입니다. 아래 "자주 막히는 부분"에서 해결법을 다룹니다.

Step 3. 첫 실행하고 로그인하기

이제 프로젝트 폴더로 옮겨가 Claude Code를 켜고 계정으로 로그인합니다.

cd /path/to/your/project
claude

여기서 /path/to/your/project 부분은 본인이 작업할 폴더 경로로 바꿔 넣으세요.

처음 claude를 실행하면 로그인 안내가 나옵니다.

안내를 따라가면 브라우저가 자동으로 열리고 인증 화면이 뜹니다.

이때 Claude 구독 계정으로 로그인할지, Console 계정으로 로그인할지 고릅니다.

인증이 끝나면 자격증명이 저장되어 다음부터는 다시 로그인하지 않아도 됩니다.

나중에 계정을 바꾸고 싶으면 세션 안에서 /login을 입력하면 됩니다.

✅ 이렇게 보이면 성공 — 로그인 후 Claude Code 프롬프트가 뜨고, 화면 위쪽에 버전과 현재 모델, 작업 폴더가 표시됩니다.

⚠️ 이게 안 되면 — 브라우저가 안 열리면 로그인 화면에서 c 키를 누르세요. 인증 주소(URL)가 복사되니 브라우저에 직접 붙여넣으면 됩니다.

참고로 ANTHROPIC_API_KEY 환경변수가 이미 설정돼 있으면, 브라우저 대신 "이 키를 쓸까요?"라고 한 번 물어봅니다.

Step 4. 신뢰 폴더와 초기 설정 확인

첫 실행에서 신뢰 폴더(trust)를 확인하는 프롬프트가 나올 수 있습니다.

지금 폴더의 파일을 읽어도 되는지 되묻는 안전장치입니다.

본인 프로젝트 폴더가 맞다면 신뢰를 선택하면 됩니다.

이 밖에 테마 같은 초기 설정을 처음에 몇 가지 물어볼 수 있습니다. 안내대로 골라주면 됩니다.

여기까지 하면 설치와 로그인은 끝난 셈입니다.

첫 질문은 이렇게 던진다

설치가 끝났으면 Claude Code 프롬프트에 자연어로 그냥 물어보면 됩니다.

처음이라면 이 정도 질문으로 감을 잡아보길 추천합니다.

what does this project do?

이렇게 물으면 현재 폴더의 코드를 훑어보고 이 프로젝트가 무슨 일을 하는지 설명해줍니다.

파일을 고치는 작업을 시키면 Claude가 먼저 변경안을 보여주고, 승인을 받은 뒤에 실제로 편집합니다.

기본 모드에서는 이렇게 매번 승인을 묻습니다.

Shift+Tab을 누르면 권한 모드가 바뀝니다. 자동 승인(acceptEdits)이나 편집 없이 계획만 세우는 모드(plan)로 넘어갈 수 있습니다.

자주 쓰는 세션 명령도 몇 개 알아두면 편합니다.

/help는 사용 가능한 명령 목록을 보여주고, /clear는 대화 기록을 초기화합니다.

끝낼 때는 /exit를 입력하거나 Ctrl+D를 두 번 누르면 됩니다.

더 많은 명령어는 claude-code-commands 글에 따로 정리해뒀으니 익숙해진 뒤 참고하면 좋습니다.

VS Code에서 쓰려면 어떻게 하나

1편에서 VS Code를 깔았다면, Claude Code를 VS Code 안에서 바로 쓸 수 있습니다.

가장 간단한 방법은 VS Code 통합 터미널을 여는 것입니다.

윈도우·리눅스는 Ctrl+`, 맥은 Cmd+`로 통합 터미널을 열고 claude를 입력하면 끝입니다.

여기서 한 가지 주의할 점이 있습니다.

VS Code용 Claude Code 확장을 깔아도 터미널의 claude 명령이 저절로 생기지는 않습니다.

통합 터미널에서 claude를 쓰려면 Step 1의 네이티브 설치가 먼저 되어 있어야 합니다.

그래픽 패널로 쓰고 싶다면 확장을 따로 설치하는 방법도 있습니다.

VS Code 1.98.0 이상에서 확장 검색창에 "Claude Code"를 찾아 설치하고, 파일을 열면 나오는 아이콘으로 로그인하면 됩니다. 이때도 API 키는 필요 없고 유료 구독이나 Console 계정이면 됩니다.

자주 막히는 부분

초보자가 실제로 자주 만나는 문제 순서로 정리했습니다.

1. 명령을 못 찾는다 (PATH 문제)

설치는 됐는데 command not found: claude가 뜬다면 설치 위치가 경로(PATH)에 없는 것입니다.

✅ 가장 쉬운 해결책은 터미널을 완전히 껐다가 다시 켜는 것입니다. 대부분 이걸로 풀립니다.

그래도 안 되면 경로를 직접 추가합니다. 맥(zsh)은 아래처럼 합니다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

윈도우 PowerShell은 이렇게 추가한 뒤 터미널을 다시 켜면 됩니다.

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

2. 맥 명령을 윈도우에 붙여넣었을 때

'bash' is not recognized나 parameter name 'fsSL' 오류가 뜨면 맥·리눅스용 명령을 윈도우 PowerShell에 붙여넣은 것입니다.

✅ 윈도우용 irm https://claude.ai/install.ps1 | iex로 바꿔서 실행하세요.

3. npm 권한 오류가 날 때

npm으로 전역 설치하다 권한 오류가 나도 sudo npm install -g는 쓰지 마세요.

공식 문서도 권한·보안 문제를 이유로 이 방법을 경고합니다.

✅ 해결책은 애초에 네이티브 설치로 넘어가는 것입니다. curl -fsSL https://claude.ai/install.sh | bash 한 줄이면 됩니다.

4. 로그인은 되는데 403 오류가 날 때

API Error: 403 ... Request not allowed가 뜨면 구독 상태를 확인해야 합니다.

claude.ai/settings에서 Pro나 Max 구독이 활성 상태인지 보세요. 무료 플랜은 Claude Code를 쓸 수 없습니다.

Console 계정이라면 "Claude Code"나 "Developer" 역할이 있어야 합니다.

자주 묻는 질문

Claude Code는 무료로 쓸 수 있나요?

무료 Claude.ai 플랜으로는 쓸 수 없습니다.

최소 Pro 구독(월 $20, 연간 결제 시 월 $17)이나 Console API 크레딧이 필요합니다.

사용량이 많으면 Max 플랜(월 $100부터, 사용량 5배·20배 티어)도 있습니다. (2026년 7월 18일 기준, claude.com/pricing)

윈도우에서 WSL 없이 설치할 수 있나요?

됩니다.

2026년 7월 현재 윈도우 네이티브 설치가 표준이라, PowerShell에서 irm https://claude.ai/install.ps1 | iex 한 줄이면 끝납니다.

WSL은 리눅스 툴체인이나 샌드박스 실행이 필요할 때만 고르면 됩니다. 리눅스 도구가 필요해진다면 이 시리즈 2편 WSL 글을 참고하세요.

Node.js를 먼저 깔아야 하나요?

네이티브 설치를 쓰면 필요 없습니다.

Node.js는 npm 설치 방식을 택할 때만, 그것도 22 버전 이상이 필요합니다.

그래서 초보자에게는 네이티브 설치를 권합니다.

마무리 체크리스트

아래 항목을 하나씩 확인하면 설치가 제대로 끝난 것입니다.

✅ claude --version에서 버전 번호와 (Claude Code) 출력 확인

✅ claude doctor에서 경고·오류 없음 확인

✅ 프로젝트 폴더에서 claude 실행 후 로그인 완료, 프롬프트 표시됨

✅ "what does this project do?" 같은 첫 질문에 답이 옴

✅ /help로 명령 목록이 뜸

공식 문서를 더 보고 싶다면 아래 버튼으로 바로 이동할 수 있습니다.

📘 Claude Code 공식 문서 바로가기 →

다음 편 예고

여기까지 왔다면 이제 터미널 안에 코딩 비서 한 명을 앉혀둔 셈입니다.

개인적으로 이 도구가 초보자에게 좋은 이유는, 막히는 순간 옆에 물어볼 사람이 늘 있는 것과 비슷하기 때문이라고 생각합니다.

설치보다 중요한 건 결국 어떻게 지시하느냐인데, 이건 몇 번 써보며 감을 잡는 게 가장 빠릅니다.

다음 편에서는 만든 결과물을 실제 웹에 올리는 Vercel 배포를 다룹니다. 코드가 내 컴퓨터를 벗어나 인터넷 주소를 갖는 단계입니다.

요금이나 토큰 사용량이 걱정된다면 ai-token-cost-limit 글도 함께 보면 도움이 됩니다.

 

 

참고한 자료

Claude Code 공식 문서의 Advanced setup, Quickstart, VS Code 사용, 설치·로그인 문제 해결(troubleshoot) 페이지와 Anthropic 공식 요금 페이지(claude.com/pricing)를 참고했습니다. 모델·요금·기능은 발행 시점에 따라 달라질 수 있으니 공식 문서로 재확인하는 것을 권합니다.