Claude Code 설치 및 초기 설정

들어가며

이전 차시에서 Claude Code가 무엇인지, 에이전틱 코딩이 어떻게 동작하는지 학습했다. 이제 직접 Claude Code를 설치하고 첫 번째 세션을 시작할 준비를 한다.

설치는 간단하다. 대부분의 경우 명령어 한 줄로 끝난다. 하지만 운영체제별로 주의할 점이 있고, 인증 방식도 여러 가지가 있다. 이번 차시에서는 시스템 요구사항을 확인하고, 운영체제별 설치 방법을 살펴보고, 로그인 설정까지 완료한다.

시스템 요구사항

Claude Code를 설치하기 전에 시스템 요구사항을 확인한다.

운영체제

하드웨어

• RAM: 4GB 이상

네트워크

• 인터넷 연결 필요

셸

• Bash, Zsh, PowerShell, CMD 지원
• Windows에서는 Git for Windows 필요

구독

Claude Code를 사용하려면 다음 중 하나가 필요하다.

무료 플랜에서는 Claude Code를 사용할 수 없다.

설치 방법

Native Install (권장)

Native Install은 가장 권장하는 설치 방법이다. 자동 업데이트를 지원하고 설치가 간단하다.

macOS / Linux

터미널을 열고 다음 명령을 실행한다.

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

Windows PowerShell

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

Windows에서는 Git for Windows가 필요하다. Git for Windows가 없다면 먼저 설치한다.

Native Install의 장점은 자동 업데이트다. 백그라운드에서 업데이트를 확인하고 설치하기 때문에 항상 최신 버전을 유지할 수 있다.

Homebrew (macOS)

macOS에서 Homebrew를 사용한다면 다음 명령으로 설치할 수 있다.

brew install --cask claude-code

Homebrew 설치는 자동 업데이트가 없다. 새 버전이 나오면 직접 업데이트해야 한다.

brew upgrade claude-code

WinGet (Windows)

Windows에서 WinGet을 사용한다면 다음 명령으로 설치할 수 있다.

winget install Anthropic.ClaudeCode

WinGet 설치도 자동 업데이트가 없다. 직접 업데이트한다.

winget upgrade Anthropic.ClaudeCode

설치 방법 비교

Windows 설정 상세

Windows에서는 두 가지 방법으로 Claude Code를 사용할 수 있다.

방법 1: Git Bash (권장)

1. Git for Windows를 설치한다
2. PowerShell 또는 CMD에서 설치 명령을 실행한다
3. claude 명령은 PowerShell, CMD, Git Bash 어디서든 실행할 수 있다

Claude Code는 내부적으로 Git Bash를 사용해서 명령을 실행한다.

방법 2: WSL

WSL(Windows Subsystem for Linux)을 사용하면 Linux 환경에서 Claude Code를 실행할 수 있다.

# WSL 설치 (PowerShell 관리자 권한)
wsl --install

WSL 설치 후:

# WSL 터미널에서
curl -fsSL https://claude.ai/install.sh | bash

WSL 버전별 차이

WSL 2를 권장한다. 샌드박싱 기능으로 보안이 강화되고, Linux 파일 시스템 성능이 더 좋다.

설치 확인

설치가 완료되면 버전을 확인한다.

claude --version

정상 설치되었다면 버전 번호가 출력된다.

Claude Code v2.x.x

더 상세한 설치 상태를 확인하려면:

claude doctor

claude doctor 명령은 설치 상태, 인증 상태, 네트워크 연결 등을 종합적으로 점검한다.

로그인 및 인증

Claude Code를 처음 실행하면 로그인이 필요하다.

claude

Claude.ai 계정으로 로그인 (권장)

Pro, Max, Team, Enterprise 구독자는 Claude.ai 계정으로 로그인한다.

1. claude 명령 실행
2. 브라우저가 자동으로 열림
3. Claude.ai 계정으로 로그인
4. 권한 승인
5. 터미널로 돌아와서 완료 확인

브라우저가 자동으로 열리지 않으면 c를 눌러 로그인 URL을 클립보드에 복사한다.

Console 계정으로 로그인

API 기반 과금을 선호한다면 Claude Console 계정을 사용할 수 있다.

