Mac, Windows, Linux에 Claude Code 설치하기 (2026)

Q: Claude Code는 어떻게 설치하나요?

macOS, Linux 또는 WSL에서는 `curl -fsSL https://claude.ai/install.sh | bash`를 실행하세요. Windows에서는 PowerShell에서 `irm https://claude.ai/install.ps1 | iex`를 실행하거나 CMD에서 `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`를 실행하세요. 기본 설치 프로그램이 권장되며 백그라운드에서 자체 업데이트됩니다. Homebrew(`brew install --cask claude-code`), WinGet(`winget install Anthropic.ClaudeCode`), npm 및 서명된 apt/dnf/apk 저장소도 지원되지만, 기본적으로 자동 업데이트되지는 않습니다.

Q: Claude Code를 설치하려면 Node.js가 필요한가요?

기본 설치 프로그램, Homebrew, WinGet 또는 Linux 패키지 저장소를 사용하는 경우에는 필요하지 않습니다. 모두 런타임에 Node를 사용하지 않는 네이티브 바이너리를 설치합니다. npm 설치 경로만 Node를 사용하며, v2.1.198부터 해당 패키지에는 Node.js 22 이상이 필요합니다. 그래도 npm은 플랫폼별 선택적 종속성을 통해 동일한 네이티브 바이너리를 가져올 뿐입니다.

Q: Claude Code의 시스템 요구 사항은 무엇인가요?

macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상 또는 Alpine Linux 3.19 이상, x64 또는 ARM64 프로세서에서 4GB 이상의 RAM, 인터넷 연결, 그리고 Bash, Zsh, PowerShell 또는 CMD 셸이 필요합니다. 또한 Anthropic이 지원하는 국가에 있어야 합니다.

Q: 처음 Claude Code에 로그인하려면 어떻게 하나요?

프로젝트 디렉터리에서 `claude`를 실행하고 브라우저 안내를 따르세요. Claude Code를 사용하려면 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 Claude.ai 요금제에는 Claude Code 액세스가 포함되지 않습니다. ANTHROPIC_API_KEY 환경 변수가 설정되어 있으면 Claude Code는 브라우저를 여는 대신 해당 키를 승인할지 한 번 묻습니다.

Q: WSL 없이 Windows에 Claude Code를 설치할 수 있나요?

예. PowerShell 또는 CMD 설치 프로그램을 실행하고 어느 터미널에서든 `claude`를 실행하면 됩니다. 관리자 권한은 필요하지 않습니다. Git for Windows는 선택 사항이지만 Bash 도구를 지원하는 Git Bash를 제공하므로 권장됩니다. 이것이 없으면 Claude Code가 PowerShell 도구를 통해 셸 명령을 실행합니다. Linux 도구 체인이나 네이티브 Windows에서 지원하지 않는 샌드박스 명령 실행이 필요하다면 WSL 2를 선택하세요.

Q: 설치 후 `claude`에서 command not found가 표시되는 이유는 무엇인가요?

사용 중인 셸의 PATH에 설치 디렉터리가 없습니다. 먼저 새 터미널을 여세요. 설치 프로그램은 macOS와 Linux에서 ~/.local/bin을 추가하며 기존 세션에는 이 변경 사항이 반영되지 않습니다. `claude doctor`를 실행하면 설치와 설정 파일에 대한 읽기 전용 진단을 수행할 수 있습니다. 두 번째로 설치된 오래된 버전이나 남아 있는 셸 별칭도 흔한 원인입니다.

Q: Claude Code가 다른 API 엔드포인트를 사용하도록 하려면 어떻게 하나요?

모든 Anthropic Messages API 엔드포인트를 제공하는 원본 주소로 ANTHROPIC_BASE_URL을 설정하세요. Claude Code는 이를 기본적으로 읽고 /v1/messages를 자체적으로 추가하므로 플러그인이나 프록시가 필요하지 않습니다. 인증 정보에는 ANTHROPIC_AUTH_TOKEN을, 모델에는 명시적인 ANTHROPIC_MODEL을 함께 사용하고, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL 및 ANTHROPIC_DEFAULT_HAIKU_MODEL은 해당 엔드포인트가 제공하는 모델로 고정하세요. 그렇지 않으면 opus 및 sonnet 별칭이 Anthropic의 최신 모델을 따르기 때문입니다. Kunavo에서는 동일한 Claude 모델을 Anthropic 정가보다 종량제 기준 30% 낮은 가격으로 사용할 수 있습니다.

