Claude Code 설치: Windows, macOS, Linux 명령어와 구독 없이 사용하는 방법

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 공식 설치 문서에 있습니다.

설치 전에

macOS 및 Linux에 설치

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

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

권장 방법입니다. 백그라운드에서 자동 업데이트되는 독립 실행형 바이너리를 설치합니다. 바로 가기는 ~/.local/bin/claude에 있으며, 이미 열려 있던 터미널은 새 PATH를 인식하지 못하므로 테스트하기 전에 새 창을 여세요. WSL에서도 같은 명령어를 사용합니다.

Windows에 설치

Windows에는 서로 다른 두 가지 명령줄이 있으며, 차이는 사용 중인 터미널뿐입니다. 프롬프트가 PS C:\Users\SeuNome>로 시작하면 PowerShell이고, PS 없이 C:\Users\SeuNome>만 있으면 명령 프롬프트(CMD)입니다. 관리자 권한으로 실행할 필요는 없습니다.

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

:: Windows Prompt de Comando (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

잘못된 터미널에 명령줄을 붙여 넣는 것이 가장 흔한 오류입니다. CMD 명령줄을 PowerShell에서 실행하면 The token '&&' is not a valid statement separator가 표시되고, PowerShell 명령줄을 CMD에서 실행하면 'irm' is not recognized as an internal or external command가 표시됩니다(포르투갈어 Windows에서는 “내부 또는 외부 명령으로 인식되지 않습니다”). macOS의 curl … | bash를 PowerShell에 붙여 넣으면 A parameter cannot be found that matches parameter name 'fsSL'가 표시됩니다. 세 경우 모두 올바른 명령줄을 사용하면 됩니다.

Git for Windows 설치는 선택 사항이지만 권장됩니다. Claude Code는 함께 설치되는 Git Bash를 사용해 명령어를 실행하며, 없으면 PowerShell을 사용합니다. Git이 설치되어 있는데도 Git Bash를 찾지 못하면 설정의 env 블록에서 CLAUDE_CODE_GIT_BASH_PATH을 bash.exe을 가리키도록 지정하세요.

WSL에서는 macOS/Linux 명령줄을 WSL 터미널 안에서 실행하고 그곳에서 claude도 여세요 — PowerShell이나 CMD에서 실행하지 마세요.

패키지 관리자 사용

작동하지만 중요한 차이가 있습니다. 어느 것도 기본적으로 자동 업데이트되지 않습니다. 직접 업데이트해야 합니다(brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Debian/Ubuntu, Fedora/RHEL 및 Alpine용 서명된 apt, dnf, apk 저장소도 있습니다.

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

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — exige Node.js 22 ou mais novo; nunca com sudo
npm install -g @anthropic-ai/claude-code

npm을 사용하는 경우 버전 2.1.198부터 패키지에 Node.js 22 이상이 필요합니다. 오래된 Node에서는 npm이 EBADENGINE 경고만 표시하고 설치를 완료합니다. 패키지는 실행에 Node.js를 사용하지 않는 동일한 네이티브 바이너리를 설치합니다. sudo npm install -g는 절대 사용하지 마세요: 권한 문제가 발생하고 보안 위험이 있습니다.

설치 확인

claude --version   # imprime a versão, por exemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico da instalação e das configurações, sem abrir sessão

claude doctor를 기억해 두세요. 로그인하지 않고도 설치 상태, 구성 파일 오류 및 권장 해결 방법을 보여주므로 문제가 설치에 있는지 구성에 있는지 가장 빠르게 확인할 수 있습니다.

command not found: claude가 표시되거나 Windows에서 claude을(를) 인식할 수 없다는 메시지가 표시되면 설치 폴더가 PATH에 포함되어 있지 않은 것입니다. macOS와 Linux에서는 새 터미널을 여세요. 그래도 해결되지 않으면 ~/.zshrc 또는 ~/.bashrc에서 ~/.local/bin을(를) PATH에 추가하세요. Windows에서 해당 폴더는 %USERPROFILE%\.local\bin입니다. PowerShell에서 확인하고 추가하세요:

# 1. Veja se a pasta de instalação já está no PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem saída? Adicione ao PATH do usuário e abra um terminal novo
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. No terminal novo: se houver duas instalações, aparecem dois caminhos
where.exe claude

첫 연결: 구독 또는 API 키

경로 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   # só o domínio, sem /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 창에서 테스트하려면:

# Vale só para esta janela do 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 및 ANTHROPIC_DEFAULT_SONNET_MODEL도 고정하세요. Claude Code의 기본 모델과 opus 별칭은 최신 Opus를 가리키며, Kunavo가 아직 해당 모델을 제공하지 않으면 첫 번째 요청이 404를 반환합니다. sonnet 별칭은 이미 Sonnet 5.5를 요청하지만 Kunavo는 이를 제공하지 않습니다. 고정하지 않으면 /model sonnet, opusplan의 실행 단계 및 model: sonnet을 사용하는 서브에이전트가 404를 받습니다. opus 별칭은 Opus 5.5(claude-opus-5-5)로 고정되며, Claude Code v2.1.280 이상이 필요합니다. 이전 설치에서는 claude update을 실행하세요.
• ANTHROPIC_DEFAULT_HAIKU_MODEL는 Claude Code가 자동으로 수행하는 백그라운드 호출(요약, 제목)을 처리합니다. Haiku로 지정하면 별다른 노력 없이 비용을 절약할 수 있습니다.

키를 프로젝트의 .claude/settings.json에 절대 넣지 마세요. 이 파일은 git에 올라가고 저장소를 복제하는 사람에게도 노출됩니다. VS Code 확장에서는 변수를 VS Code 자체의 사용자 설정인 claudeCode.environmentVariables에 두세요. 확장이 시작 전에 자격 증명을 확인하기 때문입니다.

카탈로그에서 읽은 1M 토큰당 요율:

세션 중 모델을 바꾸려면 전체 이름과 함께 /model(예: /model claude-opus-5-5)를 사용하거나 claude --model claude-opus-5-5와 함께 Claude Code를 시작하세요. 월 사용 비용과 구독이 더 유리한 시점은 Claude Code 가격 가이드에 설명되어 있습니다.

현재 활성 경로 확인

Claude Code 안에서 /status를 실행하세요. Auth token 줄이 있으면 키가 사용 중이고, claude.ai 계정과 함께 Login method 줄이 있으면 변수를 읽지 않은 것입니다. 두 방식은 합산되지 않습니다. 변수가 설정되어 있으면 구독이 중지되고, 변수를 제거하면 재설치 없이 구독으로 돌아갑니다.

게이트웨이 뒤에서는 세 가지가 달라집니다. Remote Control과 음성 받아쓰기는 작동하지 않습니다(claude.ai의 신원이 필요함). /fast는 빠른 모드를 사용할 수 없다고 표시할 수 있습니다. 이 확인은 Anthropic으로 직접 전송되기 때문이지만 일반 요청은 달라지지 않습니다. 또한 /context의 수치는 로컬 추정치가 됩니다. 코드, 도구, 하위 에이전트, MCP, hooks 및 프롬프트 캐싱은 동일하게 작동합니다. 자세한 내용은 통합 문서(영어)에 있습니다.

브라질에서 결제하기 — checkout의 Pix

claude.ai 구독은 국제 결제가 허용된 카드가 필요한 달러 정기 결제입니다. API 키 경로에서는 충전이 Stripe 결제 화면을 통해 이루어지며, 브라질에서 결제하는 경우 Pix가 결제 수단으로 표시됩니다. 가격은 USD로 책정되고, Stripe는 확인 전에 금액을 브라질 헤알로 환산하여 표시합니다. 국제 카드(Visa, Mastercard, American Express), Apple Pay, Google Pay 및 Link도 결제 화면에 표시됩니다. 지갑은 선불 방식입니다. 최소 충전 금액은 $10이고 잔액은 만료되지 않으며 실패한 요청에는 요금이 부과되지 않습니다. 각 키에는 월별 지출 한도를 설정할 수 있습니다. 화면별 단계별 안내는 Pix로 API 결제하기에 있습니다.

일반적인 오류

설치 후

처음 사용할 때 프로젝트 안에서 /init를 실행하세요. Claude Code가 저장소를 읽고 찾은 테스트 명령어와 규칙을 담은 CLAUDE.md를 생성합니다. 이 파일을 검토하고 짧게 유지하세요. 모든 세션에서 로드됩니다. 관련 없는 작업 사이에는 /clear로 새 대화를 시작하고, 작업이 길어지면 /compact로 기록을 요약한 뒤 계속하세요.

선택에 대해 솔직히 말하면, Claude Code를 하루에 여러 시간 사용하는 사람에게는 구독 월 요금이 보통 더 저렴합니다. 사용량이 변동하거나 5시간 창에 묶이고 싶지 않을 때는 종량제가 유리하며, 사용하지 않은 달의 비용은 0입니다. Kunavo에서는 전용 할당량이나 계약상 SLA 없이 공유 용량을 사용합니다. 이러한 보장이 필요하면 Anthropic과 직접 계약해야 합니다.

자주 묻는 질문