설치 가이드

공식 문서: https://code.claude.com/docs/ko/desktop

설치 흐름도

설치 흐름도 — OS 선택부터 사용 시작까지

💻

1단계: OS 선택

🍎 macOS

🪟 Windows

🐧 Linux

→

📦

2단계: 설치

curl | bash

brew install

winget install

→

🔐

3단계: 인증

계정 로그인

ANTHROPIC_API_KEY

→

✅

4단계: 확인

claude --version

claude doctor

→

🚀

사용 시작!

claude

어떤 설치 방법을 선택해야 할까?

처음 설치할 때 어떤 방법을 선택해야 할지 막막하다면 아래를 참고하세요.

상황	선택	비고
Claude Desktop 앱만 일반적으로 사용하려면	다운로드 설치	코딩 지식 불필요, GUI 방식
터미널에서 코딩 작업에 Claude를 활용하려면	Claude Code 설치	개발자용, 터미널 필요
VS Code나 JetBrains IDE 안에서 사용하려면	IDE 확장 설치	VS Code Extension / JetBrains 플러그인 (아래 참고)

처음 사용자라면 **다운로드 설치(Claude Desktop 앱)**로 시작하는 것을 권장합니다. 코딩 경험이 없어도 바로 사용할 수 있습니다.

Claude Desktop 설치

시스템 요구사항

운영체제	최소 버전	비고
macOS	13.0 (Ventura) 이상	Apple Silicon 및 Intel 지원
Windows	10 (1809) 이상	64비트 필수
Linux	Ubuntu 20.04+ / Debian 10+	`.deb` 패키지 제공

메모리: 4GB 이상 RAM 권장
디스크: 최소 500MB 여유 공간

다운로드

claude.ai/download에서 운영체제에 맞는 설치 파일을 다운로드합니다
다운로드한 파일을 실행하여 설치합니다
- macOS: .dmg 파일을 열고 앱을 Applications 폴더로 드래그
- Windows: .exe 파일을 실행하여 설치 진행
- Linux: .deb 패키지를 다운로드하여 sudo dpkg -i 로 설치

계정 설정

Claude Desktop을 실행합니다
Anthropic 계정으로 로그인합니다 (Google, 이메일 등)
구독 플랜을 선택합니다
- Free: 기본 사용량 제공
- Pro: 더 많은 사용량과 최신 모델 접근
- Team/Enterprise: 팀 협업 기능

Claude Code 설치

Claude Code는 터미널에서 사용하는 AI 코딩 에이전트입니다.

시스템 요구사항

운영체제	최소 버전	비고
macOS	13.0 (Ventura) 이상	-
Windows	10 (1809) 이상	네이티브(Git Bash) 또는 WSL 2
Ubuntu	20.04 이상	-
Debian	10 이상	-
Alpine	3.19 이상	추가 패키지 필요 (아래 참고)

메모리: 4GB 이상 RAM 권장
인증: Anthropic API 키 또는 Claude Pro/Max/Team 구독

Node.js 불필요

네이티브 설치가 권장 방법이며, Node.js가 필요하지 않습니다.

설치 방법 (권장: 네이티브 설치)

macOS / Linux:

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

Windows (PowerShell):

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

Windows (CMD 명령 프롬프트):

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

패키지 관리자로 설치

# Homebrew (macOS)
brew install claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

Windows 환경 상세

Windows에서는 두 가지 방법으로 사용할 수 있습니다:

방법	장점	단점
네이티브 (Git Bash)	설치 간편, 빠른 시작	샌드박싱 미지원
WSL 2	Linux 환경, 샌드박싱 지원	WSL 설치 필요

WSL 2 권장

보안을 위한 파일시스템 샌드박싱 기능은 WSL 2에서만 지원됩니다. 프로덕션 환경에서는 WSL 2를 권장합니다.

# WSL 2에서 설치
wsl
curl -fsSL https://claude.ai/install.sh | bash

Alpine Linux 특이사항

Alpine Linux에서는 추가 패키지를 설치해야 합니다:

# 필수 패키지 설치
apk add libgcc libstdc++ ripgrep

# 내장 ripgrep 대신 시스템 ripgrep 사용 설정
export USE_BUILTIN_RIPGREP=0

# Claude Code 설치
curl -fsSL https://claude.ai/install.sh | bash

터미널이 처음이라면

터미널(Terminal)은 텍스트로 컴퓨터에 명령을 내리는 프로그램입니다. 처음엔 낯설어 보이지만 생각보다 어렵지 않습니다.

macOS: ⌘ + Space(Spotlight)를 누르고 "터미널" 또는 "Terminal"을 검색하여 실행합니다.
Windows: 시작 메뉴에서 "PowerShell"을 검색하거나, Windows + R을 누르고 powershell을 입력합니다.
명령어를 입력한 뒤 Enter 키를 눌러 실행합니다.
잘못 입력해도 걱정하지 마세요 — 오류 메시지가 나올 뿐, 컴퓨터에 문제가 생기지 않습니다.

설치 확인

# 버전 확인
claude --version

# 환경 종합 진단
claude doctor

