Claude Code 설치 가이드 — macOS, Windows 명령어, 설치 후 구독 또는 API 키로 연결

Claude Code 설치는 한 줄 명령으로 끝납니다. macOS, Linux 및 WSL에서는 curl -fsSL https://claude.ai/install.sh | bash을 실행하고, Windows PowerShell에서는 irm https://claude.ai/install.ps1 | iex를 실행하세요(CMD에서는 아래 install.cmd 줄을 사용합니다). 설치 후 새 터미널을 열고 claude --version로 확인한 다음 claude를 실행해 시작하세요. 처음 연결할 때는 두 가지 경로가 있습니다. Pro, Max, Team, Enterprise 또는 Console 계정으로 로그인하거나(Claude.ai 무료 요금제에는 Claude Code가 포함되지 않음), ANTHROPIC_BASE_URL 및 ANTHROPIC_AUTH_TOKEN 두 환경 변수를 설정하여 사용량에 따라 과금되는 API 키를 사용할 수 있습니다. 구독은 전혀 필요하지 않습니다.

명령 확인일: 2026년 9월 11일, Anthropic 공식 설치 문서 기준입니다. 이 페이지에서는 설치와 첫 연결만 설명하며, 설치 후 일상적인 사용법은 Claude Code 튜토리얼을 참조하세요.

설치 전 확인

macOS 설치

‘터미널’을 열고 다음 줄을 붙여 넣으세요:

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

공식 권장 기본 설치 방식입니다. 독립 실행 파일을 설치하며 백그라운드에서 자동 업데이트됩니다. 실행 파일의 진입점은 ~/.local/bin/claude입니다. 이미 열려 있는 터미널은 새 PATH를 읽지 않으므로 설치 후 새 창을 여세요. Linux와 WSL에서도 같은 명령을 사용합니다.

Windows 설치

Windows에는 서로 다른 두 명령이 있으며 차이는 어떤 터미널을 열었는지뿐입니다. 프롬프트가 PS C:\Users\你的名字>이면 PowerShell이고, PS 없이 C:\Users\你的名字>만 있으면 명령 프롬프트(CMD)입니다. 관리자 권한으로 실행할 필요가 없습니다.

# 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

잘못된 곳에 붙여 넣는 것이 Windows에서 가장 흔한 실패 원인입니다. PowerShell에서 CMD 줄을 실행하면 The token '&&' is not a valid statement separator가 표시되고, CMD에서 PowerShell 줄을 실행하면 'irm' is not recognized as an internal or external command이 표시됩니다. macOS의 curl … | bash를 PowerShell에 붙여 넣으면 A parameter cannot be found that matches parameter name 'fsSL'가 표시됩니다. 세 경우 모두 해당 터미널에 맞는 줄로 바꾸면 됩니다.

Git for Windows를 별도로 설치하는 것이 좋습니다. Claude Code는 여기에 포함된 Git Bash를 사용해 명령을 실행하며, 설치하지 않으면 PowerShell을 사용합니다. 설치했는데 Git Bash를 찾지 못하면 설정 파일의 env 블록에 CLAUDE_CODE_GIT_BASH_PATH를 추가하고 bash.exe 경로를 지정하세요.

WSL을 선택했다면 위의 macOS/Linux 명령을 WSL 터미널에서 실행하고 claude도 WSL 안에서 시작하세요. PowerShell이나 CMD에서 실행하면 안 됩니다.

패키지 관리 도구로 설치

