고급 설정 - Claude Code Docs

이 페이지에서는 시스템 요구사항, 플랫폼별 설치 세부사항, 업데이트 및 제거에 대해 다룹니다. 첫 번째 세션의 단계별 안내는 빠른 시작을 참조하세요. 터미널을 처음 사용하는 경우 터미널 가이드를 참조하세요.

시스템 요구사항

Claude Code는 다음 플랫폼 및 구성에서 실행됩니다:

운영 체제:
- macOS 13.0+
- Windows 10 1809+ 또는 Windows Server 2019+
- Ubuntu 20.04+
- Debian 10+
- Alpine Linux 3.19+
하드웨어: 4GB 이상 RAM
네트워크: 인터넷 연결 필수. 네트워크 구성을 참조하세요.
셸: Bash, Zsh, PowerShell 또는 CMD. Windows에서는 Git for Windows가 필요합니다.
위치: Anthropic 지원 국가

추가 종속성

ripgrep: 일반적으로 Claude Code에 포함됩니다. 검색이 실패하면 검색 문제 해결을 참조하세요.

Claude Code 설치

그래픽 인터페이스를 선호하시나요? Desktop 앱을 사용하면 터미널 없이 Claude Code를 사용할 수 있습니다. macOS 또는 Windows용으로 다운로드하세요.터미널이 처음이신가요? 단계별 지침은 터미널 가이드를 참조하세요.

To install Claude Code, use one of the following methods:

Native Install (Recommended)
Homebrew
WinGet

macOS, Linux, WSL:

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

Windows 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

If you see The token '&&' is not a valid statement separator, you’re in PowerShell, not CMD. Use the PowerShell command above instead. Your prompt shows PS C:\ when you’re in PowerShell.Windows requires Git for Windows. Install it first if you don’t have it.

Native installations automatically update in the background to keep you on the latest version.

brew install --cask claude-code

Homebrew offers two casks. claude-code tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. claude-code@latest tracks the latest channel and receives new versions as soon as they ship.

Homebrew installations do not auto-update. Run brew upgrade claude-code or brew upgrade claude-code@latest, depending on which cask you installed, to get the latest features and security fixes.

winget install Anthropic.ClaudeCode

WinGet installations do not auto-update. Run winget upgrade Anthropic.ClaudeCode periodically to get the latest features and security fixes.

설치가 완료된 후 작업하려는 프로젝트에서 터미널을 열고 Claude Code를 시작하세요:

claude

설치 중에 문제가 발생하면 문제 해결 가이드를 참조하세요.

Windows에서 설정

Windows의 Claude Code는 Git for Windows 또는 WSL이 필요합니다. PowerShell, CMD 또는 Git Bash에서 claude를 실행할 수 있습니다. Claude Code는 명령을 실행하기 위해 내부적으로 Git Bash를 사용합니다. PowerShell을 관리자로 실행할 필요가 없습니다. 옵션 1: Git Bash를 사용한 네이티브 Windows Git for Windows를 설치한 후 PowerShell 또는 CMD에서 설치 명령을 실행하세요. Claude Code가 Git Bash 설치를 찾을 수 없으면 settings.json 파일에서 경로를 설정하세요:

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

Claude Code는 또한 Windows에서 PowerShell을 기본적으로 실행할 수 있으며 옵트인 미리보기로 제공됩니다. 설정 및 제한사항은 PowerShell 도구를 참조하세요. 옵션 2: WSL WSL 1과 WSL 2 모두 지원됩니다. WSL 2는 향상된 보안을 위해 샌드박싱을 지원합니다. WSL 1은 샌드박싱을 지원하지 않습니다.

Alpine Linux 및 musl 기반 배포판

Alpine 및 기타 musl/uClibc 기반 배포판의 네이티브 설치 프로그램에는 libgcc, libstdc++ 및 ripgrep이 필요합니다. 배포판의 패키지 관리자를 사용하여 이들을 설치한 후 USE_BUILTIN_RIPGREP=0을 설정하세요. 이 예제는 Alpine에 필요한 패키지를 설치합니다:

apk add libgcc libstdc++ ripgrep

그런 다음 settings.json 파일에서 USE_BUILTIN_RIPGREP을 0으로 설정하세요:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

설치 확인

설치 후 Claude Code가 작동하는지 확인하세요:

claude --version

설치 및 구성을 더 자세히 확인하려면 claude doctor를 실행하세요:

claude doctor

인증

Claude Code는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 Claude.ai 플랜에는 Claude Code 액세스가 포함되지 않습니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry와 같은 타사 API 제공자와 함께 Claude Code를 사용할 수도 있습니다. 설치 후 claude를 실행하고 브라우저 프롬프트를 따라 로그인하세요. 모든 계정 유형 및 팀 설정 옵션은 인증을 참조하세요.

