Claude Code 설치 가이드북

Part 1. 시작하기 전에

이 가이드북은 Claude Code와 Claude 데스크탑 앱을 윈도우 컴퓨터에 처음 설치하는 분을 위한 자료입니다. 터미널이나 명령어를 다뤄본 적이 거의 없어도 따라올 수 있도록, 모든 단계를 화면 흐름과 함께 설명합니다.

두 가지 설치 옵션, 어떻게 다른가요?

Node.js, 따로 설치해야 하나요?

Mac과 Windows, 무엇이 다른가요?

Part 2. 사전 준비물 체크

설치를 시작하기 전에 아래 세 가지가 준비되었는지 확인합니다.

① 윈도우 버전 확인

Claude는 윈도우 10 또는 11 (64bit)에서 동작합니다.

1. 키보드에서 Windows 키 + R을 동시에 누릅니다 (실행 창 열림).
2. 실행 창에 winver라고 입력하고 Enter.
3. 열린 창에서 윈도우 버전을 확인합니다.

② 인터넷 연결 확인

Claude 제품은 Anthropic 서버와 계속 통신하면서 동작합니다. 안정적인 인터넷 환경에서 설치하시는 것을 권장합니다.

③ Claude 유료 계정 확인

Claude Code와 데스크탑 앱의 핵심 기능(Cowork, Code)은 Claude.ai의 유료 플랜(Pro / Max / Team / Enterprise) 가입자만 사용할 수 있습니다.

Part 3. Claude 데스크탑 앱 설치 (가장 쉬운 길)

먼저 데스크탑 앱부터 설치해 봅시다. 인스톨러를 클릭만 하면 되므로 5분 이면 끝납니다.

3-1. 다운로드 페이지로 이동

브라우저에서 공식 다운로드 페이지로 이동합니다: https://claude.com/download

3-2. 윈도우용 인스톨러 다운로드

3-3. 인스톨러 실행

1. 다운로드 폴더에서 받은 파일을 더블클릭합니다. 보통 Claude Setup.exe 같은 이름입니다.
2. Windows 보안 경고가 뜨면 실행 또는 자세히 → 실행을 누릅니다.
3. UAC(사용자 계정 컨트롤) 창에서 예를 클릭합니다.
4. 설치 진행 표시줄이 자동으로 채워집니다 (1~2분 소요).
5. 설치가 끝나면 Claude 앱이 자동으로 실행됩니다.

3-4. 로그인

1. Sign in또는 ‘로그인’ 버튼을 클릭합니다.
2. 기본 브라우저가 자동으로 열리며 Anthropic 로그인 페이지가 나옵니다.
3. 이메일·구글·SSO 중 평소 사용하던 방법으로 로그인합니다.
4. ‘Claude 앱에 권한을 부여하시겠습니까?’ 화면에서 승인합니다.
5. 브라우저가 ‘You can close this tab’ 메시지를 보여주면, 탭을 닫고 Claude 앱으로 돌아옵니다.

3-5. 첫 화면 둘러보기

Part 4. Git for Windows 설치 (필수)

4-1. Git for Windows 다운로드

1. 브라우저에서: https://git-scm.com/download/win
2. 페이지에 들어가면 자동으로 윈도우용 최신 버전 다운로드가 시작됩니다 (보통 64-bit).
3. 다운로드된 .exe 파일을 더블클릭해서 실행합니다.

4-2. 설치 옵션 (대부분 기본값 유지)

4-3. 설치 확인

1. Windows 키를 누르고 PowerShell 검색해서 실행합니다.
2. 아래 명령어를 입력하고 Enter:

   git --version

3. 아래와 비슷한 메시지가 나오면 성공:

   git version 2.47.0.windows.1

Part 5. PowerShell 처음부터 다루기

이번 Part는 터미널(검은 화면에 명령어 입력하는 창)을 처음 접하는 분을 위해 평소보다 더 상세하게 설명합니다. 이미 익숙하시다면 5-3과 5-4만 빠르게 훑고 Part 6으로 가셔도 됩니다.

5-1. PowerShell이 도대체 뭔가요?

쉽게 말해 윈도우에서 ‘글자(명령어)’로 컴퓨터에게 일을 시키는 창입니다. 평소에는 마우스로 폴더를 클릭하지만, PowerShell에서는 같은 일을 cd 폴더이름 같은 글자로 입력합니다.

5-2. PowerShell과 CMD, 한눈에 구분하기

5-3. PowerShell 열기

방법 1: 시작 메뉴 검색 (가장 쉬움)