claude doctor는 다음을 확인합니다:

설치 상태 및 버전
인증 상태
네트워크 연결
필요한 의존성

인증 설정

설치 후 처음 실행하면 인증 과정을 안내합니다:

claude

두 가지 인증 방법이 있습니다:

Anthropic 계정 로그인 (Pro/Team 구독자) - 브라우저에서 자동으로 인증 페이지가 열립니다
API 키 설정 (개발자)

export ANTHROPIC_API_KEY="your-api-key"

인증 방법 선택 가이드

어떤 인증 방법을 선택해야 할지 헷갈린다면 아래를 참고하세요.

상황	추천 방법	방법
일반 사용자 (Pro/Max 구독 중)	계정 로그인 (추천)	`claude auth login` 실행 후 브라우저에서 Anthropic 계정 로그인
API 개발자 / CI/CD 파이프라인	API 키 설정	`export ANTHROPIC_API_KEY="sk-ant-..."` 환경 변수 설정

차이점: 계정 로그인 방식은 구독 요금에 포함되어 별도 과금이 없습니다. API 키 방식은 사용한 토큰 만큼 별도로 과금됩니다. Pro/Max 구독자라면 claude auth login으로 계정 로그인을 사용하는 것이 경제적입니다.

claude auth 명령어

인증 상태를 관리하는 명령어입니다:

# Anthropic 계정 로그인 (브라우저 OAuth 플로우)
claude auth login

# 로그아웃
claude auth logout

# 현재 인증 상태 확인
claude auth status

업데이트 및 버전 관리

# 현재 설치된 버전 확인
claude --version

# 최신 버전으로 업데이트
claude update

# 환경 진단 (버전, 인증, 네트워크 상태 포함)
claude doctor

자동 업데이트

Claude Code는 기본적으로 새 버전이 출시되면 자동으로 업데이트를 알립니다. 자동 업데이트를 비활성화하려면 환경 변수를 설정하세요:

export DISABLE_AUTOUPDATER=1

주요 환경 변수

Claude Code 동작을 제어하는 환경 변수 목록입니다:

변수	설명	예시
`ANTHROPIC_API_KEY`	API 인증 키 (API 키 방식 사용 시 필수)	`sk-ant-api03-...`
`ANTHROPIC_BASE_URL`	커스텀 API 엔드포인트 (프록시/온프레미스)	`https://my-proxy.example.com`
`DISABLE_AUTOUPDATER`	자동 업데이트 알림 비활성화	`1`
`HTTPS_PROXY` / `HTTP_PROXY`	프록시 서버	`http://proxy:8080`
`NO_PROXY`	프록시 예외 목록	`localhost,127.0.0.1`
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Claude 응답 최대 출력 토큰 수	`32000`
`CLAUDE_CODE_DISABLE_TELEMETRY`	원격 측정(사용 통계) 전송 비활성화	`1`
`USE_BUILTIN_RIPGREP`	내장 ripgrep 사용 여부 (Alpine: `0`으로 설정)	`0`

# ~/.zshrc 또는 ~/.bashrc에 추가하는 예시
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export HTTPS_PROXY="http://company-proxy:8080"
export DISABLE_AUTOUPDATER=1

실전 예제: macOS에서 처음부터 설치하기

# 1단계: Claude Code 네이티브 설치
curl -fsSL https://claude.ai/install.sh | bash

# 2단계: 터미널 새로 열기 (PATH 적용을 위해)
# 터미널 앱을 닫고 다시 엽니다

# 3단계: 설치 확인
claude --version
# 출력 예: claude v2.x.x

# 4단계: 환경 진단
claude doctor
# 출력: 설치 상태, 인증, 네트워크 등 확인 결과

# 5단계: 프로젝트 디렉토리로 이동 후 실행
cd ~/my-project
claude
# 브라우저에서 Anthropic 계정 로그인 페이지가 열립니다
# 로그인 후 터미널에서 바로 사용 가능

# 6단계: 첫 명령 실행
# > 이 프로젝트의 구조를 설명해줘

트러블슈팅

