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 줄을 사용). 그런 다음 결제 방법을 선택합니다. Pro, Max, Team, Enterprise 또는 Console 계정으로 로그인할 수 있으며(무료 Claude.ai 구독에는 Claude Code가 포함되지 않음), 구독 없이 API 키를 사용할 수도 있습니다. 이 경우 ANTHROPIC_BASE_URL(/v1 없이 도메인만), ANTHROPIC_AUTH_TOKEN 및 네 개의 모델 변수를 설정하고 /status로 키가 활성 상태인지 확인합니다. Kunavo 잔액은 iDEAL(네덜란드) 또는 Bancontact(벨기에)로 $10부터 월 요금 없이 충전할 수 있습니다.
Commando’s en variabelen gecontroleerd op 2026년 10월 3일 in de Claude Code 공식 설치 문서 en de 환경 변수 문서; prijzen en betaalmethoden gecontroleerd op 2026년 10월 3일. Nederland en België staan allebei op de Anthropic이 지원하는 국가 목록 (gecontroleerd op 2026년 10월 3일), zowel voor Claude.ai als voor de API. Deze handleiding bestaat ook in het Engels: Claude Code 설치.
설치하기 전에
| 항목 | 요구 사항(공식 설치 문서, 2026년 10월 3일 기준 확인) |
|---|---|
| 운영 체제 | macOS 13.0 이상; Windows 10 1809 이상 또는 Windows Server 2019 이상; Ubuntu 20.04 이상; Debian 10 이상; Alpine Linux 3.19 이상 |
| 하드웨어 | 최소 4GB RAM, x64 또는 ARM64 프로세서(32비트 Windows 제외) |
| 셸 | Bash, Zsh, PowerShell 또는 CMD |
| 네트워크 및 위치 | Anthropic이 지원하는 국가에서의 인터넷 연결(네덜란드와 벨기에 포함) |
| 계정 | 로그인하려면 Pro, Max, Team, Enterprise 또는 Console이 필요합니다. 무료 Claude.ai 구독에는 Claude Code가 포함되지 않습니다. API 키를 사용하면 구독이 필요 없고 로그인하지 않습니다. |
| Node.js | npm 경로에서만 필요하며 버전 22 이상이어야 합니다. 네이티브 설치 프로그램에는 필요하지 않습니다. |
macOS 및 Linux에 Claude Code 설치
터미널을 열고 다음 줄을 붙여 넣으세요:
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash권장되는 네이티브 설치 방식으로, 백그라운드에서 자체 업데이트되는 독립 실행 프로그램 하나를 설치합니다. claude 명령은 ~/.local/bin에 설치됩니다. 이미 열려 있던 터미널은 새 PATH를 인식하지 못하므로 테스트하기 전에 새 창을 여세요. WSL에서는 WSL 터미널에서 정확히 같은 줄을 사용하세요.
Windows에 Claude Code 설치
Windows에서는 두 줄 중 하나를 사용하며, 필요한 줄은 열어 둔 창에 따라 달라집니다. 프롬프트가 PS C:\Users\Naam>로 시작하면 PowerShell이고, PS 없이 C:\Users\Naam>만 표시되면 명령 프롬프트(CMD)입니다. 창을 관리자로 열 필요는 없습니다. 공식 문서에 따르면 필요하지 않습니다.
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex:: Windows Opdrachtprompt (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에서는 두 번째 메시지가 네덜란드어로 표시될 수 있지만 원인은 같습니다. 또한 | bash가 포함된 macOS용 줄을 PowerShell에서 실행하면 bash를 인식할 수 없다는 오류가 표시됩니다. 세 경우 모두 현재 창에 맞는 줄을 사용하세요.
Git for Windows is optioneel. Staat het erop, dan voert Claude Code commando’s uit via de meegeleverde Git Bash; zonder Git gebruikt het PowerShell. Is Git wel geïnstalleerd maar wordt Git Bash niet gevonden, zet dan CLAUDE_CODE_GIT_BASH_PATH in het env-blok van ~/.claude/settings.json op het pad naar bash.exe; het voorbeeldpad in de documentatie is C:\Program Files\Git\bin\bash.exe.
| 옵션 | 필요한 것 | 샌드박싱 | 선택할 때 |
|---|---|---|---|
| 네이티브 Windows | 없음; Git for Windows는 선택 사항 | 지원되지 않음 | Windows 자체에서 실행되는 프로젝트 및 도구 |
| WSL 2 | WSL 2 활성화 | 지원됨 | Linux 도구가 필요하거나 샌드박스에서 명령을 실행해야 하는 경우 |
| WSL 1 | WSL 1 활성화 | 지원되지 않음 | WSL 2를 사용할 수 없는 경우 |
따라서 일부 오래된 가이드의 설명과 달리 WSL은 필수가 아니라 선택 사항입니다. WSL을 선택하면 WSL 터미널에서 macOS/Linux용 줄을 실행하고 claude도 PowerShell이나 CMD가 아닌 그곳에서 시작하세요.
Homebrew, WinGet 또는 npm 사용
이 방법도 가능하지만 한 가지 중요한 차이가 있습니다. 공식 문서에 따르면 Homebrew 및 WinGet 설치는 자동으로 업데이트되지 않습니다. 따라서 직접 업데이트해야 합니다:
# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code # bijwerken gebeurt niet vanzelf
# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode # bijwerken gebeurt niet vanzelfnpm 패키지에는 오래된 가이드에 여전히 적힌 Node.js 18이 아니라 Node.js 22 이상이 필요합니다. 이전 버전의 Node.js를 사용하면 npm은 EBADENGINE 경고만 표시하고 설치를 계속합니다. 패키지는 실행 시 Node.js가 필요하지 않은 동일한 네이티브 프로그램을 설치합니다. sudo npm install -g는 절대 사용하지 마세요. 권한 문제가 발생하고 보안 위험이 있습니다. 업데이트는 @latest로 하고 npm update -g는 사용하지 마세요.
node -v # moet v22 of hoger zijn
npm install -g @anthropic-ai/claude-code # nooit met sudo
# later bijwerken: met @latest, niet met npm update -g
npm install -g @anthropic-ai/claude-code@latest설치 확인
claude --version # toont het versienummer, gevolgd door (Claude Code)
claude doctor # alleen-lezen diagnose van installatie en instellingen, start geen sessieclaude doctor는 세션을 시작하지 않고 설치 상태와 설정 파일 상태를 표시합니다. 이를 통해 문제가 설치에 있는지 구성에 있는지 빠르게 확인할 수 있습니다.
Krijg je command not found: claude, of meldt Windows dat claude niet wordt herkend, dan staat de installatiemap niet in je PATH. Open eerst een nieuw terminalvenster. Helpt dat niet, zet dan op macOS en Linux ~/.local/bin in je PATH via ~/.zshrc of ~/.bashrc. Op Windows is de map %USERPROFILE%\.local\bin; volgens de 공식 문제 해결 controleer en voeg je die zo toe in PowerShell:
# 1. Staat de installatiemap al in je PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'
# 2. Geen uitvoer? Voeg de map toe aan je gebruikers-PATH en open een nieuw venster
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
# 3. In het nieuwe venster: twee paden betekent twee installaties naast elkaar
where.exe claudenpm으로 설치했는데 PowerShell에 npm.ps1 cannot be loaded because running scripts is disabled on this system가 표시된다면 PowerShell의 실행 정책이 npm 시작 스크립트를 차단하는 것입니다. 네이티브 설치 프로그램을 사용하거나, npm.cmd을 시작한 후 claude.cmd를 실행하거나, 현재 사용자에 대해 로컬 스크립트를 허용하세요:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser첫 실행: 구독 또는 API 키
처음 실행할 때 Claude Code의 결제 방식을 선택합니다. 두 경로는 서로 배타적입니다. API 키가 설정되어 있으면 저장된 로그인은 사용되지 않으며, 변수를 제거하면 Claude Code는 다시 설치하지 않고 로그인으로 돌아갑니다.
| 경로 A: 구독으로 로그인 | 경로 B: 구독 없이 API 키 사용 | |
|---|---|---|
| 필요한 것 | Pro, Max, Team, Enterprise 또는 Console 계정 | sk-kn-로 시작하는 Kunavo 키 |
| 결제 방법 | Pro 및 Max: 월 정액; Console: Anthropic에서 토큰당 결제 | 선불 잔액에서 토큰당 결제; 월 요금 없음 |
| 결제 수단 | 웹사이트에서는 신용카드 또는 직불카드만 | iDEAL, Bancontact, 카드, Apple Pay, Google Pay 또는 Link |
| Remote Control 및 음성 받아쓰기 | 사용 가능: 둘 다 claude.ai 로그인이 있어야 작동 | 사용할 수 없음 |
| 설정 | 브라우저에서 로그인 | 환경 변수 6개 |
경로 A: 구독으로 로그인
프로젝트 디렉터리에서 claude를 시작하고 브라우저를 통해 로그인합니다. 한 가지 주의할 점은 ANTHROPIC_API_KEY가 이미 설정되어 있으면 Claude Code가 해당 키를 사용할지 한 번 묻는다는 것입니다. 거부하면 이후에는 다시 묻지 않고 키를 무시하므로 변수가 읽히지 않는 것처럼 보입니다. /config → Use custom API key를 통해 다시 활성화할 수 있습니다.
경로 B: 구독 없이 API 키 사용
ANTHROPIC_BASE_URL는 Claude Code에 내장된 변수입니다. 공식 문서에 따르면 이 변수는 API 엔드포인트를 재정의하여 프록시 또는 게이트웨이를 통해 요청을 보냅니다. 따라서 Claude Code가 Anthropic Messages API를 사용하는 엔드포인트를 가리키도록 하는 것은 플러그인이나 사용자 지정 버전 없이 지원되는 구성입니다. 단계는 다음과 같습니다:
- Kunavo 계정을 만드세요.
- Billing에서 $10부터 잔액을 충전합니다(iDEAL 및 Bancontact는 뒤에서 설명합니다).
- /app/keys에서
sk-kn-로 시작하는 키를 생성합니다. 키는 한 번만 표시되므로 즉시 저장하세요. - 변수를 설정합니다. macOS 및 Linux에서는
~/.zshrc또는~/.bashrc에 설정합니다:
export ANTHROPIC_BASE_URL=https://api.kunavo.com # alleen het domein, zonder /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-5Windows에서 먼저 하나의 PowerShell 창에서 테스트하려면:
# Geldt alleen voor dit PowerShell-venster
$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영구적으로 사용하려면 사용자 설정의 env 블록이 가장 적합합니다: ~/.claude/settings.json(Windows에서는 %USERPROFILE%\.claude\settings.json). 여기의 값은 백그라운드 에이전트를 포함하여 Claude Code가 실행되는 모든 곳에 적용됩니다. 셸의 변수는 해당 터미널 창에만 적용되므로 Dock이나 시작 메뉴에서 여는 편집기에는 표시되지 않습니다. 파일에 다른 설정이 이미 있다면 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"
}
}Zet de sleutel 절대 in de .claude/settings.json van een project: volgens de 공식 게이트웨이 문서 (gecontroleerd op 2026년 10월 3일) wordt dat bestand gecommit en gedeeld met iedereen die de repository kloont. Let ook op de volgorde: zetten zowel je shell als een instellingenbestand dezelfde variabele, dan wint het instellingenbestand. Heeft een gewijzigde shellvariabele geen effect, kijk dan eerst in settings.json.
각 줄마다 고유한 주의점이 있습니다:
ANTHROPIC_BASE_URL는 도메인만 지정합니다. Claude Code가 뒤에/v1/messages를 자동으로 추가하므로, 끝에/v1를 넣으면 요청이/v1/v1/messages로 전송되어 404가 발생합니다.ANTHROPIC_AUTH_TOKEN를 사용하고ANTHROPIC_API_KEY는 사용하지 마세요. 문서에 따르면ANTHROPIC_AUTH_TOKEN는Authorization헤더로 전달되며 앞에Bearer가 붙으므로 즉시 적용됩니다.ANTHROPIC_API_KEY는x-api-key헤더에 들어가며 대화형 모드에서는 먼저 한 번 승인해야 합니다(경로 A 참조).- 모델 이름을
ANTHROPIC_MODEL에 정확히 입력하세요. Kunavo는 정확한 이름만 인식하며 뒤에 날짜가 붙은 이전 이름을 변환하지 않습니다. ANTHROPIC_DEFAULT_OPUS_MODEL및ANTHROPIC_DEFAULT_SONNET_MODEL도 고정하세요. Volgens de 모델 구성 문서 (gecontroleerd op 2026년 10월 3일) wijzen de standaardinstelling en de aliasopusvoor API-gebruikers naar Opus 5.5 en de aliassonnetnaar Sonnet 5.5, en schuiven die aliassen mee met nieuwe versies. Vastzetten doe je met de volledige modelnaam of met variabelen alsANTHROPIC_DEFAULT_OPUS_MODEL. Kunavo biedt Sonnet 5.5 nu niet aan, en een nieuw Opus-model staat er niet altijd meteen; een model dat er niet is, geeft een 404. ZonderANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5mislukken daardoor/model sonnet, de uitvoerfase vanopusplanen subagents die opmodel: sonnetstaan. De aliasopuszet je vast op Opus 5.5 (claude-opus-5-5); daarvoor heb je Claude Code v2.1.280 of nieuwer nodig; een oudere versie werk je bij metclaude update.ANTHROPIC_DEFAULT_HAIKU_MODEL는 백그라운드 작업에도 적용됩니다. 문서에 따르면 이 변수는haiku별칭과 세션 제목 같은 백그라운드 기능의 모델을 결정합니다. Claude Haiku 4.5를 사용하면 비용을 낮게 유지할 수 있습니다.
VS Code 확장을 사용하는 경우 변수는 VS Code 자체의 사용자 설정인 claudeCode.environmentVariables에 설정하세요(명령 Preferences: Open User Settings (JSON)). 확장은 시작 전에 해당 위치의 로그인 정보를 이미 확인합니다. ~/.claude/settings.json의 값은 시작된 프로세스에는 전달되지만 이 확인에는 사용되지 않습니다.
{
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://api.kunavo.com" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-kn-..." },
{ "name": "ANTHROPIC_MODEL", "value": "claude-sonnet-5" },
{ "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "claude-opus-5-5" },
{ "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
{ "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "claude-haiku-4-5" }
]
}Prijzen per miljoen tokens, uit de Kunavo-catalogus; de lijstprijs van Anthropic komt van claude.com/pricing (gecontroleerd op 2026년 10월 3일):
| 모델 | Kunavo (입력 / 출력) | Anthropic 정가(입력 / 출력) | 차이 | 용도 |
|---|---|---|---|---|
claude-haiku-4-5 | $0,70 / $3,50 | $1,00 / $5,00 | 약 30% 낮음 | Claude Code 자체의 백그라운드 작업 및 간단한 작업 |
claude-sonnet-5 | $1,40 / $7,00 | $2,00 / $10,00 | 약 30% 낮음 | 일상 작업의 기본 모델 |
claude-opus-5-5 | $2,80 / $14,00 | $4,00 / $20,00 | 약 30% 낮음 | 대규모 리팩터링 및 계획 수립 |
세션 중에는 /model claude-opus-5-5로 전환하거나, claude --model claude-opus-5-5로 바로 시작할 수 있습니다. Claude Code의 월별 대략적인 비용과 구독이 더 유리한 시기는 Claude Code pricing(영어)에서 확인할 수 있으며, 자신의 사용량은 Claude 토큰 계산기로 계산할 수 있습니다. 모든 모델과 가격은 가격 페이지에 나와 있습니다.
/status로 확인
claude를 시작합니다. ANTHROPIC_AUTH_TOKEN가 설정되어 있으면 로그인 화면이 표시되지 않습니다: 변수가 즉시 적용됩니다. 그래도 로그인 화면이 표시된다면 Claude Code가 키를 읽지 못한 것입니다. 이 경우 Claude Code가 첫 실행 마법사 전에 읽는 위치에 설정하세요. 셸의 export 또는 ~/.claude/settings.json의 env 블록이 해당됩니다. 프로젝트의 .claude/settings.json 또는 .claude/settings.local.json에 있는 env 블록은 대화형 세션에서 첫 실행 마법사와 디렉터리 신뢰 여부를 묻는 과정이 끝난 후에만 적용됩니다.
Typ in de sessie /status en kijk op het tabblad Status naar twee regels (bron: de 공식 게이트웨이 문서, gecontroleerd op 2026년 10월 3일):
Anthropic base URL에https://api.kunavo.com가 표시되어야 합니다. 이 줄은 게이트웨이 주소가 설정된 경우에만 나타납니다. 표시되지 않는다면ANTHROPIC_BASE_URL가 세션에 적용되지 않은 것입니다.Auth token에ANTHROPIC_AUTH_TOKEN가 표시되어야 합니다. 대신 claude.ai 계정과 함께Login method가 표시된다면 변수가 읽히지 않았으며 세션이 구독으로 실행되고 있는 것입니다.
이전에 구독으로 로그인한 적이 있다면 Claude Code가 시작할 때 두 개의 로그인 소스가 활성 상태라고 경고할 수 있습니다(메시지는 auth may not work as expected로 끝납니다). 이 경우 요청은 키를 통해 전송됩니다. /logout로 이전 로그인을 삭제할 수 있습니다.
Claude Code를 열기 전에 주소와 키를 테스트하고 싶다면 문서에서 제안하는 대로 출력 토큰 하나만 요청하세요. 아주 적은 잔액이 사용됩니다. 명령은 셸의 변수를 읽으므로 변수가 이미 settings.json에 있더라도 셸에도 설정해야 합니다.
curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
-Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json" `
-Body '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'{"id":"msg_로 시작하는 JSON 응답은 주소와 키가 작동한다는 뜻입니다. PowerShell에서는 id가 msg_로 시작하는 것을 볼 수 있습니다. 401는 키가 거부되었다는 뜻입니다.
API 키로 작동하는 기타 기능
- Remote Control과 음성 받아쓰기는 사용할 수 없습니다. 둘 다 claude.ai 계정이 필요하며
ANTHROPIC_AUTH_TOKEN가 활성 상태인 동안에는 사용할 수 없습니다. 또한ANTHROPIC_BASE_URL가 Anthropic 외부의 주소를 가리키는 동안 Remote Control은 비활성화됩니다. /fast는 fast mode가 꺼져 있다고 표시합니다. bearer 토큰만 사용하는 경우 Claude Code는 확인 요청을 보내지 않고 fast mode를 비활성화된 것으로 처리합니다.- MCP tool search는 기본적으로 꺼져 있습니다.
ANTHROPIC_BASE_URL가 Anthropic 외부의 주소를 가리키는 경우에 해당합니다. /context의 숫자는 근사치입니다: Kunavo biedt/v1/messages/count_tokensnu niet aan. Volgens de 공식 게이트웨이 호환성 문서 (gecontroleerd op 2026년 10월 3일) valt Claude Code zonder dat endpoint terug op een schatting op basis van tekens, dus/contexttoont benaderde aantallen.
코드, 도구, 하위 에이전트, MCP 서버, 훅 및 프롬프트 캐싱은 평소와 같이 작동합니다. 자세한 내용은 Claude Code 통합 문서(영어)와 Claude Code without a subscription(영어)을 참조하세요.
iDEAL 또는 Bancontact로 결제
Een Claude-abonnement betaal je via de website alleen met een creditcard of debitcard (유료 구독에 관한 Claude 도움말 문서, gecontroleerd op 2026년 10월 3일); de prijzen op claude.com/pricing zijn exclusief belasting.
Het Kunavo-tegoed waardeer je op via Stripe Checkout. De prijzen staan in Amerikaanse dollars; voor kopers in Nederland en België toont Stripe het bedrag in euro’s. Volgens de Adaptive Pricing에 관한 Stripe 문서 (gecontroleerd op 2026년 10월 3일) zit in die wisselkoers een omrekenopslag van 2–4% die de koper betaalt; wie in dollars betaalt (met een kaart, Apple Pay, Google Pay of Link), betaalt die opslag niet. iDEAL en Bancontact werken alleen in euro’s. Op de betaalpagina worden aangeboden:
- iDEAL, voor Nederland. De methode heet inmiddels iDEAL | Wero (Stripe vroeg om die naam in het eerste kwartaal van 2026 over te nemen), dus ook die naam kun je op de betaalpagina zien. Je wordt doorgestuurd naar de omgeving van je eigen bank en bevestigt daar (iDEAL에 대한 Stripe 설명, gecontroleerd op 2026년 10월 3일).
- Bancontact, voor België, met je Bancontact-kaart of de app (Bancontact에 대한 Stripe 설명, gecontroleerd op 2026년 10월 3일).
- 카드(Visa, Mastercard), Apple Pay, Google Pay 및 Link.
제공되지 않음: PayPal, SEPA 자동이체, Klarna(미국 구매자에게만 제공됨), Tikkie, Riverty(이전 AfterPay) 및 일반 은행 송금.
- Kunavo 계정을 만드세요.
- Billing에서 최소 $10의 금액을 선택하세요. 한 번에 더 많이 충전하면 추가 잔액을 받습니다: bij $100 krijg je $110, bij $1.000 krijg je $1.200, bij $5.000 krijg je $6.250.
- Stripe 결제 페이지에서 iDEAL 또는 Bancontact를 선택하고 은행 환경(iDEAL) 또는 Bancontact 앱이나 카드를 통해 결제를 완료하세요. 확인하기 전에 결제 페이지에서 유로 금액을 확인할 수 있습니다.
- /app/keys에서 키를 생성하고
ANTHROPIC_AUTH_TOKEN에 입력하세요.
잔액은 선불 방식입니다. 월 요금이 없고 잔액은 만료되지 않으며 실패한 요청에는 요금이 청구되지 않습니다. 자동 충전은 저장된 카드 또는 Link로만 가능합니다. 따라서 iDEAL과 Bancontact는 매번 수동으로 충전해야 합니다. Kunavo는 VAT 세금계산서를 발행하지 않으며 충전 내역은 Billing에 표시됩니다. 이러한 결제 수단은 Kunavo API 잔액만 충전하며 Claude Pro 또는 Max 구독 결제에는 사용할 수 없습니다. 유로 결제에 대한 자세한 내용은 Claude를 iDEAL로 결제하기를 참조하세요.
자주 발생하는 오류
| 표시되는 내용 | 원인 및 해결 방법 |
|---|---|
The token '&&' is not a valid statement separator | PowerShell에 CMD 명령줄을 붙여 넣었습니다. irm … | iex를 사용하세요. |
'irm' is not recognized as an internal or external command(또는 해당 메시지의 네덜란드어 버전) | PowerShell 명령줄을 CMD에 붙여 넣었습니다. install.cmd 줄을 사용하세요. |
'bash' is not recognized as the name of a cmdlet | macOS/Linux 명령줄을 Windows에 붙여 넣었습니다. PowerShell 줄을 사용하세요. |
| 명령이 스크립트 텍스트를 표시할 뿐 설치하지 않음 | 두 번째 부분이 누락되었습니다. PowerShell에서는 전체 줄 irm … | iex이고, CMD에서는 -o install.cmd가 포함된 전체 명령입니다. |
syntax error near unexpected token '<' 또는 403 | 다운로드에서 스크립트 대신 웹 페이지나 오류 코드가 반환되었습니다. 공식 문제 해결 문서에 따르면 네트워크 문제, 지역 라우팅, 일시적인 장애 또는 (내용 없는 403의 경우) 회사 프록시나 방화벽 때문일 수 있습니다. 몇 분 후 다시 시도하거나 macOS에서는 Homebrew, Windows에서는 WinGet을 통해 설치하세요. |
Claude Code does not support 32-bit Windows | Windows PowerShell(x86)을 열었습니다. 일반 Windows PowerShell을 여세요. |
npm.ps1 cannot be loaded | PowerShell의 실행 정책이 npm을 차단하고 있습니다. Set-ExecutionPolicy 줄을 실행하거나 네이티브 설치 프로그램을 사용하세요. |
command not found: claude 또는 claude를 찾을 수 없음 | 설치 디렉터리가 PATH에 없습니다. 새 창을 열고, Windows에서는 위의 PATH 부분을 사용하세요. |
| 키가 설정되어 있는데 로그인 화면이 표시됨 | Claude Code가 키를 읽지 못했습니다. 변수는 셸 또는 ~/.claude/settings.json에 설정하고 프로젝트 설정에만 설정하지 말고, 새 창을 여세요. |
auth may not work as expected로 끝나는 경고 | 키와 이전 로그인이 모두 활성 상태입니다. /logout를 사용해 키만 남기거나 변수를 제거해 로그인을 사용하세요. |
401 | 키를 인식할 수 없습니다. 전체 sk-kn- 키를 공백 없이 복사했는지, /app/keys에서 삭제되지 않았는지, 그리고 ANTHROPIC_AUTH_TOKEN에 있는지 확인하세요. |
404 | ANTHROPIC_BASE_URL가 /v1로 끝나거나 요청한 모델이 Kunavo에 없습니다(예: 네 개의 모델 변수가 누락된 경우). |
설치 후
프로젝트에서 처음 시작할 때 /init를 입력하세요. Claude Code가 저장소를 읽고 발견한 테스트 명령과 규칙이 담긴 CLAUDE.md을 생성합니다. 이 파일은 모든 세션에서 로드되므로 확인하고 짧게 유지하세요. 개별 작업 사이에는 /clear가 새 대화를 시작하며, 작업이 길어지면 /compact가 기록을 요약하고 계속 작업할 수 있게 합니다.
알아야 할 사항
- 이는 Claude Pro 또는 Max 구독이 아니라 토큰당 결제하는 API입니다. 매일 몇 시간씩 Claude Code를 사용하는 경우에는 구독이 더 저렴한 경우가 많고, 사용량이 일정하지 않다면 토큰당 결제가 적합하며 한 달 동안 사용하지 않으면 비용이 들지 않습니다. 비교 내용은 Claude Code pricing(영어)에 나와 있습니다.
- API 키를 사용하면 Remote Control과 음성 받아쓰기를 사용할 수 없습니다.
- Kunavo에서는 예약된 할당량이나 계약상 보장 없이 공유 용량을 사용합니다. 이러한 보장이 필요하다면 Anthropic과 직접 계약을 체결하세요.
- iDEAL과 Bancontact는 수동 충전에만 사용할 수 있으며, 자동 충전은 카드 또는 Link로만 가능합니다.
- 유로 금액에는 Stripe의 환전 수수료가 포함되어 있습니다. Kunavo는 VAT 세금계산서를 발행하지 않습니다.
자주 묻는 질문
Claude Code는 어떻게 설치하나요?
공식 명령 하나로 설치합니다. 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를 사용합니다. Anthropic이 권장하는 네이티브 설치 방식이며 백그라운드에서 자동으로 업데이트됩니다. 그런 다음 새 터미널 창을 열고 claude --version으로 확인한 뒤 claude로 시작하세요.
Windows에 Claude Code를 설치하려면 WSL 또는 관리자 권한이 필요한가요?
아니요. 공식 설치 문서에 따르면 창을 관리자로 열지 않고 PowerShell 또는 CMD에서 설치 명령을 실행하면 됩니다. Git for Windows는 선택 사항입니다. 설치되어 있으면 Claude Code가 Git Bash를 통해 명령을 실행하고, 그렇지 않으면 PowerShell을 사용합니다. Linux 도구나 샌드박싱이 필요한 경우에만 WSL 2를 선택하면 됩니다. 이 경우 WSL 터미널에서 Claude Code를 설치하고 시작하세요. Windows PowerShell(x86)은 열지 마세요. Claude Code는 32비트 Windows를 지원하지 않습니다.
Claude Code에 Node.js가 필요한가요?
npm으로 설치할 때만 필요하며, Node.js 22 이상이어야 합니다. 네이티브 설치 프로그램, Homebrew 및 WinGet에는 Node.js가 필요하지 않습니다. 이전 버전의 Node.js를 사용하면 npm은 EBADENGINE 경고만 표시하고 설치를 계속합니다. sudo npm install -g는 사용하지 말고, npm update -g 대신 npm install -g @anthropic-ai/claude-code@latest로 업데이트하세요.
구독 없이 Claude Code를 사용할 수 있나요?
예. 로그인하려면 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하며 무료 Claude.ai 구독에는 Claude Code가 포함되지 않습니다. 구독 없이 사용하려면 ANTHROPIC_BASE_URL=https://api.kunavo.com과 Kunavo 키가 포함된 ANTHROPIC_AUTH_TOKEN을 설정하세요. 그러면 Claude Code가 로그인 화면을 건너뛰고 선불 Kunavo 잔액에서 사용한 토큰만큼, $10부터 월 요금 없이 결제합니다. Remote Control과 음성 받아쓰기는 claude.ai 계정이 필요하므로 이 방식에서는 사용할 수 없습니다.
Claude Code용 API 키는 어떻게 설정하나요?
변수를 ~/.claude/settings.json의 env 블록(Windows에서는 %USERPROFILE%\.claude\settings.json)에 넣거나 ~/.zshrc, ~/.bashrc 또는 PowerShell의 $PROFILE에 export 줄로 추가하세요. ANTHROPIC_API_KEY가 아닌 ANTHROPIC_AUTH_TOKEN을 사용하세요. ANTHROPIC_AUTH_TOKEN은 Authorization: Bearer로 전달되어 즉시 적용되고, ANTHROPIC_API_KEY는 x-api-key 헤더에 들어가 먼저 한 번 승인해야 합니다. ANTHROPIC_BASE_URL은 /v1 없이 도메인 https://api.kunavo.com만 지정해야 합니다. Claude Code가 뒤에 /v1/messages를 자체적으로 추가하므로 /v1을 포함하면 /v1/v1/messages가 되어 404가 발생합니다. 키를 프로젝트의 .claude/settings.json에 절대 넣지 마세요. 해당 파일은 커밋되기 때문입니다. 셸과 설정 파일에서 같은 변수를 설정하면 설정 파일이 우선합니다.
API 키로 Claude Code를 사용할 때 모델 변수가 네 개인 이유는 무엇인가요?
고정 모델이 없으면 Claude Code는 Anthropic의 새 버전에 따라 바뀌는 별칭을 사용합니다. 공식 모델 구성 문서(2026년 10월 3일 기준)에 따르면 기본 설정과 API 사용자의 opus 별칭은 Opus 5.5를, sonnet 별칭은 Sonnet 5.5를 가리킵니다. Kunavo는 현재 Sonnet 5.5를 제공하지 않으며 존재하지 않는 모델은 404를 반환합니다. 따라서 고정된 sonnet 변수가 없으면 /model sonnet, opusplan의 실행 단계, model: sonnet을 사용하는 서브에이전트가 실패합니다. 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를 설정하면 각 요청이 Kunavo가 제공하는 모델을 요청하므로 비용도 알 수 있습니다. Opus 5.5에는 Claude Code v2.1.280 이상이 필요합니다. 이전 버전은 claude update로 업데이트하세요. haiku 변수는 Claude Code의 백그라운드 작업에 사용할 모델도 결정합니다.
Claude Code가 내 API 키를 사용하는지 어떻게 확인하나요?
Claude Code에서 /status를 입력하세요. Status 탭의 Anthropic base URL 줄에는 https://api.kunavo.com이 표시되고, Auth token 줄에는 ANTHROPIC_AUTH_TOKEN이 표시되어야 합니다. 대신 claude.ai 계정과 함께 Login method가 표시되면 변수를 읽지 못해 세션이 구독으로 실행되고 있는 것입니다. 시작할 때 로그인 화면이 표시되면 Claude Code가 키를 전혀 읽지 못한 것입니다.
iDEAL 또는 Bancontact로 Claude Code 비용을 결제할 수 있나요?
Kunavo API 잔액은 가능합니다. Stripe 결제 페이지에서는 카드, Apple Pay, Google Pay 및 Link와 함께 iDEAL(네덜란드)과 Bancontact(벨기에)를 제공합니다. 가격은 달러로 표시되며 Stripe는 금액을 유로로 보여 줍니다. Stripe에 따르면 환율에는 2~4%의 환전 수수료가 포함됩니다. 최소 금액은 $10이고 월 요금은 없으며 잔액은 만료되지 않습니다. iDEAL과 Bancontact는 수동 충전에서만 사용할 수 있고 자동 충전은 저장된 카드 또는 Link로만 가능합니다. PayPal과 SEPA 자동이체는 제공되지 않으며 Kunavo는 VAT 세금계산서를 발행하지 않습니다. Claude Pro 또는 Max 구독은 여기서 결제할 수 없습니다. claude.ai 웹사이트에서 신용카드 또는 직불카드로만 결제합니다.