1. 키보드의 Windows 키를 한 번 누릅니다 (시작 메뉴가 열림).
2. 바로 powershell이라고 타이핑합니다 (검색창이 자동 활성화됨).
3. 검색 결과에 ‘Windows PowerShell’이 나타납니다.
4. 결과를 마우스 우클릭 → ‘관리자 권한으로 실행’을 클릭합니다.
5. UAC 창이 뜨면 ‘예’를 누릅니다.

5-4. PowerShell 화면 익히기 (처음 보는 분 필독)

관리자: Windows PowerShell
Windows PowerShell
Copyright (C) Microsoft Corporation. 모든 권한 보유.

PS C:\Users\내이름> _

알아두면 좋은 단축키:

5-5. 실행 정책 확인 (필요시)

아주 가끔, 윈도우 보안 정책 때문에 PowerShell에서 스크립트 실행이 막혀 있는 경우가 있습니다. 이때는 다음 명령으로 한 번만 풀어주면 됩니다.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

실행 시 ‘Y’를 입력하고 Enter. 이 단계는 필수는 아니며, 설치 중 정책 관련 에러가 났을 때만 시도해 주세요.

Part 6. Claude Code 네이티브 설치

드디어 본격 설치입니다. Part 5에서 열어 둔 PowerShell(관리자 권한)을 그대로 사용하시면 됩니다.

6-1. 설치 명령어 실행

PowerShell 창에 아래 명령을 그대로 복사해 붙여넣고 Enter:

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

명령어 한 줄 풀어 설명:

• irm → Invoke-RestMethod. 인터넷에서 설치 스크립트를 받아옵니다.
• iex → Invoke-Expression. 받아온 스크립트를 실행합니다.
• | → 파이프(pipe). 앞의 결과를 뒤로 넘깁니다.

6-2. 설치 진행 중 보이는 화면

Downloading Claude Code...
Installing to C:\Users\이름\.local\bin
Installation complete!
Run 'claude' to get started.

위 메시지가 나오면 설치 자체는 성공입니다.

6-3. 설치 확인

claude --version

Part 7. PATH 문제 해결하기

7-1. 자주 만나는 에러 메시지

claude : 'claude' 용어가 cmdlet, 함수, 스크립트 파일 또는
실행할 수 있는 프로그램 이름으로 인식되지 않습니다.

7-2. 해결 방법 (한 번만 하면 끝)

Claude Code는 사용자 폴더 아래 .local\bin 위치에 설치됩니다. 이 폴더를 PATH에 추가해 주면 됩니다.

1. Windows 키 + R을 누르고 sysdm.cpl을 입력하고 Enter (시스템 속성 창 열림).
2. 상단 탭 중 ‘고급’ 탭을 클릭합니다 (영문: Advanced).
3. 우측 하단의 ‘환경 변수(N)...’ 버튼을 클릭합니다.
4. ‘사용자 변수’ 영역에서 Path라는 행을 찾아 클릭한 후, 아래 ‘편집(E)...’ 버튼을 누릅니다.
5. 열린 창에서 우측의 ‘새로 만들기(N)’ 버튼을 클릭하고, 다음 경로를 입력합니다:

   %USERPROFILE%\.local\bin

6. 입력 후 ‘확인’을 눌러 모든 창을 닫습니다.
7. 열려 있던 PowerShell 창을 모두 닫고, 새로 PowerShell을 다시 엽니다 (관리자 권한 불필요).
8. 새 창에서 다음 명령을 다시 입력:

   claude --version

Part 8. 첫 실행 + Anthropic 계정 인증

Claude Code가 설치되었어도 처음 실행할 때는 본인 계정으로 인증을 한 번 해야 합니다. 이 과정은 약 1분이면 끝납니다.

8-1. claude 명령으로 첫 실행

claude

처음 실행할 때는 다음과 같은 안내 화면이 표시됩니다:

Welcome to Claude Code!
You need to log in. Press Enter to open browser...

Enter를 누르면 기본 브라우저가 자동으로 열립니다.

8-2. 브라우저에서 로그인

1. 브라우저에 Anthropic 로그인 화면이 나타납니다.
2. Claude.ai에서 사용하는 계정(이메일·구글·SSO)으로 로그인합니다.
3. 'Claude Code에 권한을 부여하시겠습니까?' 화면이 뜨면 'Authorize'를 클릭합니다.
4. 성공 화면이 나오면 브라우저 탭을 닫아도 됩니다.

8-3. 인증 완료 확인

PowerShell 창으로 돌아오면 Claude Code의 대화형 화면이 떠 있습니다:

* Welcome to Claude Code
/help for help, /status for info

> _

프롬프트 옆에 커서가 깜빡이면 입력 대기 상태입니다. 시험 삼아 안녕을 입력하고 Enter. Claude가 한국어로 응답한다면 인증이 정상적으로 완료된 것입니다.

Part 9. 프로젝트 폴더로 이동하기 (cd 마스터)

