설치 및 설정

읽는 시간: 10분 | 난이도: 초급자

Claude Code를 설치하고 시스템에 맞게 설정하는 방법을 안내합니다.

이 가이드에서는 Claude Code를 설치하고 시스템에 맞게 설정하는 모든 단계를 안내합니다.

1. 시스템 요구사항

Claude Code는 대부분의 환경에서 잘 작동합니다. 다음을 확인하세요:

요구사항	최소 사양	권장 사양
운영체제	macOS 10.15+ Ubuntu 18.04+ Windows 10/11	macOS 11+ Ubuntu 20.04+ Windows 11
메모리	4GB RAM	8GB+ RAM
저장공간	100MB	500MB
네트워크	인터넷 연결	안정적인 인터넷
Python	3.8+ (필수)	3.10+

추가 요구사항

Node.js: 16.0+ (npm 설치 방식 사용 시)
Git: 버전 관리를 위한 권장 사항
터미널: zsh, bash, 또는 호환되는 쉘

2. 설치 방법

Claude Code는 여러 방법으로 설치할 수 있습니다. 시스템에 맞는 방법을 선택하세요.

NPM을 사용한 설치 (권장)

가장 간단하고 널리 사용되는 방법입니다:

# 글로벌 설치
npm install -g @anthropic-ai/claude-code

# 특정 버전 설치
npm install -g @anthropic-ai/claude-code@latest

# 최신 버전 확인
npm view @anthropic-ai/claude-code version

Homebrew를 사용한 설치 (macOS)

macOS 사용자를 위한 가장 편리한 방법입니다:

# Homebrew 업데이트
brew update

# Claude Code 설치
brew install claude-code

# 설치 확인
brew info claude-code

curl을 사용한 설치 (Linux)

Linux 시스템에서 설치 스크립트를 사용합니다:

# 설치 스크립트 다운로드 및 실행
curl -fsSL https://anthropic.com/install | bash

# 또는 wget 사용
wget -qO- https://anthropic.com/install | bash

Windows에서 설치

Windows 사용자는 다음 방법 중 하나를 사용하세요:

WSL 사용 (권장):

# WSL 내에서 npm 설치
npm install -g @anthropic-ai/claude-code

PowerShell 사용:

# PowerShell 관리자 모드에서 실행
npm install -g @anthropic-ai/claude-code

3. 설치 확인

설치가 완료되었다면 다음 명령어로 확인할 수 있습니다:

# 버전 확인
claude-code --version

# 도움말 보기
claude-code --help

# 설치 경로 확인
which claude-code  # macOS/Linux
where claude-code  # Windows

정상적으로 설치되었다면 다음과 비슷한 결과가 나타납니다:

$ claude-code --version
claude-code/1.0.0 darwin-arm64 node-v18.0.0

4. 초기 설정

Claude Code를 설치한 후에는 기본 설정을 해야 합니다.

첫 번째 세션 시작

Claude Code를 실행하세요:

claude-code

처음 실행하면 설정 마법사가 시작됩니다:

Welcome to Claude Code!
=======================

Let's configure your environment:

1. Language: ko (한국어)
2. Theme: dark
3. Log level: info

Is this correct? [Y/n]

CLAUDE.md 파일 생성

Claude Code는 CLAUDE.md 파일을 사용하여 프로젝트를 이해합니다. 첫 실행 시 자동으로 생성됩니다:

# CLAUDE.md

이 프로젝트에 대한 기본 정보를 설정하세요.

## 기본 설정
- 작업 언어: 한국어
- 코드 스타일: Prettier + ESLint
- 테스트: Jest
- 빌드: npm run build

## 커스텀 명령어
- `build`: npm run build 실행
- `test`: npm test 실행
- `deploy`: 배포 스크립트 실행

중요: CLAUDE.md 파일은 프로젝트의 설정 파일입니다. 이 파일을 수정하면 Claude Code의 작동 방식이 변경됩니다.

5. 에디터 통합

Claude Code는 다양한 에디터와 통합될 수 있습니다.

VS Code 통합

확장 프로그램 설치
- VS Code 마켓플레이스에서 Claude Code 검색
- 또는 .vsix 파일로 직접 설치
설정 추가

{
  "terminal.integrated.shell.osx": "zsh",
  "files.associations": {
    "CLAUDE.md": "markdown"
  },
  "claude-code.enabled": true,
  "claude-code.autoStart": false
}

단축키 설정

{
  "key": "cmd+shift+c",
  "command": "claude-code.open"
}

JetBrains IDE 통합

