Claude Code 공식문서 리뷰-Administration[1] : Claude Code 설정 - 설치 및 설정

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> [관리] 섹션의 내용 중 [Claude Code 설정 - 설치 및 설정]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/ko/setup

Claude Code 설정 - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

 

Claude Code 설치 및 설정

설치 방법, 시스템 요구 사항, 인증 옵션

 

시스템 요구 사항

Claude Code를 설치하고 실행하기 위한 최소 요구 사항입니다.

항목	요구 사항
운영 체제	macOS 10.15+, Ubuntu 20.04+/Debian 10+, Windows 10+ (WSL 권장)
하드웨어	4GB+ RAM
소프트웨어	Node.js 18+ (npm 설치 시에만 필요)
네트워크	인터넷 연결 (Anthropic API 통신용)
쉘	Bash, Zsh, Fish (권장)
지역	Anthropic 서비스 지원 국가 (지원 국가 목록)

 

설치 방법

설치 방법은 여러 가지가 있다. 상황에 맞는 방법을 선택하면 된다.

설치 방법	추천 대상	특징
네이티브	대부분의 사용자	Node.js 불필요, 가장 빠른 설치
Homebrew	macOS/Linux에서 brew 사용자	brew로 통합 관리 가능
npm	Node.js 개발자	Node.js 18+ 필요, npm으로 관리

 

1. 네이티브 설치 (권장)

Claude Code는 자체 설치 프로그램을 제공합니다. 별도의 의존성 없이 가장 빠르게 설치할 수 있습니다.

# 네이티브 설치
curl -fsSL https://claude.ai/install.sh | sh

 

2. Homebrew (macOS/Linux)

macOS 또는 Linux에서 Homebrew를 사용하는 경우:

brew install claude-code

 

3. npm

Node.js가 이미 설치되어 있다면 npm으로 설치할 수 있습니다:

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

참고: npm 설치 시 Node.js 18 이상이 필요합니다. node --version으로 버전을 확인하세요.

 

Windows 설치

Windows에서 Claude Code를 사용하는 방법은 여러 가지가 있다.

 

방법 1: WSL 사용 (권장)

Windows Subsystem for Linux(WSL)를 통해 Linux 환경에서 Claude Code를 실행한다. 최상의 호환성과 성능을 제공한다. WSL 1, WSL 2 모두 지원된다.

# WSL이 설치되어 있지 않다면
wsl --install

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

 

방법 2: PowerShell 네이티브 설치

WSL 없이 Windows에서 직접 실행할 수 있다. PowerShell에서 다음 명령어를 실행한다.

# PowerShell에서 네이티브 설치
irm https://claude.ai/install.ps1 | iex

 

방법 3: CMD 네이티브 설치

명령 프롬프트(CMD)에서도 설치할 수 있다.

REM CMD에서 네이티브 설치
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

 

방법 4: Git Bash 사용

Git for Windows가 설치되어 있다면 Git Bash에서 사용할 수 있다.

# Git Bash 경로가 기본 위치가 아닌 경우 환경변수 설정
$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

참고: 네이티브 Windows 설치는 WSL에 비해 일부 기능에 제한이 있을 수 있다. 최상의 경험을 위해서는 WSL 사용을 권장한다.

 

인증

설치 후 처음 실행하면 인증이 필요하다. Claude Code는 여러 인증 방법을 지원한다.

어떤 인증 방법을 선택해야 할까?

상황	추천 인증 방법
Claude Pro/Max 구독 중	Claude 앱 연동 (가장 간편)
API 사용량을 직접 관리하고 싶다	API 키
회사에서 AWS를 사용한다	AWS Bedrock
회사에서 GCP를 사용한다	Google Vertex AI

1. Claude 앱 연동 (개인 사용자)

Claude Pro 또는 Max 구독자라면 Claude 앱 계정으로 인증할 수 있다. 구독 플랜 확인

# Claude Code 시작
claude

# 브라우저가 열리면 Claude 앱 계정으로 로그인

2. API 키 (개발자)

Anthropic Console에서 API 키를 발급받아 인증할 수 있다. 사용량 기반 과금이 적용된다.

# 환경 변수로 API 키 설정
export ANTHROPIC_API_KEY="sk-ant-..."

# 또는 시작 시 직접 입력
claude --api-key "sk-ant-..."

환경변수 영구 설정: 매번 export 명령을 실행하지 않으려면 쉘 설정 파일에 추가한다.

# ~/.bashrc 또는 ~/.zshrc에 추가
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

3. Enterprise (기업 사용자)

기업 환경에서는 다양한 인증 방법을 지원합니다:

• SSO 연동: SAML, OIDC를 통한 기업 SSO 인증
• AWS Bedrock: AWS 자격 증명으로 인증
• Google Vertex AI: GCP 서비스 계정으로 인증

# AWS Bedrock 사용 시
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

# Google Vertex AI 사용 시
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

 

설치 확인

설치가 완료되면 버전을 확인하여 정상 설치되었는지 검증합니다:

# 버전 확인
claude --version

# 도움말 보기
claude --help

# 인증 상태 확인
claude /doctor

 

업데이트

Claude Code를 최신 버전으로 업데이트하는 방법입니다:

# 네이티브 설치 업데이트
claude update

# Homebrew 업데이트
brew upgrade claude-code

# npm 업데이트
npm update -g @anthropic-ai/claude-code

자동 업데이트: Claude Code는 시작 시 자동으로 업데이트를 확인하고 백그라운드에서 설치한다. 다음 시작 시 적용된다.

특정 버전 설치

특정 버전을 설치하거나 latest 채널을 사용할 수 있다.

# 특정 버전 설치 (macOS/Linux/WSL)
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# latest 채널 (최신 개발 버전)
curl -fsSL https://claude.ai/install.sh | bash -s latest

# PowerShell에서 특정 버전 설치
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

자동 업데이트 비활성화

자동 업데이트를 비활성화하려면 환경변수를 설정한다.

# 환경변수로 설정
export DISABLE_AUTOUPDATER=1

# 또는 ~/.claude/settings.json에 추가
{
  "DISABLE_AUTOUPDATER": 1
}

 

삭제

Claude Code를 제거하려면 설치 방법에 따라 다음 명령을 실행합니다:

# 네이티브 설치 삭제
claude uninstall

# Homebrew 삭제
brew uninstall claude-code

# npm 삭제
npm uninstall -g @anthropic-ai/claude-code

설정 파일 삭제 (선택)

설정 파일과 캐시도 함께 삭제하려면 아래 명령을 실행한다.

# macOS/Linux/WSL - 사용자 설정 삭제
rm -rf ~/.claude          # 사용자 설정 및 상태
rm ~/.claude.json         # 전역 설정 파일

# 프로젝트별 설정 삭제 (프로젝트 디렉토리에서)
rm -rf .claude            # 프로젝트 설정
rm .mcp.json              # MCP 서버 설정

Windows에서는 다음 경로를 삭제한다:

# PowerShell - 사용자 설정 삭제
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

# 프로젝트별 설정 삭제
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force

 

일반적인 문제 해결

Node.js 버전 오류

# 현재 버전 확인
node --version

# nvm으로 Node.js 18 설치
nvm install 18
nvm use 18

권한 오류

# npm 전역 설치 시 권한 문제 해결
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# .bashrc 또는 .zshrc에 추가
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

네트워크 연결 오류

방화벽이나 프록시 환경에서 연결 문제가 발생할 수 있습니다:

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

# 진단 실행
claude /doctor