9-1. cd 명령어 기초

cd는 ‘change directory’의 줄임말로, ‘폴더를 옮긴다’는 뜻입니다.

cd 폴더경로

예를 들어 바탕화면의 ‘my-project’ 폴더로 이동하려면:

cd $env:USERPROFILE\Desktop\my-project
# 또는
cd C:\Users\내이름\Desktop\my-project

9-2. 윈도우 경로 표기, 이렇게 다릅니다

9-3. cd로 폴더 이동할 때 자주 만나는 함정

함정 1: 한글 폴더명— 폴더 이름에 한글이 있어도 cd 자체는 동작합니다. 하지만 인코딩 문제로 가끔 깨질 수 있고, Claude Code가 파일을 처리할 때 문제가 생기기도 합니다. 가능하면 영문 이름으로 만드세요. 예: ‘농업컨설팅보고서’ → ‘agri-report’.

함정 2: 폴더 이름에 띄어쓰기 — 공백이 있을 때는 반드시 따옴표로 감싸야 합니다.

# ✗ 잘못된 예 — 에러 발생
cd C:\Users\Owen\Desktop\my project

# ✓ 올바른 예 — 따옴표로 감싸기
cd "C:\Users\Owen\Desktop\my project"

함정 3: 드라이브가 다를 때 (예: D: 드라이브)

# 1단계: 드라이브 변경
D:

# 2단계: 폴더 이동
cd D:\projects\my-project

함정 4: ‘Documents 폴더’를 찾지 못하는 경우 — OneDrive 동기화가 설정되어 있으면, 일반적인 Documents 폴더가 아닌 OneDrive 하위에 있을 수 있습니다.

# 일반적인 위치
cd $env:USERPROFILE\Documents

# OneDrive 동기화가 활성화된 경우
cd $env:USERPROFILE\OneDrive\Documents
cd $env:USERPROFILE\OneDrive\문서

9-4. 가장 안전한 방법: 파일 탐색기에서 경로 복사

1. 파일 탐색기를 열고, Claude Code로 작업할 폴더로 이동합니다.
2. 주소창을 클릭하면 전체 경로가 자동 선택됩니다.
3. Ctrl + C로 복사합니다.
4. PowerShell에서 cd를 입력하고 한 칸 띈 다음, Ctrl + V 또는 우클릭으로 붙여넣기합니다.
5. Enter를 누릅니다.

9-5. 지금 어디에 있는지 확인하기

pwd   # 현재 폴더 전체 경로
ls    # 현재 폴더 안의 파일·폴더 목록

이 두 명령만 익숙해져도 cd로 헤매는 시간이 확 줄어듭니다.

Part 10. Hello World 첫 프로젝트

이제 모든 설치와 인증이 끝났습니다. 마지막으로 간단한 첫 프로젝트를 만들어보면서 Claude Code의 흐름을 한 번 체험해 봅시다.

10-1. 연습용 폴더 만들기

# 바탕화면으로 이동
cd $env:USERPROFILE\Desktop

# 새 폴더 만들기
mkdir claude-test

# 그 폴더로 들어가기
cd claude-test

10-2. Claude Code 시작

claude

Claude Code 대화 화면이 뜨면 다음과 같이 입력해 봅니다:

'안녕하세요'를 한국어로 화면에 출력하는 간단한 Python
파일 hello.py를 만들어 줘. 만든 다음 실행 방법도 알려줘.

Claude가 hello.py 파일을 만들겠다는 계획을 보여주고, 사용자에게 승인을 요청합니다. 화면 안내에 따라 승인하면 파일이 생성됩니다.

10-3. 결과 확인

Claude Code에서 빠져나오려면 /exit을 입력합니다. 그 다음 폴더를 확인해 봅니다:

ls

hello.py 파일이 만들어져 있다면 성공입니다.

Part 11. 자주 만나는 에러 트러블슈팅

실제 설치 과정에서 가장 자주 마주치는 에러와 해결법을 모았습니다. 본인이 겪은 상황과 비슷한 항목을 찾아 따라하세요.

에러 #1. ‘claude’ 용어가 cmdlet … 인식되지 않습니다

• 증상: claude 명령을 입력했는데 인식되지 않음.
• 원인: PATH 환경 변수에 Claude Code 폴더가 추가되지 않음.
• 해결: Part 7의 PATH 해결 따라하기 → PowerShell 모두 닫고 새로 열기 → 그래도 안 되면 윈도우 재시작.

에러 #2. ‘irm은 내부 또는 외부 명령이 아닙니다’

• 증상: 설치 명령어 irm을 입력했는데 인식 안 됨.
• 원인: PowerShell이 아닌 CMD에서 명령어를 입력 중.
• 해결: 현재 창의 프롬프트 확인. C:\>로 시작하면 CMD, PS C:\>로 시작하면 PowerShell. Part 5 참고해 PowerShell을 다시 엽니다.

