Windows, macOS, Linux에 Claude Code 설치하는 법 — 구독 없이 사용하는 법

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를 실행하세요. 첫 번째 유용한 명령은 /init입니다. 연결 방법은 두 가지입니다. 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에 Claude Code 설치

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

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

:: Windows Símbolo del sistema (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 블록에서 bash.exe 경로를 사용하여 CLAUDE_CODE_GIT_BASH_PATH을 정의하세요.

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 — requiere Node.js 22 o posterior; nunca con 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 la versión, por ejemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico de la instalación y la configuración, sin abrir sesión

claude doctor만 기억해 두세요. 로그인하지 않아도 설치 상태, 구성 파일의 오류 및 권장 해결 방법을 보여 줍니다. 설치 문제인지 구성 문제인지 가장 빠르게 확인하는 방법입니다.

command not found: claude가 표시되거나(Windows에서는 claude가 인식되지 않는 경우) 설치 폴더가 PATH에 없는 것입니다. macOS와 Linux에서는 새 터미널을 열고, 그래도 같으면 ~/.zshrc 또는 ~/.bashrc에서 ~/.local/bin를 PATH에 추가하세요. Windows의 폴더는 %USERPROFILE%\.local\bin입니다. PowerShell에서 확인하고 추가하세요:

# 1. Comprueba si la carpeta de instalación ya está en el PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. ¿Sin salida? Añádela al PATH de usuario y abre una terminal nueva
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. En la terminal nueva: si hay dos instalaciones, verás dos rutas
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- 키를 생성하고(한 번만 표시됨), 이 env 블록을 사용자 구성 ~/.claude/settings.json에 추가하세요(Windows에서는 %USERPROFILE%\.claude\settings.json). 이렇게 하면 모든 터미널, 편집기 확장 및 백그라운드 프로세스에서 사용할 수 있습니다:

{
  "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"
  }
}

먼저 PowerShell의 한 창에서만 테스트하려면:

# Solo para esta ventana de PowerShell (en macOS/Linux: export VARIABLE=valor)
$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

• 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도 고정합니다. Claude Code의 기본 모델과 별칭 opus는 가장 최신 Opus를 가리키며, Kunavo에서 아직 제공하지 않는 경우 첫 요청이 404를 반환합니다. 여기서는 별칭 opus를 Claude Opus 5.5(claude-opus-5-5)로 고정합니다. 이 모델에는 Claude Code v2.1.280 이상이 필요하며, 이전 버전에서는 claude update를 실행하세요.
• ANTHROPIC_DEFAULT_SONNET_MODEL도 마찬가지입니다. 별칭 sonnet는 Kunavo가 제공하지 않는 Sonnet 5.5를 요청합니다. 이 변수가 없으면 /model sonnet, opusplan의 실행 단계 및 sonnet로 구성된 하위 에이전트가 404를 반환합니다. 이를 claude-sonnet-5로 설정하면 문제가 해결됩니다.
• ANTHROPIC_DEFAULT_HAIKU_MODEL는 Claude Code가 자체적으로 수행하는 백그라운드 호출(요약, 제목)을 담당합니다. 이를 Haiku로 지정하면 별다른 노력 없이 비용을 절약할 수 있습니다.

키를 프로젝트의 .claude/settings.json에 절대 넣지 마세요. 이 파일은 저장소에 커밋됩니다. VS Code 확장에서는 변수를 claudeCode.environmentVariables에 넣고 VS Code 사용자 설정에서 구성하세요. 확장이 시작 전에 인증 정보를 확인하기 때문입니다.

카탈로그에서 읽은 100만 토큰당 요금:

어떤 옵션이 활성 상태인지 확인하는 방법

Claude Code에서 /status를 실행하세요. Auth token 행은 키가 사용 중임을 의미하고, claude.ai 계정과 함께 Login method 행이 표시되면 변수가 읽히지 않았다는 뜻입니다. 두 항목은 합산되지 않습니다. 변수가 존재하는 동안에는 구독이 일시 중지되고, 변수를 제거하면 재설치 없이 Claude Code가 구독으로 돌아갑니다.

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

Claude Code 사용 방법: 시작하기

# 1. Arranca siempre dentro de la carpeta del proyecto
cd ~/proyectos/mi-app
claude

# 2. Primer comando: lee el repositorio y genera CLAUDE.md
> /init

# 3. Pide las tareas en español y con la ruta del archivo
> cambia la validación de src/api/user.ts a zod y arregla los tests

# 4. Para tareas que tocan muchos archivos: Shift+Tab activa el modo plan

Claude Code는 파일을 편집하거나 명령을 실행하기 전에 권한을 요청합니다. 잘못된 방향으로 진행되면 Esc를 눌러 중지하고 /rewind를 사용해 이전 지점으로 돌아가세요. CLAUDE.md에서 생성하는 /init는 초안입니다. 매 세션마다 반복할 내용(테스트 명령, 규칙, 건드리지 않을 폴더)만 남겨 두세요. 매 세션에 로드되고 모든 요청에 포함되며, Anthropic은 200줄을 넘기지 않을 것을 권장합니다.

• 모델 변경: /model 뒤에 전체 이름을 입력하세요. 예: /model claude-opus-5. 또는 claude --model claude-opus-5로 시작하세요. 작업 사이에 변경하세요. 모델마다 자체 캐시가 있으므로 작업 중간에 변경하면 캐시 없이 전체 대화를 다시 읽어야 합니다.
• 서로 관련 없는 작업 사이에 /clear. 새 대화를 시작하면 비용이 들지 않으며, 이전 대화는 /resume로 복구할 수 있습니다.
• 작업이 길어질 때 /compact: 기록을 요약하고 계속 진행하세요. API 키를 사용하면 기본적으로 캐시가 5분 동안 유지되므로, 긴 휴식 후가 아니라 휴식 전에 압축하세요.
• 세션 비용: /usage는 토큰을 표시하지만, 계산된 금액은 Anthropic의 정가를 기준으로 한 로컬 추정치입니다. Kunavo에서는 실제 청구액을 사용량 페이지에서 확인할 수 있습니다.

결제와 선택의 정직성

잔액은 Stripe를 통한 선불 방식입니다. 카드(Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay 또는 Link를 사용할 수 있으며 SEPA 자동이체는 제공되지 않습니다. 최소 충전 금액은 $10이고 잔액은 만료되지 않으며 실패한 요청에는 요금이 부과되지 않습니다. 각 키에는 월별 지출 한도가 적용됩니다. 모든 요금은 가격 페이지에 있습니다.

Claude Code를 하루에 여러 시간 사용한다면 구독의 고정 요금이 대체로 더 저렴합니다. 사용량이 불규칙하거나 5시간 사용 창에 의존하고 싶지 않을 때는 종량제가 유리하며, 활동이 없는 달의 비용은 0입니다. 전체 비교는 영어로 Claude Code 요금 안내에 있습니다. Kunavo를 이용하면 전용 할당량이나 계약상 SLA 없이 공유 용량을 사용합니다. 이러한 보장이 필요하다면 Anthropic과 직접 계약하세요.

자주 묻는 질문