플러그인 설치
- Settings > Plugins > Marketplace
- Claude Code 검색 및 설치
설정
- Settings > Tools > Claude Code
- 경로 및 인자 설정

Vim/Neovim 통합

Vim:

" .vimrc
command! ClaudeCode !claude-code
nnoremap <leader>cc :ClaudeCode<CR>

Neovim:

-- init.lua
vim.api.nvim_create_user_command('ClaudeCode', function()
  vim.fn.termopen('claude-code')
end, {})

Emacs 통합

;; .emacs
(defun claude-code ()
  (interactive)
  (ansi-term "claude-code" "claude-code"))

(global-set-key (kbd "C-c c") 'claude-code)

6. 환경 변수 설정

기본 환경 변수

# API 키 설정
export ANTHROPIC_API_KEY="your_api_key_here"

# 로그 레벨 설정
export CLAUDE_LOG_LEVEL="info"

# 최대 메모리 설정
export NODE_OPTIONS="--max-old-space-size=4096"

# 프록시 설정 (필요한 경우)
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

쉘 프로파일에 추가

zsh 사용자:

echo 'export ANTHROPIC_API_KEY="your_api_key_here"' >> ~/.zshrc
echo 'export CLAUDE_LOG_LEVEL="info"' >> ~/.zshrc
source ~/.zshrc

bash 사용자:

echo 'export ANTHROPIC_API_KEY="your_api_key_here"' >> ~/.bashrc
echo 'export CLAUDE_LOG_LEVEL="info"' >> ~/.bashrc
source ~/.bashrc

fish 사용자:

echo 'set -x ANTHROPIC_API_KEY "your_api_key_here"' >> ~/.config/fish/config.fish
echo 'set -x CLAUDE_LOG_LEVEL "info"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

7. 문제 해결

설치 문제

문제: 권한 오류 발생

npm install -g @anthropic-ai/claude-code

해결:

# sudo 사용 (macOS/Linux)
sudo npm install -g @anthropic-ai/claude-code

# 또는 npm 권한 수정
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

문제: 버전 오류

Error: Unsupported Node.js version

해결:

# Node.js 버전 확인
node --version

# Node.js 업그레이드 (nvm 사용)
nvm install 18
nvm use 18

문제: PATH 문제

command not found: claude-code

해결:

# npm 경로 확인
npm config get prefix

# PATH에 추가
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

네트워크 문제

문제: 연결 오류

Error: Network timeout

해결:

# 프록시 설정
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 또는 npm 설정
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

캐시 문제

문제: 설치 실패 또는 오동작

해결:

# npm 캐시 정리
npm cache clean --force

# Claude Code 재설치
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

8. 업데이트

Claude Code를 최신 버전으로 유지하세요:

# NPM 사용자
npm update -g @anthropic-ai/claude-code

# Homebrew 사용자
brew upgrade claude-code

# 최신 버전 확인
npm outdated -g @anthropic-ai/claude-code

9. 제거

Claude Code를 제거하려면:

# NPM 설치 제거
npm uninstall -g @anthropic-ai/claude-code

# Homebrew 설치 제거
brew uninstall claude-code

# 설정 파일 제거
rm -rf ~/.claude
rm -f ~/CLAUDE.md

10. 다음 단계

설치가 완료되었습니다. 다음 단계로 나아가세요:

1. 인증 설정

인증 설정 가이드에서 API 키를 설정하세요.

2. 빠른 시작

빠른 시작 가이드에서 첫 번째 프로젝트를 만들어보세요.

3. 핵심 개념 학습

핵심 개념 가이드에서 Claude Code의 기능을 자세히 알아보세요.

설치 과정에서 문제가 발생했나요?

공식 포럼에서 도움을 받거나 GitHub Issues로 문제를 신고해주세요.

설치 및 설정

읽는 시간: 10분 | 난이도: 초급자

Claude Code를 설치하고 시스템에 맞게 설정하는 방법을 안내합니다.

이 가이드에서는 Claude Code를 설치하고 시스템에 맞게 설정하는 모든 단계를 안내합니다.

1. 시스템 요구사항

Claude Code는 대부분의 환경에서 잘 작동합니다. 다음을 확인하세요:

요구사항	최소 사양	권장 사양
운영체제	macOS 10.15+ Ubuntu 18.04+ Windows 10/11	macOS 11+ Ubuntu 20.04+ Windows 11
메모리	4GB RAM	8GB+ RAM
저장공간	100MB	500MB
네트워크	인터넷 연결	안정적인 인터넷
Python	3.8+ (필수)	3.10+

추가 요구사항

Node.js: 16.0+ (npm 설치 방식 사용 시)
Git: 버전 관리를 위한 권장 사항
터미널: zsh, bash, 또는 호환되는 쉘

2. 설치 방법

Claude Code는 여러 방법으로 설치할 수 있습니다. 시스템에 맞는 방법을 선택하세요.

NPM을 사용한 설치 (권장)

가장 간단하고 널리 사용되는 방법입니다:

# 글로벌 설치
npm install -g @anthropic-ai/claude-code

# 특정 버전 설치
npm install -g @anthropic-ai/claude-code@latest

# 최신 버전 확인
npm view @anthropic-ai/claude-code version

Homebrew를 사용한 설치 (macOS)

macOS 사용자를 위한 가장 편리한 방법입니다:

# Homebrew 업데이트
brew update

# Claude Code 설치
brew install claude-code

# 설치 확인
brew info claude-code

curl을 사용한 설치 (Linux)

Linux 시스템에서 설치 스크립트를 사용합니다:

# 설치 스크립트 다운로드 및 실행
curl -fsSL https://anthropic.com/install | bash

# 또는 wget 사용
wget -qO- https://anthropic.com/install | bash

Windows에서 설치

Windows 사용자는 다음 방법 중 하나를 사용하세요:

WSL 사용 (권장):

# WSL 내에서 npm 설치
npm install -g @anthropic-ai/claude-code

PowerShell 사용:

# PowerShell 관리자 모드에서 실행
npm install -g @anthropic-ai/claude-code

3. 설치 확인

설치가 완료되었다면 다음 명령어로 확인할 수 있습니다:

# 버전 확인
claude-code --version

# 도움말 보기
claude-code --help

# 설치 경로 확인
which claude-code  # macOS/Linux
where claude-code  # Windows

정상적으로 설치되었다면 다음과 비슷한 결과가 나타납니다:

$ claude-code --version
claude-code/1.0.0 darwin-arm64 node-v18.0.0

4. 초기 설정

Claude Code를 설치한 후에는 기본 설정을 해야 합니다.

첫 번째 세션 시작

Claude Code를 실행하세요:

claude-code

처음 실행하면 설정 마법사가 시작됩니다:

Welcome to Claude Code!
=======================

Let's configure your environment:

1. Language: ko (한국어)
2. Theme: dark
3. Log level: info

Is this correct? [Y/n]

CLAUDE.md 파일 생성

Claude Code는 CLAUDE.md 파일을 사용하여 프로젝트를 이해합니다. 첫 실행 시 자동으로 생성됩니다:

# CLAUDE.md

이 프로젝트에 대한 기본 정보를 설정하세요.

## 기본 설정
- 작업 언어: 한국어
- 코드 스타일: Prettier + ESLint
- 테스트: Jest
- 빌드: npm run build

## 커스텀 명령어
- `build`: npm run build 실행
- `test`: npm test 실행
- `deploy`: 배포 스크립트 실행

중요: CLAUDE.md 파일은 프로젝트의 설정 파일입니다. 이 파일을 수정하면 Claude Code의 작동 방식이 변경됩니다.

5. 에디터 통합

Claude Code는 다양한 에디터와 통합될 수 있습니다.

VS Code 통합

확장 프로그램 설치
- VS Code 마켓플레이스에서 Claude Code 검색
- 또는 .vsix 파일로 직접 설치
설정 추가

{
  "terminal.integrated.shell.osx": "zsh",
  "files.associations": {
    "CLAUDE.md": "markdown"
  },
  "claude-code.enabled": true,
  "claude-code.autoStart": false
}

단축키 설정

{
  "key": "cmd+shift+c",
  "command": "claude-code.open"
}

JetBrains IDE 통합

플러그인 설치
- Settings > Plugins > Marketplace
- Claude Code 검색 및 설치
설정
- Settings > Tools > Claude Code
- 경로 및 인자 설정

Vim/Neovim 통합

Vim:

" .vimrc
command! ClaudeCode !claude-code
nnoremap <leader>cc :ClaudeCode<CR>

Neovim:

-- init.lua
vim.api.nvim_create_user_command('ClaudeCode', function()
  vim.fn.termopen('claude-code')
end, {})

Emacs 통합

;; .emacs
(defun claude-code ()
  (interactive)
  (ansi-term "claude-code" "claude-code"))

(global-set-key (kbd "C-c c") 'claude-code)

6. 환경 변수 설정

기본 환경 변수

# API 키 설정
export ANTHROPIC_API_KEY="your_api_key_here"

# 로그 레벨 설정
export CLAUDE_LOG_LEVEL="info"

# 최대 메모리 설정
export NODE_OPTIONS="--max-old-space-size=4096"

# 프록시 설정 (필요한 경우)
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

쉘 프로파일에 추가

zsh 사용자:

echo 'export ANTHROPIC_API_KEY="your_api_key_here"' >> ~/.zshrc
echo 'export CLAUDE_LOG_LEVEL="info"' >> ~/.zshrc
source ~/.zshrc

bash 사용자:

echo 'export ANTHROPIC_API_KEY="your_api_key_here"' >> ~/.bashrc
echo 'export CLAUDE_LOG_LEVEL="info"' >> ~/.bashrc
source ~/.bashrc

fish 사용자:

echo 'set -x ANTHROPIC_API_KEY "your_api_key_here"' >> ~/.config/fish/config.fish
echo 'set -x CLAUDE_LOG_LEVEL "info"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

7. 문제 해결

설치 문제

문제: 권한 오류 발생

npm install -g @anthropic-ai/claude-code

해결:

# sudo 사용 (macOS/Linux)
sudo npm install -g @anthropic-ai/claude-code

# 또는 npm 권한 수정
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

문제: 버전 오류

Error: Unsupported Node.js version

해결:

# Node.js 버전 확인
node --version

# Node.js 업그레이드 (nvm 사용)
nvm install 18
nvm use 18

문제: PATH 문제

command not found: claude-code

해결:

# npm 경로 확인
npm config get prefix

# PATH에 추가
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

네트워크 문제

문제: 연결 오류

Error: Network timeout

해결:

# 프록시 설정
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 또는 npm 설정
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

캐시 문제

문제: 설치 실패 또는 오동작

해결:

# npm 캐시 정리
npm cache clean --force

# Claude Code 재설치
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

8. 업데이트

Claude Code를 최신 버전으로 유지하세요:

# NPM 사용자
npm update -g @anthropic-ai/claude-code

# Homebrew 사용자
brew upgrade claude-code

# 최신 버전 확인
npm outdated -g @anthropic-ai/claude-code

9. 제거

Claude Code를 제거하려면:

# NPM 설치 제거
npm uninstall -g @anthropic-ai/claude-code

# Homebrew 설치 제거
brew uninstall claude-code

# 설정 파일 제거
rm -rf ~/.claude
rm -f ~/CLAUDE.md

10. 다음 단계

설치가 완료되었습니다. 다음 단계로 나아가세요:

1. 인증 설정

인증 설정 가이드에서 API 키를 설정하세요.

2. 빠른 시작

빠른 시작 가이드에서 첫 번째 프로젝트를 만들어보세요.

3. 핵심 개념 학습

핵심 개념 가이드에서 Claude Code의 기능을 자세히 알아보세요.

설치 과정에서 문제가 발생했나요?

공식 포럼에서 도움을 받거나 GitHub Issues로 문제를 신고해주세요.

설치 및 설정

1. 시스템 요구사항

추가 요구사항

2. 설치 방법

NPM을 사용한 설치 (권장)

Homebrew를 사용한 설치 (macOS)

curl을 사용한 설치 (Linux)

Windows에서 설치

3. 설치 확인

4. 초기 설정

첫 번째 세션 시작

CLAUDE.md 파일 생성

5. 에디터 통합

VS Code 통합

JetBrains IDE 통합

Vim/Neovim 통합

Emacs 통합

6. 환경 변수 설정

기본 환경 변수

쉘 프로파일에 추가

7. 문제 해결

설치 문제

네트워크 문제

캐시 문제

8. 업데이트

9. 제거

10. 다음 단계

1. 인증 설정

2. 빠른 시작

3. 핵심 개념 학습

관련 가이드

설치 및 설정

1. 시스템 요구사항

추가 요구사항

2. 설치 방법

NPM을 사용한 설치 (권장)

Homebrew를 사용한 설치 (macOS)

curl을 사용한 설치 (Linux)

Windows에서 설치

3. 설치 확인

4. 초기 설정

첫 번째 세션 시작

CLAUDE.md 파일 생성

5. 에디터 통합

VS Code 통합

JetBrains IDE 통합

Vim/Neovim 통합

Emacs 통합

6. 환경 변수 설정

기본 환경 변수

쉘 프로파일에 추가

7. 문제 해결

설치 문제

네트워크 문제

캐시 문제

8. 업데이트

9. 제거

10. 다음 단계

1. 인증 설정

2. 빠른 시작

3. 핵심 개념 학습

관련 가이드