Claude Code 업데이트

네이티브 설치는 백그라운드에서 자동으로 업데이트됩니다. 릴리스 채널을 구성하여 즉시 업데이트를 받을지 또는 지연된 안정적인 일정으로 받을지 제어하거나 자동 업데이트를 비활성화할 수 있습니다. Homebrew 및 WinGet 설치는 수동 업데이트가 필요합니다.

자동 업데이트

Claude Code는 시작 시 및 실행 중에 주기적으로 업데이트를 확인합니다. 업데이트는 백그라운드에서 다운로드 및 설치되며 다음 번에 Claude Code를 시작할 때 적용됩니다.

Homebrew 및 WinGet 설치는 자동으로 업데이트되지 않습니다. brew upgrade claude-code 또는 winget upgrade Anthropic.ClaudeCode를 사용하여 수동으로 업데이트하세요.알려진 문제: Claude Code는 새 버전이 이러한 패키지 관리자에서 사용 가능하기 전에 업데이트를 알릴 수 있습니다. 업그레이드가 실패하면 잠시 기다렸다가 나중에 다시 시도하세요.Homebrew는 업그레이드 후 디스크에 이전 버전을 유지합니다. 디스크 공간을 확보하려면 주기적으로 brew cleanup claude-code를 실행하세요.

릴리스 채널 구성

autoUpdatesChannel 설정으로 Claude Code가 자동 업데이트 및 claude update에 대해 따르는 릴리스 채널을 제어하세요:

"latest", 기본값: 새 기능이 릴리스되는 즉시 받기
"stable": 일반적으로 약 1주일 된 버전을 사용하여 주요 회귀가 있는 릴리스 건너뛰기

이를 /config → 자동 업데이트 채널을 통해 구성하거나 settings.json 파일에 추가하세요:

{
  "autoUpdatesChannel": "stable"
}

엔터프라이즈 배포의 경우 관리 설정을 사용하여 조직 전체에서 일관된 릴리스 채널을 적용할 수 있습니다.

자동 업데이트 비활성화

settings.json 파일의 env 키에서 DISABLE_AUTOUPDATER를 "1"로 설정하세요:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

수동으로 업데이트

다음 백그라운드 확인을 기다리지 않고 즉시 업데이트를 적용하려면 다음을 실행하세요:

claude update

고급 설치 옵션

이러한 옵션은 버전 고정, npm에서 마이그레이션 및 바이너리 무결성 확인을 위한 것입니다.

특정 버전 설치

네이티브 설치 프로그램은 특정 버전 번호 또는 릴리스 채널(latest 또는 stable)을 허용합니다. 설치 시 선택한 채널이 자동 업데이트의 기본값이 됩니다. 자세한 내용은 릴리스 채널 구성을 참조하세요. 최신 버전을 설치하려면(기본값):

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

irm https://claude.ai/install.ps1 | iex

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

안정적인 버전을 설치하려면:

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd

특정 버전 번호를 설치하려면:

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.89 && del install.cmd

더 이상 사용되지 않는 npm 설치

npm 설치는 더 이상 사용되지 않습니다. 네이티브 설치 프로그램이 더 빠르고 종속성이 필요 없으며 백그라운드에서 자동으로 업데이트됩니다. 가능하면 네이티브 설치 방법을 사용하세요.

npm에서 네이티브로 마이그레이션

이전에 npm으로 Claude Code를 설치한 경우 네이티브 설치 프로그램으로 전환하세요:

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

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

기존 npm 설치에서 claude install을 실행하여 네이티브 바이너리를 나란히 설치한 후 npm 버전을 제거할 수도 있습니다.

npm으로 설치

호환성 이유로 npm 설치가 필요한 경우 Node.js 18+가 설치되어 있어야 합니다. 패키지를 전역으로 설치하세요:

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

sudo npm install -g를 사용하지 마세요. 이는 권한 문제 및 보안 위험으로 이어질 수 있습니다. 권한 오류가 발생하면 권한 오류 문제 해결을 참조하세요.

바이너리 무결성 및 코드 서명

각 릴리스는 모든 플랫폼 바이너리에 대한 SHA256 체크섬을 포함하는 manifest.json을 게시합니다. 매니페스트는 Anthropic GPG 키로 서명되므로 매니페스트의 서명을 확인하면 이것이 나열하는 모든 바이너리를 전이적으로 확인합니다.

매니페스트 서명 확인

다음 단계 1-3에는 gpg 및 curl이 있는 POSIX 셸이 필요합니다. Windows에서는 Git Bash 또는 WSL에서 실행하세요. 4단계에는 PowerShell 옵션이 포함됩니다.