에러 #3. ‘&&’ 연산자는 이 버전에서 예약되어 있습니다

• 원인: PowerShell 5에서는 &&가 동작하지 않음 (PowerShell 7+에서만 지원).
• 해결: 두 명령을 별도 줄로 입력하거나 세미콜론(;)으로 연결.

# ✗ Windows PowerShell 5에서 동작 안 함
mkdir test && cd test

# ✓ 두 줄로 나누기
mkdir test
cd test

# ✓ 또는 세미콜론으로 연결
mkdir test ; cd test

에러 #4. cd로 폴더 이동 시 ‘경로를 찾을 수 없습니다’

• 폴더 이름에 띄어쓰기가 있으면 따옴표로 감싸세요. 예: cd "my project"
• 폴더 이름이 한글이면 영문 이름으로 폴더를 새로 만드는 것을 권장.
• 다른 드라이브로 이동 시에는 먼저 D: 같이 드라이브 변경부터.
• OneDrive 동기화 폴더는 OneDrive\문서 안에 있을 수 있음.
• 가장 확실한 방법: 파일 탐색기 주소창에서 경로를 복사해 붙여넣기 (Part 9-4).

에러 #5. Git Bash 관련 경고가 뜸

• 증상:claude 실행 시 ‘Git for Windows not found’ 또는 ‘falling back to PowerShell’.
• 해결: Part 4로 돌아가 Git for Windows 설치 확인 → PowerShell에서 git --version으로 상태 확인 → 그래도 안 되면 Git 재설치 시 ‘Git from command line and also from 3rd-party software’ 옵션 선택.

에러 #6. Ctrl + V로 명령어가 붙여넣어지지 않음

• PowerShell 창에서 마우스 우클릭 한 번 — 그 자리에 즉시 붙여넣어짐 (메뉴 안 뜸).
• 또는 Ctrl + Shift + V 시도.
• 그래도 안 되면, Windows 11 사용자라면 PowerShell 대신 'Windows Terminal'을 사용하세요 (Ctrl + V 정상 동작).

에러 #7. 스크린샷이 Ctrl + V로 붙여넣어지지 않음 (Claude Code 안에서)

• 해결 1: 이미지 붙여넣기는 ALT + V (Ctrl이 아님).
• 해결 2: 스크린샷을 파일로 저장한 후 Claude Code 창에 드래그 앤 드롭.

에러 #8. 로그인했는데 ‘Authentication failed’가 계속 뜸

1. Claude Code를 한 번 종료 (/exit 또는 Ctrl + C).
2. 다음 명령으로 로그아웃 후 재로그인:

   claude logout
   claude login

3. 그래도 안 되면 사용 중인 브라우저의 쿠키·캐시 삭제 후 재시도.
4. Claude.ai에서 유료 플랜이 활성화되어 있는지 다시 확인 (만료된 경우 동작 안 함).

에러 #9. 데스크탑 앱이 실행 안 됨 / 갑자기 꺼짐

• 작업 관리자(Ctrl + Shift + Esc)에서 Claude 프로세스를 모두 종료 후 재실행.
• 앱 제거 후 claude.com/download에서 최신 버전 재설치.
• ARM 윈도우인데 일반 인스톨러를 받았다면, ARM64 버전으로 재설치.
• 바이러스 백신이 차단하고 있을 수 있음 — 예외 처리.

에러 #10. 업데이트는 어떻게 하나요?

네이티브 설치한 Claude Code는 백그라운드에서 자동 업데이트됩니다. 수동으로 즉시 업데이트하려면:

claude update

현재 버전 확인:

claude --version

데스크탑 앱은 실행 시 자동으로 업데이트를 확인합니다. 별도 작업 불필요.

에러 #11. PowerShell에서 한글이 깨져 보입니다

PowerShell 인코딩을 UTF-8로 변경합니다:

# 현재 세션에만 적용
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

매번 입력하기 번거롭다면 PowerShell 프로필 파일에 위 두 줄을 추가해두면 다음부터 자동 적용됩니다.

에러 #12. Claude가 답변하다가 멈추거나 느립니다

• 인터넷 연결 상태 확인 (VPN 사용 중이면 일시 해제 후 시도).
• 사용량 한도가 초과되었을 수 있음. Claude.ai 대시보드에서 확인.
• /status 명령으로 현재 세션 상태 점검.
• Claude Code 종료 후 재실행.

부록. 자주 쓰는 명령어 치트시트

프린트해서 모니터 옆에 붙여 두면 좋습니다.

터미널 기본 명령 (PowerShell)

Claude Code 기본 명령

Claude Code 대화창 안에서