1. console.anthropic.com에서 계정 생성
2. 팀 관리자가 사용자 초대 (Developer 또는 Claude Code 역할)
3. claude 명령 실행
4. Console 자격증명으로 로그인

클라우드 제공자 사용

조직에서 AWS Bedrock, Google Vertex AI, Microsoft Foundry를 사용한다면 해당 자격증명으로 인증할 수 있다.

AWS Bedrock

# 환경변수 설정
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
# AWS 자격증명 설정 필요

Google Vertex AI

# 환경변수 설정
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-central1
# GCP 자격증명 설정 필요

클라우드 제공자 인증은 브라우저 로그인이 필요 없다. 환경변수만 설정하면 된다.

로그아웃

인증 정보를 변경하거나 다시 로그인하려면:

claude
> /logout

업데이트

자동 업데이트

Native Install은 자동으로 업데이트된다. 시작할 때와 실행 중에 주기적으로 업데이트를 확인하고, 백그라운드에서 다운로드하고 설치한다. 다음 실행 때 새 버전이 적용된다.

수동 업데이트

즉시 업데이트하려면:

claude update

Homebrew / WinGet 업데이트

# Homebrew
brew upgrade claude-code

# WinGet
winget upgrade Anthropic.ClaudeCode

릴리스 채널

업데이트 채널을 선택할 수 있다.

설정 방법:

claude
> /config
# Auto-update channel 선택

또는 settings.json에서:

{
  "autoUpdatesChannel": "stable"
}

제거

Native Install 제거

macOS / Linux / WSL

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows PowerShell

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew 제거

brew uninstall --cask claude-code

WinGet 제거

winget uninstall Anthropic.ClaudeCode

설정 파일 제거

Claude Code의 모든 설정과 히스토리를 삭제하려면:

# 사용자 설정 및 상태
rm -rf ~/.claude
rm ~/.claude.json

# 프로젝트 설정 (프로젝트 디렉토리에서)
rm -rf .claude
rm -f .mcp.json

이 작업은 모든 설정, 허용된 도구 목록, MCP 서버 설정, 세션 히스토리를 삭제한다.

트러블슈팅

권한 오류 (macOS/Linux)

# 실행 권한 부여
chmod +x ~/.local/bin/claude

PATH 설정 문제

claude 명령을 찾을 수 없다면 PATH를 확인한다.

# ~/.bashrc 또는 ~/.zshrc에 추가
export PATH="$HOME/.local/bin:$PATH"

Windows에서 Git Bash 경로 문제

Claude Code가 Git Bash를 찾지 못한다면 settings.json에서 경로를 지정한다.

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

네트워크/프록시 환경

프록시 환경에서 사용한다면:

export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

인증 문제

인증이 실패하면 /logout 후 다시 로그인한다.

claude
> /logout
> /login

ANTHROPIC_API_KEY 환경변수가 설정되어 있으면 구독 인증보다 우선한다. 구독을 사용하려면:

unset ANTHROPIC_API_KEY

정리

핵심 요점

1. 시스템 요구사항: macOS 13+, Windows 10 1809+, Ubuntu 20.04+, 4GB RAM

2. 권장 설치 방법: Native Install (자동 업데이트 지원)

   • macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash
   • Windows: irm https://claude.ai/install.ps1 | iex

3. Windows 사용자: Git for Windows 필요, WSL 2 권장

4. 인증 방법: Claude.ai 계정(권장), Console 계정, 클라우드 제공자

5. 설치 확인: claude --version, claude doctor

설치 체크리스트

• 시스템 요구사항 확인
• 운영체제에 맞는 방법으로 설치
• claude --version 실행 성공
• claude doctor 상태 확인
• 로그인 인증 완료
• Pro/Max/Team/Enterprise 구독 확인

확인해볼 링크

• Claude Code 설치 문서
• Claude Code 트러블슈팅
• Claude 구독 플랜

다음 단계

다음 차시에서는 Windows 사용자를 위한 WSL 설치와 설정을 학습한다. WSL을 사용하면 Windows에서도 Linux 환경으로 Claude Code를 최적의 성능으로 사용할 수 있다.

참고 자료

• Advanced setup - Claude Code
• Authentication - Claude Code
• Troubleshooting - Claude Code