공개 키 다운로드 및 가져오기

릴리스 서명 키는 고정 URL에 게시됩니다.

curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import

가져온 키의 지문을 표시합니다.

gpg --fingerprint [email protected]

출력에 이 지문이 포함되어 있는지 확인하세요:

31DD DE24 DDFA B679 F42D  7BD2 BAA9 29FF 1A7E CACE

매니페스트 및 서명 다운로드

VERSION을 확인하려는 릴리스로 설정하세요.

REPO=https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases
VERSION=2.1.89
curl -fsSLO "$REPO/$VERSION/manifest.json"
curl -fsSLO "$REPO/$VERSION/manifest.json.sig"

서명 확인

매니페스트에 대해 분리된 서명을 확인합니다.

gpg --verify manifest.json.sig manifest.json

유효한 결과는 Good signature from "Anthropic Claude Code Release Signing <[email protected]>"을 보고합니다.gpg는 또한 새로 가져온 키에 대해 WARNING: This key is not certified with a trusted signature!을 인쇄합니다. 이는 예상된 것입니다. Good signature 줄은 암호화 확인이 통과했음을 확인합니다. 1단계의 지문 비교는 키 자체가 진정함을 확인합니다.

바이너리를 매니페스트와 비교

다운로드한 바이너리의 SHA256 체크섬을 manifest.json의 platforms.<platform>.checksum 아래에 나열된 값과 비교합니다.

Linux
macOS
Windows PowerShell

sha256sum claude

shasum -a 256 claude

(Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()

매니페스트 서명은 2.1.89 이상의 릴리스에 사용 가능합니다. 이전 릴리스는 분리된 서명 없이 manifest.json에 체크섬을 게시합니다.

플랫폼 코드 서명

서명된 매니페스트 외에도 개별 바이너리는 지원되는 플랫폼에서 플랫폼 기본 코드 서명을 수행합니다.

macOS: “Anthropic PBC”에서 서명하고 Apple에서 공증합니다. codesign --verify --verbose ./claude로 확인하세요.
Windows: “Anthropic, PBC”에서 서명합니다. Get-AuthenticodeSignature .\claude.exe로 확인하세요.
Linux: 위의 매니페스트 서명을 사용하여 무결성을 확인하세요. Linux 바이너리는 개별적으로 코드 서명되지 않습니다.

Claude Code 제거

Claude Code를 제거하려면 설치 방법에 따른 지침을 따르세요.

네이티브 설치

Claude Code 바이너리 및 버전 파일을 제거하세요:

macOS, Linux, WSL
Windows PowerShell

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

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

Homebrew 설치

Homebrew cask를 제거하세요:

brew uninstall --cask claude-code

WinGet 설치

WinGet 패키지를 제거하세요:

winget uninstall Anthropic.ClaudeCode

npm

전역 npm 패키지를 제거하세요:

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

구성 파일 제거

구성 파일을 제거하면 모든 설정, 허용된 도구, MCP 서버 구성 및 세션 기록이 삭제됩니다.

Claude Code 설정 및 캐시된 데이터를 제거하려면:

macOS, Linux, WSL
Windows PowerShell

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

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

# 사용자 설정 및 상태 제거
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

관리

​시스템 요구사항

​추가 종속성

​Claude Code 설치

​Windows에서 설정

​Alpine Linux 및 musl 기반 배포판

​설치 확인

​인증

​Claude Code 업데이트

​자동 업데이트

​릴리스 채널 구성

​자동 업데이트 비활성화

​수동으로 업데이트

​고급 설치 옵션

​특정 버전 설치

​더 이상 사용되지 않는 npm 설치

​npm에서 네이티브로 마이그레이션

​npm으로 설치

​바이너리 무결성 및 코드 서명

​매니페스트 서명 확인

​플랫폼 코드 서명

​Claude Code 제거

​네이티브 설치

​Homebrew 설치

​WinGet 설치

​npm

​구성 파일 제거

시스템 요구사항

추가 종속성

Claude Code 설치

Windows에서 설정

Alpine Linux 및 musl 기반 배포판

설치 확인

인증

Claude Code 업데이트

자동 업데이트

릴리스 채널 구성

자동 업데이트 비활성화

수동으로 업데이트

고급 설치 옵션

특정 버전 설치

더 이상 사용되지 않는 npm 설치

npm에서 네이티브로 마이그레이션

npm으로 설치

바이너리 무결성 및 코드 서명

매니페스트 서명 확인

플랫폼 코드 서명

Claude Code 제거

네이티브 설치

Homebrew 설치

WinGet 설치

npm

구성 파일 제거