Claude Code는 지원되는 모든 플랫폼에서 단일 명령으로 설치되며, 첫 실행 전체 과정은 설치, claude 입력, 로그인입니다. 이 가이드에는 각 운영 체제에 맞는 정확한 명령, 작동하지 않을 때 확인할 사항, 설치 후 다른 엔드포인트로 지정하는 방법이 담겨 있습니다.

2026년 10월 3일 명령 확인 완료: Anthropic의 Claude Code 설정 문서를 기준으로 검증되었습니다.

시작하기 전에

요구 사항	지원되는 항목
운영 체제	macOS 13.0 이상, Windows 10 1809 이상 / Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상
하드웨어	4GB 이상 RAM, x64 또는 ARM64
셸	Bash, Zsh, PowerShell 또는 CMD
네트워크	인터넷 연결 필요
계정	Pro, Max, Team, Enterprise 또는 Console — 무료 Claude.ai 요금제에는 Claude Code가 포함되지 않습니다

설치 — 네이티브 설치 프로그램

모든 플랫폼에서 권장되는 방법입니다. 자체 포함 바이너리를 설치하고 백그라운드에서 자동으로 최신 상태를 유지합니다.

install.sh

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

PowerShell

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

cmd.exe

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

사용 중인 Windows 셸이 확실하지 않다면 프롬프트를 확인하세요. PowerShell에는 PS C:\가 표시되고, CMD에는 C:\가 PS 없이 표시됩니다. 잘못된 명령을 실행하는 것은 Windows에서 설치가 실패하는 가장 흔한 원인입니다. 아래 문제 해결 표에서 각 경우에 발생하는 정확한 오류를 확인하세요.

패키지 관리자

기존 패키지 관리자가 설치를 관리하도록 하려면 이 방법을 사용하세요. 단점은 업데이트입니다. 네이티브 설치 프로그램과 달리 이들 중 어느 것도 기본적으로 자동 업데이트되지 않습니다.

package-managers.sh

# Homebrew (macOS, Linux) — stable channel
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — requires Node.js 22+; never with sudo
npm install -g @anthropic-ai/claude-code

Homebrew는 두 개의 cask를 제공합니다. claude-code는 안정 채널을 추적하며(일반적으로 약 일주일 늦고 주요 회귀가 있는 릴리스는 건너뜁니다), claude-code@latest는 모든 릴리스를 즉시 제공합니다. Debian / Ubuntu, Fedora / RHEL, Alpine용 서명된 apt, dnf, apk 저장소도 각각 동일한 stable 및 latest 채널로 제공됩니다.

npm에서는 sudo npm install -g를 절대 사용하지 마세요. 권한 문제가 발생하고 보안 위험이 있습니다. npm 패키지는 독립 실행형 설치 프로그램과 정확히 동일한 네이티브 바이너리를 설치하므로 어느 쪽을 사용해도 런타임 Node 의존성은 없습니다.

설치 확인

verify.sh

claude --version   # prints e.g. "2.1.211 (Claude Code)"
claude doctor      # read-only install + settings diagnostics
claude             # start a session in the current project

기억해야 할 명령은 claude doctor입니다. 세션을 시작하지 않고 설치 상태, 설정 파일 검증 오류 및 권장 수정 사항을 출력하므로 설치 문제와 설정 문제를 가장 빠르게 구분할 수 있습니다.

첫 실행 및 로그인

작업할 프로젝트에서 터미널을 열고 claude를 실행하세요. 대화형 세션이 열리고 브라우저에서 로그인하는 과정을 안내합니다. Claude Code를 사용하려면 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다.

뜻밖의 동작을 방지하기 위해 알아둘 점이 하나 있습니다. 환경에 ANTHROPIC_API_KEY가 이미 설정되어 있으면 Claude Code는 브라우저를 여는 대신 해당 키를 승인할지 한 번 묻습니다. 이 프롬프트를 거부하면 그 이후에는 추가 프롬프트 없이 키가 조용히 무시됩니다. 따라서 변수를 읽지 못하는 것처럼 보입니다. /config → 사용자 지정 API 키 사용에서 다시 활성화할 수 있습니다.