기존 패키지 관리 도구로 관리할 수도 있지만, 그 경우 기본적으로 자동 업데이트가 되지 않으므로 직접 정기적으로 업그레이드해야 합니다(예: brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Debian／Ubuntu, Fedora／RHEL 및 Alpine에는 공식 서명된 apt, dnf, apk 패키지 저장소도 있습니다.

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

npm 경로는 v2.1.198부터 Node.js 22 이상이 필요합니다. 더 오래된 버전에서는 npm이 EBADENGINE 경고만 출력하고 설치는 완료됩니다. 설치되는 것은 기본 설치 프로그램과 동일한 실행 파일이며 실행 시 Node.js에 의존하지 않습니다. 절대로 sudo npm install -g를 사용하지 마세요. 권한 문제가 남고 보안 위험도 있습니다.

설치 성공 확인

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

claude doctor를 기억해 두는 것이 가장 좋습니다. 세션을 시작하지 않고 설치 상태, 설정 파일 오류 및 권장 해결 방법만 표시하므로 ‘설치가 잘못된 것인지’와 ‘설정이 잘못된 것인지’를 구분하는 가장 빠른 방법입니다.

command not found: claude 또는 Windows에서 'claude' is not recognized가 표시되면 설치 디렉터리가 PATH에 없는 것입니다. macOS/Linux에서는 먼저 새 터미널을 열어 다시 시도하고, 그래도 안 되면 ~/.local/bin를 ~/.zshrc 또는 ~/.bashrc의 PATH에 추가하세요. Windows 설치 위치는 %USERPROFILE%\.local\bin이며 PowerShell에서 확인하고 추가할 수 있습니다:

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

첫 연결: 구독 로그인 또는 사용량 기반 키

경로 A: 구독 계정으로 로그인

프로젝트 폴더에서 claude를 실행하고 브라우저 안내에 따라 Pro, Max, Team, Enterprise 또는 Console 계정으로 로그인하세요. 한 가지 세부 사항에 유의하세요. 환경에 이미 ANTHROPIC_API_KEY가 있으면 Claude Code가 이 키를 사용할지 한 번 묻습니다. 이때 거부를 선택하면 이후 해당 키를 조용히 무시하고 다시 묻지 않으므로 변수를 읽지 못한 것처럼 보입니다. 다시 활성화하려면 /config의 Use custom API key로 이동하세요.

경로 B: 구독 없이 사용량 기반 키 사용

Claude Code는 기본적으로 ANTHROPIC_BASE_URL를 지원하므로 Anthropic Messages API를 제공하는 모든 엔드포인트를 가리키는 설정이 공식적으로 지원됩니다. 플러그인, 프록시 또는 수정된 실행 파일이 필요하지 않습니다. 순서는 다음과 같습니다: 계정 등록, 충전(최소 $10), 키 관리 페이지에서 sk-kn-로 시작하는 키를 생성(한 번만 표시됨)한 후 아래 변수를 설정합니다. macOS/Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只寫到網域，不要加 /v1
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

Windows에서 먼저 PowerShell 창 하나로 테스트하려면:

# 只對這個 PowerShell 視窗有效，關掉就沒了
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

장기적으로 사용하려면 사용자 설정 파일 ~/.claude/settings.json의 env 블록에 작성하는 것이 좋습니다(Windows에서는 %USERPROFILE%\.claude\settings.json). 여기에 작성하면 모든 터미널, 편집기 확장 및 백그라운드 프로세스가 읽을 수 있습니다. 파일에 다른 설정이 이미 있다면 env를 병합하면 됩니다:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

이 여섯 줄에는 각각 하나씩 잘못 설정하면 오랫동안 막힐 수 있는 부분이 있습니다:

• ANTHROPIC_BASE_URL는 도메인까지만 작성하세요. Claude Code가 뒤에 /v1/messages를 자동으로 붙입니다. /v1를 더 입력하면 /v1/v1/messages가 되어 404가 반환됩니다.
• ANTHROPIC_AUTH_TOKEN를 사용하고 ANTHROPIC_API_KEY는 사용하지 마세요. 둘은 서로 다른 HTTP 헤더에 들어갑니다. 전자는 Authorization: Bearer를 전송하여 즉시 적용되고, 후자는 x-api-key를 전송하며 위에서 설명한 일회성 확인을 거쳐야 합니다.
• ANTHROPIC_MODEL 완전하고 정확한 모델 이름을 입력해야 합니다.Kunavo는 정확히 일치하는 이름만 인식하며, 날짜 접미사가 붙은 이전 이름을 자동으로 대응하지 않습니다.
• ANTHROPIC_DEFAULT_OPUS_MODEL은 opus 별칭을 담당합니다. Claude Code의 기본 모델과 opus 별칭은 모두 최신 Opus를 가리키며, Kunavo가 아직 제공하지 않는 모델이면 404가 반환됩니다. 따라서 이 줄과 ANTHROPIC_MODEL를 모두 고정해야 합니다. 여기서는 opus 별칭을 Opus 5.5（claude-opus-5-5）로 고정하며, Claude Code v2.1.280 이상이 필요합니다. 이전 버전이라면 먼저 claude update을 실행하세요.
• ANTHROPIC_DEFAULT_SONNET_MODEL은 sonnet 별칭을 담당합니다. Anthropic API에서 sonnet 별칭은 Sonnet 5.5를 가리키지만 Kunavo는 이 모델을 제공하지 않습니다. 고정하지 않으면 /model sonnet, opusplan의 실행 단계 및 model: sonnet으로 설정된 하위 에이전트가 404를 반환합니다. 따라서 여기서도 Claude Sonnet 5（claude-sonnet-5）로 고정합니다.
• ANTHROPIC_DEFAULT_HAIKU_MODEL 백그라운드 호출을 담당합니다.Claude Code가 자체적으로 수행하는 요약과 제목 생성은 이 모델을 사용합니다: Claude Haiku 4.5 1M token당 $0.70 / $3.50, 주력 모델인 Claude Sonnet 5은 $1.40 / $7.00입니다(Anthropic 공식 가격과 동일).

키를 프로젝트의 .claude/settings.json에 절대 작성하지 마세요. 해당 파일은 commit되어 프로젝트를 clone하는 모든 사람과 공유됩니다. VS Code 확장을 사용하는 경우 변수는 VS Code 사용자 설정의 claudeCode.environmentVariables에 넣으세요. 확장은 시작 전에 자격 증명을 먼저 확인하기 때문입니다.

어느 경로로 연결되었는지 확인하기

Claude Code에 들어간 후 /status를 실행하세요. Auth token 줄이 표시되면 키가 적용된 것입니다. Login method가 표시되고 claude.ai 계정이 나열되면 변수를 읽지 못한 것입니다. 둘은 중첩되지 않습니다. 키 변수가 존재하는 동안에는 로그인된 구독이 일시 중지되고, 변수를 제거하면 재설치 없이 구독으로 돌아갑니다.

게이트웨이를 사용할 때 세 가지가 달라집니다. Remote Control과 음성 입력은 claude.ai 신원이 필요하므로 사용할 수 없습니다. /fast의 가용성 확인은 Anthropic에 직접 질의하므로 사용 불가로 표시될 수 있지만 일반 요청에는 영향이 없습니다. /context의 수치는 로컬 추정치가 됩니다. 코딩, 도구, 하위 에이전트, MCP, hooks 및 프롬프트 캐시는 정상적으로 작동합니다. 자세한 설명은 Claude Code 통합 문서와 Claude Code API 키 가이드에서 확인할 수 있습니다(둘 다 영어).

일반적인 오류 대조표

설치 후

처음 프로젝트에 들어가면 먼저 /init를 실행해 전체 프로젝트를 읽고 CLAUDE.md를 생성하세요. 이후 작업에 따라 Opus, Sonnet, Haiku를 전환하는 방법, 한 세션에서 실제로 얼마를 사용하는지, /clear와 /compact로 비용을 낮추는 방법은 Claude Code 튜토리얼에서 설명합니다.

어느 경로를 선택할지도 솔직하게 말할 필요가 있습니다. 매일 장시간 상호작용하고 사용량이 많은 사람에게는 구독의 고정 월 요금이 대체로 더 저렴합니다. 종량제는 사용량 변동이 크거나 5시간 사용량 창에 제한받고 싶지 않은 사람에게 적합하며, 작업하지 않는 달에는 $0입니다. Kunavo를 통하면 공유 용량을 사용하므로 전용 할당량이나 계약상 SLA가 없습니다. 이러한 보장이 필요한 팀은 Anthropic에서 직접 구매해야 합니다. 두 경로의 월 요금과 손익분기점은 Claude Code 비용에서 확인할 수 있습니다.

자주 묻는 질문