증상	원인	해결 방법
`command not found: claude`	PATH에 설치 경로 미포함	터미널 재시작 또는 `source ~/.zshrc`
설치 스크립트 다운로드 실패	네트워크/프록시 문제	`HTTPS_PROXY` 설정 후 재시도
macOS에서 "확인되지 않은 개발자" 경고	Gatekeeper 차단	시스템 설정 > 보안에서 허용
Windows에서 PowerShell 실행 정책 오류	실행 정책이 Restricted	`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
Alpine에서 segfault	누락된 시스템 라이브러리	`apk add libgcc libstdc++` 설치
`claude doctor` 인증 오류	API 키 만료 또는 잘못됨	키 재생성 후 `ANTHROPIC_API_KEY` 재설정
WSL에서 브라우저가 열리지 않음	GUI 미지원 환경	API 키 방식으로 인증

연계 기능

설치를 마친 후 자연스럽게 이어지는 문서들과 각 기능의 연관 관계입니다.

🔧

초기 설정

code/setup.md — 설치 후 개발 환경을 구성합니다. CLAUDE.md 생성, 프로젝트 설정 파일 작성 등 코딩 작업 준비 단계입니다.

👋

첫 사용법

first-steps.md — 설치 직후 Chat, Cowork, Code 세 가지 모드를 처음 체험하는 방법을 안내합니다.

⚙️

설정

settings.md — 인증 완료 후 글로벌/프로젝트/로컬 범위의 설정 파일을 구성하여 팀 또는 개인 환경을 최적화합니다.

장점, 단점과 한계점

장점

간단한 원커맨드 설치: curl 또는 PowerShell 한 줄로 설치가 완료되어 초보자도 쉽게 시작할 수 있습니다.
크로스 플랫폼 지원: macOS, Windows, Ubuntu, Debian, Alpine 등 주요 운영체제를 폭넓게 지원합니다.
자동 업데이트: 별도의 관리 없이 자동으로 최신 버전이 적용되어 유지보수 부담이 적습니다.
Node.js 불필요: 네이티브 설치 방식으로 Node.js 의존성 없이 독립적으로 실행됩니다.

단점과 한계점

최소 4GB RAM 필요: 메모리가 부족한 환경(가벼운 VM, 오래된 하드웨어)에서는 성능 저하가 발생할 수 있습니다.
Alpine Linux 특별 설정 필요: Alpine에서는 libgcc, libstdc++, ripgrep 등 추가 패키지를 수동으로 설치해야 합니다.
기업 환경 프록시 이슈: 회사 방화벽이나 프록시 뒤에서 설치 스크립트 다운로드 및 인증이 실패할 수 있습니다.
npm에서 마이그레이션 필요: 기존 npm 사용자는 네이티브 설치로 전환해야 하며, 기존 설치를 먼저 제거해야 합니다.

활용 팁

설치에 문제가 생기면 claude doctor로 원인을 빠르게 진단하세요. 프록시 환경에서는 export HTTPS_PROXY=http://proxy:8080을 설정한 후 설치를 시도하면 대부분 해결됩니다.

다음 단계

첫 사용법 - 설치 후 처음 해야 할 것들
설정 - 환경 설정 방법

IDE 확장 설치

Claude Code를 IDE 내에서 직접 사용할 수 있는 확장 프로그램을 제공합니다.

VS Code 확장

VS Code 마켓플레이스에서 설치
- VS Code를 실행합니다
- 좌측 사이드바에서 확장(Extensions) 아이콘을 클릭합니다
- Claude 또는 Anthropic으로 검색합니다
- 공식 Claude Extension을 설치합니다

또는 CLI로 설치

code --install-extension Anthropic.claude-vsx

인증 설정
- VS Code를 재시작합니다
- Claude 확장의 설정 아이콘을 클릭합니다
- API 키 또는 계정으로 인증합니다

JetBrains 플러그인

JetBrains IDE에서 설치
- IntelliJ IDEA, PyCharm, WebStorm 등 JetBrains IDE를 실행합니다
- Settings → Plugins → Marketplace로 이동합니다
- Claude 검색 후 설치합니다
또는 플러그인 마켓플레이스에서 검색
- JetBrains Marketplace에서 Claude를 검색합니다
인증
- IDE를 재시작합니다
- 우측 하단의 Claude 아이콘을 클릭합니다
- API 키 또는 계정으로 로그인합니다

Pro/Max 플랜 정보:

Free: 기본 IDE 기능 (코드 편집, 간단한 분석)
Pro ($20/월): IDE에서 모든 Claude Code 기능 사용 가능
Max ($100 또는 $200/월): 최대 사용량 + 고급 기능 제공

설치 흐름도​

어떤 설치 방법을 선택해야 할까?​

Claude Desktop 설치​

시스템 요구사항​

다운로드​

계정 설정​

Claude Code 설치​

시스템 요구사항​

설치 방법 (권장: 네이티브 설치)​

패키지 관리자로 설치​

Windows 환경 상세​

Alpine Linux 특이사항​

설치 확인​

인증 설정​

인증 방법 선택 가이드​

claude auth 명령어​

업데이트 및 버전 관리​

주요 환경 변수​

실전 예제: macOS에서 처음부터 설치하기​

트러블슈팅​

연계 기능​

장점, 단점과 한계점​

장점​

단점과 한계점​

다음 단계​

IDE 확장 설치​

VS Code 확장​

JetBrains 플러그인​

설치 흐름도

어떤 설치 방법을 선택해야 할까?

Claude Desktop 설치

시스템 요구사항

다운로드

계정 설정

Claude Code 설치

시스템 요구사항

설치 방법 (권장: 네이티브 설치)

패키지 관리자로 설치

Windows 환경 상세

Alpine Linux 특이사항

설치 확인

인증 설정

인증 방법 선택 가이드

claude auth 명령어

업데이트 및 버전 관리

주요 환경 변수

실전 예제: macOS에서 처음부터 설치하기

트러블슈팅

연계 기능

장점, 단점과 한계점

장점

단점과 한계점

다음 단계

IDE 확장 설치

VS Code 확장

JetBrains 플러그인