Windows: 네이티브 또는 WSL

옵션	필요 사항	샌드박싱	다음과 같은 경우 선택
네이티브 Windows	없음. Git for Windows는 선택 사항	지원되지 않음	프로젝트와 도구가 Windows 네이티브 환경에서 실행됨
WSL 2	WSL 2 활성화	지원됨	Linux 도구 체인을 사용하거나 샌드박스된 명령 실행이 필요한 경우
WSL 1	WSL 1 활성화	지원되지 않음	WSL 2를 사용할 수 없는 경우

네이티브 Windows에서는 Git for Windows 설치가 선택 사항이지만 권장됩니다. Bash 도구를 지원하는 Git Bash를 제공합니다. 설치하지 않으면 Claude Code가 PowerShell 도구를 통해 셸 명령을 실행합니다. WSL에서는 PowerShell이 아니라 WSL 터미널 안에서 claude를 설치하고 실행하세요.

문제 해결

증상	원인 및 해결 방법
`The token '&&' is not a valid statement separator`	PowerShell에서 CMD 명령을 실행했습니다. 대신 `irm … \| iex` 줄을 사용하세요.
`'irm' is not recognized…`	반대의 경우입니다. CMD에서 PowerShell 명령을 실행했습니다. `curl … install.cmd` 줄을 사용하세요.
`syntax error near unexpected token '<'`, `403` 또는 기타 curl 오류	다운로드에서 스크립트를 반환하지 않았습니다. 대개 사용자와 설치 프로그램 사이의 프록시 또는 네트워크 필터가 원인입니다. 다시 시도하거나 패키지 관리자 설치를 대신 사용하세요.
새로 설치한 후 `claude: command not found`	새 터미널을 열어 셸이 설치 디렉터리를 인식하도록 한 다음 `claude doctor`를 실행하세요. 두 번째 이전 설치 또는 오래된 셸 별칭도 흔한 원인입니다.
npm 설치 중 권한 오류	`sudo`를 사용했거나 npm 전역 디렉터리에 쓰기 권한이 없습니다. `sudo`를 다시 실행하지 말고 디렉터리 소유권을 수정하세요. 쓰기 불가능한 전역 디렉터리는 자동 업데이트도 차단합니다.
`npm install -g` 후 네이티브 바이너리 누락	패키지 관리자가 선택적 의존성을 건너뛰도록 구성되어 있습니다. 플랫폼 바이너리는 선택적 의존성으로 제공되므로 이를 허용한 후 다시 설치하세요.
Alpine 또는 다른 musl 배포판에서 설치 실패	Alpine에는 `bash` 및 `curl`가 기본으로 포함되지 않습니다. `bash curl libgcc libstdc++ ripgrep`를 설치한 다음 설정 파일의 `env` 블록에서 `USE_BUILTIN_RIPGREP`를 `"0"`로 설정하세요.
검색 및 파일 탐색 실패	ripgrep은 일반적으로 번들로 제공됩니다. 플랫폼에서 실행할 수 없다면 시스템 `ripgrep`를 설치하고 `USE_BUILTIN_RIPGREP=0`를 설정하세요.
네이티브 Windows에서 Bash 도구 누락	Git for Windows를 설치하세요. Claude Code가 여전히 Git Bash를 찾지 못하면 `~/.claude/settings.json`의 `env` 블록에서 `CLAUDE_CODE_GIT_BASH_PATH`를 설정하세요.
키를 구성한 후 `401`	키가 서버가 읽지 않는 헤더에 있습니다. `ANTHROPIC_AUTH_TOKEN`와 `ANTHROPIC_API_KEY` 사이를 바꾸세요. 자세한 내용은 API 키 가이드를 참조하세요.

Claude Code를 Kunavo에 연결하기

실행되면 Claude Code는 Anthropic Messages API를 제공하는 모든 엔드포인트에 연결할 수 있습니다. ANTHROPIC_BASE_URL를 기본적으로 읽으므로 이는 우회 방법이 아니라 지원되는 구성입니다. 플러그인도, 프록시도, 패치된 바이너리도 필요하지 않습니다.

~/.zshrc

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

이 블록에 관해 알아둘 다섯 가지입니다. 하나라도 잘못 설정하면 한 시간이 걸릴 수 있습니다.

