설치 및 설정

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

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

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

1. 시스템 요구사항

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

추가 요구사항

• 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 통합

1. 확장 프로그램 설치

   • VS Code 마켓플레이스에서 Claude Code 검색
   • 또는 .vsix 파일로 직접 설치

2. 설정 추가

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

3. 단축키 설정

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

JetBrains IDE 통합

1. 플러그인 설치

   • Settings > Plugins > Marketplace
   • Claude Code 검색 및 설치

2. 설정

   • 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로 문제를 신고해주세요.