시스템 요구사항
Claude Code를 설치하기 전에 다음 요구사항을 확인하세요.
- Node.js 18.0 이상
- npm 9.0 이상 (또는 yarn, pnpm)
- Git 2.0 이상 (Git 통합 사용 시)
- 10MB 이상의 여유 디스크 공간
- 인터넷 연결 (API 호출용)
권장 사항: 최신 LTS 버전의 Node.js를 사용하는 것을 권장합니다. 현재 LTS는 Node.js 20.x입니다.
npm으로 설치하기
npm을 사용하여 Claude Code를 전역으로 설치합니다. 설치 후 터미널 어디서든 `claude` 명령어를 사용할 수 있습니다.
bash
# npm으로 설치
npm install -g @anthropic-ai/claude-code
# yarn 사용 시
yarn global add @anthropic-ai/claude-code
# pnpm 사용 시
pnpm add -g @anthropic-ai/claude-code권한 오류 발생 시: macOS/Linux에서 권한 오류가 발생하면 `sudo npm install -g @anthropic-ai/claude-code` 명령어를 사용하세요.
API 키 설정
Claude Code를 사용하려면 Anthropic API 키가 필요합니다. API 키는 Anthropic Console에서 무료로 발급받을 수 있습니다.
- 1Anthropic Console (console.anthropic.com)에 접속합니다
- 2계정을 생성하거나 로그인합니다
- 3API Keys 섹션에서 새 API 키를 생성합니다
- 4생성된 API 키를 복사합니다
환경 변수로 API 키를 설정하세요:
bash
# bash/zsh
export ANTHROPIC_API_KEY="your-api-key-here"
# 영구적으로 설정 (bash)
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
# 영구적으로 설정 (zsh)
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc보안 주의사항: API 키는 절대 Git 저장소에 커밋하지 마세요. .env 파일을 사용하는 경우 반드시 .gitignore에 추가하세요.
설치 확인
설치가 제대로 완료되었는지 다음 명령어로 확인하세요.
bash
# 버전 확인
claude --version
# 도움말 보기
claude --help설치 완료! Claude Code가 정상적으로 설치되었습니다. 이제 `claude` 명령어로 시작할 수 있습니다.
문제 해결
설치 중 자주 발생하는 문제와 해결 방법입니다.
명령어를 찾을 수 없습니다 (command not found)
PATH 환경 변수가 올바르게 설정되지 않았을 수 있습니다.
bash
# npm global bin 경로 확인
npm bin -g
# PATH에 추가 (bash)
echo 'export PATH="$PATH:$(npm bin -g)"' >> ~/.bashrc
source ~/.bashrcAPI 키 오류 (Invalid API Key)
API 키가 올바르게 설정되지 않았거나 유효하지 않습니다.
- 환경 변수가 올바르게 설정되었는지 확인: echo $ANTHROPIC_API_KEY
- API 키에 따옴표나 공백이 포함되지 않았는지 확인
- Anthropic Console에서 API 키가 활성 상태인지 확인
네트워크 오류 (Connection Failed)
방화벽이나 프록시 설정을 확인하세요. 기업 네트워크에서는 프록시 설정이 필요할 수 있습니다.