ANTHROPIC_BASE_URL는 오리진만 지정합니다. Claude Code가 /v1/messages를 직접 추가하므로 경로를 포함하면 404가 발생합니다.
ANTHROPIC_AUTH_TOKEN를 사용하고 ANTHROPIC_API_KEY는 사용하지 마세요. 두 값은 서로 다른 HTTP 헤더에 들어갑니다. Bearer 토큰은 즉시 적용되지만 ANTHROPIC_API_KEY는 위에서 설명한 일회성 승인이 필요합니다. Kunavo는 /v1/models를 포함해 두 헤더 중 어느 쪽에서도 키를 읽으므로 Kunavo에서는 그 승인 단계가 둘을 구분합니다.
ANTHROPIC_MODEL를 명시적으로 설정하세요. Kunavo는 모델 슬러그를 정확히 일치시키며 날짜가 붙은 이름의 별칭을 제공하지 않습니다. 따라서 claude-sonnet-4-5-20250929는 404를 반환하고 claude-sonnet-5는 작동합니다.
ANTHROPIC_DEFAULT_OPUS_MODEL 및 ANTHROPIC_DEFAULT_SONNET_MODEL도 고정하세요. Claude Code의 기본 모델과 opus 별칭은 모두 최신 Opus로 확인되며, Kunavo가 아직 해당 모델을 제공하지 않으면 첫 요청이 404를 반환합니다. 이 블록은 opus를 Opus 5.5(claude-opus-5-5)로 고정합니다. 이 모델에는 Claude Code v2.1.280 이상이 필요하므로, 이전 버전이 설치되어 있다면 claude update를 실행하세요. sonnet 별칭은 Sonnet 5.5를 요청하지만 Kunavo는 이를 제공하지 않습니다. 따라서 sonnet 고정값 /model sonnet이 없으면 opusplan의 실행 단계와 model: sonnet으로 설정된 모든 하위 에이전트가 404를 반환합니다.
ANTHROPIC_DEFAULT_HAIKU_MODEL는 Claude Code가 요약과 제목을 위해 자체적으로 수행하는 백그라운드 호출을 처리합니다. claude-haiku-4-5는 1M 기준 $0.70 / $3.50이고 주 모델은 $1.40 / $7.00이므로, 한 줄만 추가해도 지속적으로 비용을 절약할 수 있습니다.

편집기와 백그라운드 에이전트에서도 사용할 수 있도록 셸 export 대신 ~/.claude/settings.json의 env 블록에 설정하세요. 프로젝트에 커밋된 .claude/settings.json에는 절대 넣지 마세요. 가입한 후 대시보드에서 sk-kn- 키를 생성하세요. 최소 충전액은 $10이고 월 이용료는 없으며 잔액은 만료되지 않습니다. 각 모델의 토큰당 비용이 Anthropic의 공식 API 가격과 비교해 $10로 얼마나 사용할 수 있는지를 결정합니다.

게이트웨이 뒤에서 달라지는 점

코딩, 도구, 하위 에이전트, MCP, 훅 및 프롬프트 캐싱은 모두 영향을 받지 않습니다. 변경되는 사항은 세 가지이며, 무언가 고장 났다고 생각하기 전에 알아둘 가치가 있습니다.

Remote Control 및 음성 받아쓰기를 사용할 수 없습니다. 두 기능 모두 claude.ai ID가 필요하며 게이트웨이 자격 증명이 이를 대체합니다.
/fast가 fast mode를 비활성화된 것으로 보고할 수 있습니다. 가용성 확인은 기본 URL을 따르지 않고 Anthropic에 직접 호출합니다. 일반 요청에는 영향을 주지 않습니다.
/context 수치는 로컬 추정치가 됩니다. 토큰 수 계산은 Anthropic 자체 게이트웨이 사양에서 선택 사항으로 표시한 유일한 엔드포인트입니다. 이 엔드포인트가 없으면 Claude Code가 로컬에서 추정하며, 현재 Kunavo는 /v1/messages/count_tokens를 제공하지 않습니다. 자동 압축과 세션 자체에는 영향을 주지 않습니다.

전체 목록과 라우터 사용 여부에 대한 결정은 Claude Code 라우터 가이드에 있습니다.

자주 묻는 질문

Claude Code는 어떻게 설치하나요?