가이드 목록으로
설치·2026년 10월 3일·14분 분량

Windows, Mac 및 Linux에 Claude Code 설치: 구독 없이 API 키 사용 및 Satispay 결제

설치는 명령 하나로 끝납니다. 문제는 그다음에 발생합니다. npm의 Node.js 버전, Windows의 터미널과 PATH, 로그인 없이 API 키를 사용하는 방법 및 신용카드 없이 이탈리아에서 결제하는 방법을 다룹니다.

Claude Code는 터미널에 따라 다른 한 가지 명령으로 설치합니다. macOS, Linux 및 WSL에서는 install.sh가 포함된 줄을, PowerShell에서는 irm … | iex를, 명령 프롬프트에서는 install.cmd가 포함된 줄을 사용합니다. Anthropic이 권장하는 방법이며 npm도 사용할 수 있지만 Node.js 22 이상이 필요합니다. Claude 무료 요금제에는 Claude Code가 포함되지 않으므로 Pro 이상 구독 또는 API 키가 필요합니다. 여기서는 두 번째 방법을 따릅니다: ANTHROPIC_BASE_URL=https://api.kunavo.com(/v1 제외), ANTHROPIC_AUTH_TOKEN에 키 입력, 모델을 고정하는 네 가지 변수 및 최종 확인을 위한 /status입니다. 크레딧은 $10부터 유로로 충전하며 사용한 토큰만 결제합니다.

Terminale
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
PowerShell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
cmd.exe
:: Windows – Prompt dei comandi (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Da dove vengono questi comandi: la documentazione di Claude Code esiste anche in italiano e l'abbiamo riletta il 2026년 10월 3일, in particolare le pagine su 설치 e LLM 게이트웨이. Prezzi e metodi di pagamento di Kunavo sono aggiornati al 2026년 10월 3일. Anthropic serve l'Italia sia su Claude.ai sia con l'API (지원 국가, letto il 2026년 10월 3일).

필요 사항

I requisiti della 공식 문서 (letta il 2026년 10월 3일) sono bassi:

  • 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이 지원하는 국가에서의 연결: 이탈리아는 지원됩니다.
  • npm을 선택하는 경우에만 Node.js가 필요하며, 이 경우 버전 22 이상이어야 합니다.

어떤 터미널에서 어떤 명령을 실행할까요?

실행 위치식별 방법붙여넣을 줄
macOS, Linux, WSL터미널, iTerm 또는 WSL 셸curl … install.sh | bash
Windows PowerShell프롬프트는 PS C:\Users\nome>로 시작합니다.irm … install.ps1 | iex
Windows, 명령 프롬프트프롬프트에는 C:\Users\nome>만 표시되고 PS는 표시되지 않습니다.install.cmd가 포함된 줄

관리자 권한이나 WSL은 필요하지 않습니다. 공식 문서에 명시되어 있으며, 여러 가이드에서 반대로 안내하더라도 마찬가지입니다. 설치가 완료되면 Claude Code가 백그라운드에서 자동으로 업데이트됩니다. 패키지 관리자를 선호한다면 Homebrew 또는 WinGet을 사용할 수 있지만, 이 경우 업데이트는 직접 실행해야 합니다:

# Homebrew – canale stable; non si aggiorna da solo
brew install --cask claude-code

# WinGet (Windows) – non si aggiorna da solo
winget install Anthropic.ClaudeCode

시도하기 전에 터미널을 닫고 새 터미널을 여세요. 새 창만 PATH를 다시 읽습니다. 그런 다음 확인하세요. claude doctor는 나중에도 유용합니다. 세션을 열지 않고 설치와 설정을 확인하여 문제가 설치에 있는지 설정에 있는지 즉시 알려줍니다.

claude --version   # stampa la versione, ad esempio 2.1.284 (Claude Code)
claude doctor      # diagnostica di installazione e impostazioni, senza aprire una sessione

다운로드 차단됨: 스크립트 대신 403 또는 HTML 페이지가 표시됨

Quando lo script non arriva, il terminale non lo dice in modo chiaro: bash si lamenta con syntax error near unexpected token '<' (sta cercando di eseguire una pagina web), oppure curl si ferma su curl: (22) The requested URL returned error: 403. La 설치 문제에 대한 공식 페이지 (in inglese, letta il 2026년 10월 3일) distingue due casi. Se la pagina scaricata dice App unavailable in region, il server crede che ti colleghi da un paese escluso: dall'Italia capita quasi sempre per una VPN o un proxy che esce all'estero. Un 403 senza testo arriva più spesso da un proxy aziendale o da un firewall. Cambiare metodo di installazione non aiuta, perché Homebrew e WinGet scaricano dagli stessi server: prova da un'altra rete oppure chiedi all'IT di sbloccare quei domini.

npm 사용 시: Node.js 22, 18이 아님

Se Node.js lo usi già tutti i giorni, npm sembra la scelta naturale. Funziona ed è tra i metodi documentati, con una condizione che molte guide in italiano non hanno aggiornato: ci vuole Node.js 22 o successivo. Con un Node più vecchio vedrai l'avviso EBADENGINE, però l'installazione arriva in fondo e claude parte lo stesso (공식 문서, letta il 2026년 10월 3일). Le versioni aggiornate di Node sono su nodejs.org.

Terminale
node -v                                    # serve v22 o successiva
npm install -g @anthropic-ai/claude-code   # senza sudo

# aggiornamento: @latest, non npm update -g
npm install -g @anthropic-ai/claude-code@latest

피해야 할 세 가지 습관:

  • sudo를 npm install -g 앞에 사용하기. 문서에서는 권한 충돌과 보안 문제 때문에 이를 권장하지 않습니다.
  • npm update -g로 업데이트하기. 대신 위의 마지막 줄과 같이 @latest를 사용해 설치를 반복하세요.
  • 선택적 종속성 건너뛰기. Il binario di Claude Code arriva proprio come dipendenza facoltativa, un pacchetto @anthropic-ai/claude-code-* per ogni piattaforma. Con --omit=optional, o con optional=false nel file .npmrc, non viene scaricato e su macOS o Linux claude risponde claude native binary not installed (설치 문제, in inglese, letta il 2026년 10월 3일).

Windows에서 Claude Code가 막히는 지점

Su Windows Claude Code gira in modo nativo, e l'installazione in sé è la parte facile. I problemi nascono dall'ambiente. Il primo è il terminale: se incolli in PowerShell la riga per CMD, PowerShell protesta per il &&; se incolli in CMD la riga per PowerShell, CMD non sa cosa sia irm; e la riga curl … | bash del Mac in PowerShell non funziona proprio. Su un Windows in italiano alcuni di questi messaggi possono comparire tradotti. In ogni caso la soluzione è tornare alla tabella qui sopra e prendere la riga del terminale che hai davanti (i messaggi in inglese sono nella tabella degli errori in fondo; fonte: 문서, letta il 2026년 10월 3일).

시작 메뉴도 주의하세요. “Windows PowerShell (x86)”은 32비트 프로세스를 열기 때문에 PC가 64비트여도 Claude Code가 Claude Code does not support 32-bit Windows와 함께 중지됩니다. (x86)이 없는 항목을 선택하세요.

Git for Windows non è obbligatorio. Se è installato, Claude Code esegue i comandi attraverso Git Bash; se manca, usa PowerShell. Quando Git c'è ma Claude Code non trova bash.exe, indicagli il percorso con CLAUDE_CODE_GIT_BASH_PATH nel blocco env di ~/.claude/settings.json, di solito C:\Program Files\Git\bin\bash.exe. E WSL? Serve solo in un caso preciso:

Claude Code 실행 환경사전 요구 사항명령 샌드박스다음과 같은 경우 유용함
Windows 네이티브없음(Git for Windows는 선택 사항)아니요프로젝트와 도구가 Windows에 있음
WSL 2WSL 2 설치됨예Linux 도구를 사용하거나 명령을 격리하고 싶음
WSL 1WSL 1 설치됨아니요컴퓨터에서 WSL 2를 사용할 수 없음

WSL에서는 모든 작업이 Linux 내부에서 이루어집니다. install.sh 줄은 WSL 셸에서 실행하고, 그곳에서 claude를 시작합니다.

“claude”를 찾을 수 없음

설치 후 터미널에서 command not found: claude 또는 'claude' is not recognized라고 응답하면 프로그램은 있지만 해당 폴더가 PATH에 포함되지 않은 것입니다. 기본 설치 프로그램은 macOS와 Linux에서는 ~/.local/bin/claude에, Windows에서는 %USERPROFILE%\.local\bin\claude.exe에 복사합니다. 먼저 새 터미널을 열어 보세요. Windows에서 충분하지 않다면 다음은 폴더를 확인하고 사용자의 PATH에 추가하기 위한 문서의 PowerShell 명령입니다:

PowerShell
# 1. Controlla se la cartella di installazione è già nel PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Nessun risultato? Aggiungila al PATH utente, poi chiudi e riapri il terminale
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Nel nuovo terminale
claude --version

PowerShell에서 npm.ps1 cannot be loaded

npm으로 설치한 경우에만 해당합니다. PowerShell의 실행 정책이 npm이 생성하는 .ps1 스크립트를 차단하며, 전체 메시지에는 running scripts is disabled on this system가 포함됩니다. 문서에서는 세 가지 해결 방법을 제시합니다. 아래 명령으로 현재 사용자가 로컬 스크립트를 실행하도록 허용하거나, PowerShell 스크립트 대신 npm.cmd와 claude.cmd를 실행하거나, npm을 포기하고 기본 설치 프로그램을 사용하는 방법입니다.

PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

구독 없이 사용하기: Claude 계정 또는 API 키

Installato non vuol dire pronto: al primo avvio Claude Code chiede di autenticarsi, e il piano gratuito di Claude.ai non basta (문서, letta il 2026년 10월 3일). Le due strade a confronto:

Claude 구독Kunavo API 키
요구 사항Pro, Max, Team 또는 Enterprise 요금제나 Console 계정 및 로그인환경 변수에 입력한 sk-kn-… 키, 로그인 없음
비용Pro $20 al mese, oppure $17 al mese con il pagamento annuale ($200 in anticipo); Max da $100 al mese; tasse escluse (Claude 가격, letti il 2026년 10월 3일)사용량 기준 토큰별 과금, 선불 크레딧에서 $10 충전, 월 이용료 없음, 만료 없음
결제 방법Sul web solo carta di credito o di debito (Anthropic 지원); PayPal non è accettato (Anthropic 지원), entrambi letti il 2026년 10월 3일유로 결제 화면의 Satispay, Visa 및 Mastercard 카드, Apple Pay, Google Pay, Link
사용할 수 없는 기능—Remote Control 및 음성 받아쓰기, 청구서 없음

Esiste anche la chiave della Console di Anthropic, sempre a consumo. Lì però i crediti prepagati scadono dopo un anno e non si rimborsano (Anthropic 지원, letto il 2026년 10월 3일); si paga con carta, mentre il bonifico ACH è riservato agli account API con fatturazione mensile (Anthropic 지원). Il credito Kunavo non ha scadenza.

API 키 설정: 여섯 가지 변수

Che Claude Code parli con un endpoint diverso da quello di Anthropic è previsto: la documentazione ufficiale ha una pagina, tradotta anche in italiano, su come LLM 게이트웨이에 연결하기. Nessun plugin, nessuna versione modificata. Bastano queste variabili:

변수값용도
ANTHROPIC_BASE_URLhttps://api.kunavo.com서비스 주소입니다. 도메인만 입력하세요. Claude Code가 /v1/messages를 추가하므로 끝에 /v1를 입력하면 요청이 /v1/v1/messages로 전송되어 404가 됩니다.
ANTHROPIC_AUTH_TOKEN내 sk-kn-… 키Authorization: Bearer로 전송되며 확인 없이 즉시 적용됩니다.
ANTHROPIC_MODELclaude-sonnet-5주요 모델이며 여기서는 Claude Sonnet 5입니다. 이름은 Kunavo 목록에 표시된 그대로 정확히 입력해야 합니다. 끝에 날짜가 붙은 이전 버전은 인식되지 않습니다.
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5-5opus 별칭 및 Plan Mode의 opusplan 뒤에서 사용되는 모델이며, 여기서는 Claude Opus 5.5입니다. Claude Code 2.1.280 이상이 필요합니다. 이전 버전이라면 claude update를 실행하세요.
ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-5sonnet 별칭, Plan Mode 외부의 opusplan 및 model: sonnet를 사용하는 서브에이전트가 사용하는 모델입니다. 이 줄이 없으면 별칭이 Kunavo에서 제공하지 않는 Sonnet 5.5를 요청합니다.
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5haiku 별칭과 Claude Code가 백그라운드에서 자동으로 실행하는 기능이 사용하는 모델입니다.

macOS와 Linux에서는 ~/.zshrc 또는 ~/.bashrc의 마지막에 추가합니다:

~/.zshrc
export ANTHROPIC_BASE_URL=https://api.kunavo.com   # solo il dominio, senza /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
# Vale solo in questa finestra di PowerShell: chiusa la finestra, sparisce
$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(Windows에서는 %USERPROFILE%\.claude\settings.json)의 env 블록에 추가하세요. 모든 프로젝트에 적용됩니다. 파일에 다른 설정이 이미 있으면 env만 추가합니다:

~/.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"
  }
}

AUTH_TOKEN 또는 API_KEY?

Kunavo legge la chiave da tutti e due gli header, Authorization: Bearer e x-api-key, quindi in teoria vanno bene entrambe le variabili. La differenza la fa Claude Code. Con ANTHROPIC_API_KEY, inviata come x-api-key, la sessione interattiva ti chiede una volta se approvare la chiave; se rispondi no, la ignora senza dire nulla finché non la riattivi da /config → 사용자 지정 API 키 사용. ANTHROPIC_AUTH_TOKEN non chiede niente, ed è anche la variabile che la 게이트웨이에 대한 문서 (letta il 2026년 10월 3일) suggerisce quando non sai quale scegliere.

모델을 고정하는 이유

Senza variabili Claude Code ragiona per alias, e gli alias seguono le uscite di Anthropic. Oggi, secondo la 모델 구성 문서 (letta il 2026년 10월 3일), per chi usa l'API opus corrisponde a Opus 5.5 e sonnet a Sonnet 5.5. Kunavo, al 2026년 10월 3일, non offre Sonnet 5.5: senza ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la fase esecutiva di opusplan e i subagent con model: sonnet chiederebbero un modello che su Kunavo non c'è e tornerebbero 404. Con claude-sonnet-5 in quella variabile l'alias punta a Claude Sonnet 5, lo stesso modello di ANTHROPIC_MODEL. Quest'ultima decide invece il modello della sessione: senza, Claude Code partirebbe dal suo predefinito, oggi Opus 5.5. Opus 5.5 è disponibile, e fissare opus su claude-opus-5-5 serve a un'altra cosa: evitare che modello e tariffa cambino da un giorno all'altro quando l'alias passerà a un Opus successivo. Claude Opus 5.5 richiede Claude Code 2.1.280 o successivo; con una versione più vecchia, lancia prima claude update.

설정에 사용된 세 모델의 Kunavo 요금(토큰 100만 개당, 입력 / 출력): Claude Sonnet 5 $1,40 / $7,00 (Anthropic 가격표: $2,00 / $10,00); Claude Opus 5.5 $2,80 / $14,00; 백그라운드에서도 작동하는 Claude Haiku 4.5 $0,70 / $3,50.

키를 입력하지 말아야 할 위치와 우선 적용되는 설정

Il .claude/settings.json dentro il progetto viene committato: una chiave scritta lì finisce nel repository e arriva a chiunque lo cloni (게이트웨이에 대한 문서). Se una variabile compare sia nella shell sia nel blocco env di un file di impostazioni, prevale il file: quando una modifica a ~/.zshrc sembra ignorata, il motivo è quasi sempre lì. Il campo model del file di impostazioni, invece, cede il passo ad ANTHROPIC_MODEL. Nell'estensione di Claude Code per VS Code le stesse variabili vanno in claudeCode.environmentVariables, nelle impostazioni utente di VS Code. L'app desktop di Claude resta fuori da tutto questo: non legge né ANTHROPIC_BASE_URL né settings.json (게이트웨이에 대한 문서, letta il 2026년 10월 3일).

첫 실행 및 /status로 확인

Se la chiave è al suo posto, claude parte 로그인 화면 없이: restano solo la configurazione iniziale e la domanda se ti fidi della cartella. Se invece compare il login, Claude Code non ha trovato la chiave. Il caso tipico è la chiave scritta solo nel .claude/settings.json o nel .claude/settings.local.json del progetto: in modalità interattiva quel blocco env entra in gioco solo dopo la configurazione iniziale e la conferma di fiducia (게이트웨이에 대한 문서, letta il 2026년 10월 3일), quindi al primo avvio non c'è ancora. Spostala nella shell o nel file utente. Un vecchio login Pro o Max non dà fastidio, perché la variabile ha la precedenza sull'accesso salvato; se vuoi cancellarlo, c'è /logout.

세션에서 /status를 입력하세요. 중요한 줄은 두 개입니다:

  • 게이트웨이가 설정된 경우에만 표시되는 Anthropic base URL는 https://api.kunavo.com이어야 합니다. 표시되지 않으면 ANTHROPIC_BASE_URL가 세션에 전달되지 않은 것입니다.
  • Auth token 이름이 ANTHROPIC_AUTH_TOKEN인 경우 키를 사용하고 있는 것입니다. 대신 claude.ai 계정과 함께 Login method가 표시된다면 변수가 무시된 것입니다.

Claude Code를 열기 전에 먼저 확인하고 싶으신가요? 문서에서는 출력 토큰 1개를 사용하는 최소 요청을 제시하며, 크레딧에서 차감되는 금액은 무시할 수 있을 정도로 적습니다. 이 명령은 현재 셸의 변수를 읽습니다. 키가 settings.json에만 있다면 먼저 이 터미널로 내보내세요. {"id":"msg_로 시작하는 JSON이 반환되면 정상이며, 401는 키가 거부되었다는 뜻입니다.

Terminale
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": "."}]}'

PowerShell에서는 다음과 같이 테스트하며, 정상 응답에는 id가 포함되고 그 값은 msg_로 시작합니다:

PowerShell
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": "."}]}'

API 키를 사용하면 잃는 것

  • Remote Control과 음성 받아쓰기. 이 기능에는 claude.ai ID가 필요하며 ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY와 함께 작동하지 않습니다. 또한 버전 2.1.196부터는 ANTHROPIC_BASE_URL가 Anthropic이 아닌 호스트를 가리킬 때 Remote Control도 비활성화됩니다.
  • /fast 모드. Claude Code는 bearer 토큰만 있으면 이를 비활성화된 것으로 간주하고 요청조차 시도하지 않습니다.
  • 처음의 MCP 도구 검색. Con un ANTHROPIC_BASE_URL personalizzato parte spenta (MCP 문서, in inglese, letta il 2026년 10월 3일). Si riaccende con ENABLE_TOOL_SEARCH=true se il gateway inoltra i blocchi tool_reference; con Kunavo non l'abbiamo provato.
  • /context의 정확성. Kunavo non espone /v1/messages/count_tokens, un endpoint facoltativo secondo la 게이트웨이 사양 (letta il 2026년 10월 3일); senza, Claude Code stima i token a partire dai caratteri.

자세한 내용은 영어로 제공되는 Claude Code 통합 문서, ANTHROPIC_BASE_URL의 예외 사례 페이지, Claude Code 설치 가이드를 참조하세요.

신용카드 없이 Satispay로 결제하기

Prima una precisazione, perché è la domanda più frequente: Satispay non paga l'abbonamento Claude. Per Pro e Max comprati sul web Anthropic accetta solo carte di credito o di debito (Anthropic 지원) e non accetta PayPal (Anthropic 지원), entrambi letti il 2026년 10월 3일. Su Kunavo Satispay ricarica invece il credito API che Claude Code consuma con la chiave configurata sopra. Tutti i dettagli, compresi i costi per caricare la Disponibilità, sono nella guida Satispay로 Claude 결제하기. Per Claude Code la sequenza è questa:

  1. 이메일 또는 Google 계정으로 Kunavo에 가입하세요. 카드가 필요하지 않습니다.
  2. 결제를 열고 충전할 금액을 선택하세요. 최소 금액은 $10이며 월정액은 없습니다. 특정 금액 이상에서는 보너스가 제공됩니다: 크레딧 $100 diventano $110, $1.000 diventano $1.200, $5.000 diventano $6.250.
  3. Nel checkout di Stripe, che mostra l'importo in euro, scegli Satispay. Si passa alla pagina di Satispay (Stripe 문서): numero di cellulare o QR code dall'app, poi conferma con 전송 (Satispay 고객지원, letto il 2026년 10월 3일). Meglio avere già abbastanza Disponibilità prima di cominciare.
  4. Stripe에서 결제를 확인하면 결제에 크레딧이 바로 표시됩니다. 즉시 보이지 않으면 다시 결제하지 말고 페이지를 새로 고침하세요. 두 번째 결제는 첫 번째 결제를 대체하지 않고 크레딧에 더해집니다.
  5. API 키에서 키 sk-kn-…를 생성하고 즉시 ANTHROPIC_AUTH_TOKEN에 복사하세요. 한 번만 표시됩니다.
방법Kunavo의 유로 결제 화면에서
Satispay제공됨 (아래 참고 사항 참조)
Visa 및 Mastercard 카드예, 온라인 구매가 활성화된 직불카드와 선불카드도 가능합니다
Apple Pay, Google Pay예, 호환되는 기기에서 가능합니다
Link예
Pay by BankNo, non dall'Italia: Stripe lo offre solo a chi paga dal Regno Unito (in sterline), dall'Irlanda e dalla Finlandia; in Francia e Germania è in anteprima privata (Stripe, Pay by Bank, letto il 2026년 10월 3일)
PayPal, SEPA 자동이체아니요
Klarna아니요. 달러로도 불가능합니다. Stripe는 미국에서 결제하는 사용자에게만 이를 제공합니다

Kunavo fissa i prezzi in dollari e Stripe li converte in euro con una 2~4% 환전 수수료 a carico di chi paga (Stripe, Adaptive Pricing, letto il 2026년 10월 3일): sulla ricarica minima da $10 sono tra $0,20 e $0,40. In dollari la commissione sparisce, ma sparisce anche Satispay, che esiste solo nel checkout in euro; se il checkout ti appare in dollari, spesso c'entra una VPN. L'importo esatto in euro è quello che leggi nel checkout prima di confermare.

Con Satispay le ricariche si fanno a mano: la ricarica automatica di Kunavo addebita solo una carta salvata o Link. Chi ha la carta Satispay, una Mastercard di debito per i piani Plus, Metal e Velvet (Satispay 고객지원, letto il 2026년 10월 3일), può salvarla e usarla come qualsiasi carta. Il credito non scade e le richieste fallite non vengono addebitate. Kunavo non emette fatture, né con IVA né elettroniche via SDI; lo storico delle ricariche resta in 결제.

솔직히 말씀드리면 Satispay는 2026년 10월 3일부터 Kunavo 결제 화면에 표시되며 Stripe는 유로 결제에서 이를 제공하지만, 아직 이를 통한 충전은 한 건도 처리되지 않았습니다. 표시되지 않는다면 카드, Apple Pay, Google Pay 또는 Link를 사용하면 동일하게 처리할 수 있습니다.

작업 세션 비용

API 키를 사용하면 비용은 토큰으로 계산되며 Claude Code는 많은 토큰을 보냅니다. 각 단계마다 전체 컨텍스트를 다시 전송하기 때문입니다. 하지만 변경되지 않는 부분은 훨씬 낮은 요금으로 캐시에서 읽을 수 있습니다. 다음은 가정을 명확히 밝힌 계산 예시입니다. 실제 측정값도 아니고 지출 한도도 아닙니다.

  • 요청당 입력 토큰 40.000개. 그중 36.000개(90%)는 캐시에서 읽고 4.000개는 캐시에 기록합니다;
  • 요청당 출력 토큰 1.000개;
  • 세션당 요청 50회이며, 백그라운드에서 실행되는 Claude Haiku 4.5 호출은 포함하지 않습니다;
  • 입력 요금의 10%에 해당하는 캐시 읽기와 입력 요금의 1,25배에 해당하는 캐시 쓰기입니다. 이는 Claude Sonnet 5에 대한 Kunavo의 비율이며, 표의 각 행은 해당 모델의 비율을 사용합니다.
모델요청 1회요청 50회캐시 없이 요청 50회
Claude Sonnet 5$0,019$0,95$3,15
Claude Opus 5.5$0,033$1,65$6,30

컨텍스트가 길고 캐시에서 읽는 양이 적으며 응답이 장황할수록 비용이 증가하고, 작업 사이에 /clear를 실행하면 비용이 줄어듭니다. 구독과 API 중 어느 쪽이 더 유리한지는 Claude Code 비용에서 확인할 수 있습니다. 모든 Claude 모델의 요금은 Claude API 가격 및 가격 페이지에 있습니다. 자신의 수치로 다시 계산하려면 Claude 토큰 비용 계산기(영어)를 사용하세요.

오류: 메시지, 원인, 해결 방법

표시되는 내용의미와 조치
The token '&&' is not a valid statement separatorCMD용 줄을 PowerShell에서 실행했습니다. irm … | iex를 사용하세요.
'irm' is not recognized as an internal or external commandPowerShell용 줄을 CMD에서 실행했습니다. install.cmd가 포함된 줄을 사용하세요.
A parameter cannot be found that matches parameter name 'fsSL', 'bash' is not recognized as the name of a cmdletWindows에서 macOS 및 Linux용 명령을 붙여 넣었습니다. PowerShell용 줄을 사용하세요.
syntax error near unexpected token '<', 403, App unavailable in region스크립트 대신 HTML 페이지나 오류가 반환되었습니다. VPN 또는 프록시를 끄거나 다른 네트워크를 사용해 보세요. Homebrew와 WinGet은 동일한 서버를 통해 연결됩니다.
command not found: claude, 'claude' is not recognized프로그램 폴더가 PATH에 없습니다. 새 터미널을 여세요. Windows에서는 PATH 관련 섹션의 PowerShell 명령을 사용하세요.
EBADENGINE 경고Node.js가 22보다 낮습니다. 설치는 완료되지만 가능한 한 빨리 Node를 업데이트하세요.
claude native binary not installed (macOS, Linux)npm이 선택적 종속성(--omit=optional, optional=false) 또는 설치 스크립트(--ignore-scripts)를 건너뛰었습니다. 해당 옵션을 제거하고 다시 설치하세요.
npm.ps1 cannot be loadedPowerShell의 실행 정책이 npm 스크립트를 차단합니다. 현재 사용자에 대해 Set-ExecutionPolicy를 실행하거나 네이티브 설치 프로그램을 사용하세요.
Claude Code does not support 32-bit Windows“Windows PowerShell (x86)”에 있습니다. (x86)이 없는 항목을 여세요.
키를 설정했는데도 로그인 화면이 표시됨키를 읽지 못했습니다. 프로젝트 설정에만 두지 말고 셸 또는 ~/.claude/settings.json에 입력한 다음 터미널을 다시 여세요.
401키가 거부되었습니다. sk-kn-… 전체가 공백 없이 복사되었고, /app/keys에서 아직 활성 상태이며, ANTHROPIC_AUTH_TOKEN에 들어 있는지 확인하세요.
404ANTHROPIC_BASE_URL가 /v1로 끝나거나, 요청한 모델이 Kunavo의 모델 목록에 없습니다. 일반적으로 모델을 지정하는 변수가 누락되었기 때문입니다.
결제 화면에 Satispay가 표시되지 않음VPN 또는 해외 프록시 때문에 결제 화면이 달러로 표시되는 경우가 많습니다. 이를 비활성화하고 결제에서 결제 화면을 다시 여세요.

이 구성이 하지 않는 일

  • Claude Pro 또는 Max 구독을 활성화하지 않습니다. Kunavo 크레딧은 API와 키를 사용하는 Claude Code에만 사용되며, claude.ai나 Claude 앱에는 사용할 수 없습니다.
  • 청구서를 발행하지 않습니다. VAT 청구서도 SDI를 통한 전자 청구서도 발행하지 않습니다.
  • Satispay로 자동 충전하지 않습니다. 자동 충전에는 저장된 카드 또는 Link가 필요합니다.
  • Kunavo가 Sonnet 5.5를 제공할 때까지 모델 변수가 없으면 작동하지 않습니다(2026년 10월 3일 기준). 별칭 sonnet는 404를 반환하며, /model sonnet, opusplan의 실행 단계 및 model: sonnet를 사용하는 서브에이전트도 마찬가지입니다.
  • Kunavo의 이탈리아어 문서는 제공되지 않습니다. 통합 가이드와 잔액 및 결제 페이지는 영어이며, Claude Code에 대한 Anthropic 문서는 번역되어 있습니다.

이탈리아에서 Claude를 사용해 개발하는 사람들을 위한 전반적인 내용은 이탈리아에서 Claude API 사용하기 가이드를 참조하세요. 시작하려면 계정을 만들고, Satispay로 $10를 충전하고, 6개의 변수를 설정한 뒤 /status로 확인하세요.

자주 묻는 질문

Windows, Mac 및 Linux에 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를 실행합니다. 이는 Anthropic 문서에서 권장하는 기본 설치 프로그램이며 자동으로 업데이트됩니다. 설치가 끝나면 새 터미널을 열고 claude --version을 입력하세요. Homebrew와 WinGet도 작동하지만 업데이트는 직접 관리해야 합니다.

Windows에 Claude Code를 설치하려면 WSL 또는 관리자 권한이 필요한가요?

둘 다 필요하지 않습니다. Claude Code는 Windows 10 1809 이상에서 기본적으로 실행되며, 공식 문서에서도 관리자 터미널이 필요하지 않다고 명시합니다. Linux 도구를 사용하거나 Windows 기본 환경과 WSL 1에는 없는 명령 샌드박스가 필요한 경우에만 WSL 2를 사용하면 됩니다. Git for Windows는 선택 사항입니다. 설치되어 있으면 Claude Code는 Git Bash를 사용하고, 그렇지 않으면 PowerShell을 사용합니다. “Windows PowerShell (x86)”은 32비트이므로 피하세요. Claude Code가 실행되지 않습니다.

npm으로 Claude Code를 설치할 때 Node 18이 필요한가요, 아니면 Node 22가 필요한가요?

Node.js 22 이상입니다(설치 공식 문서를 2026년 10월 3일에 확인). 일부 가이드에 나오는 18은 오래된 요구 사항입니다. 더 오래된 Node를 사용하면 EBADENGINE 경고가 표시되지만 설치는 완료되고 claude도 작동합니다. 명령은 npm install -g @anthropic-ai/claude-code이며 sudo는 사용하지 않습니다. 업데이트하려면 npm update -g 대신 @latest를 사용해 설치를 반복하세요. 기본 설치 프로그램을 사용한다면 Node.js가 전혀 필요하지 않습니다.

Claude Code는 무료인가요? 구독 없이 사용할 수 있나요?

무료는 아닙니다. Claude.ai 무료 요금제에는 Claude Code가 포함되지 않으며 로그인하려면 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 하지만 구독 없이 API 키를 사용해 실행할 수 있습니다. ANTHROPIC_BASE_URL=https://api.kunavo.com과 ANTHROPIC_AUTH_TOKEN을 설정하면 Claude Code가 로그인을 건너뛰고 토큰 비용이 선불 Kunavo 크레딧에서 차감됩니다. 월 이용료는 없으며 최소 충전 금액은 $10입니다. claude.ai 계정이 필요한 Remote Control과 음성 받아쓰기는 사용할 수 없습니다.

Claude Code에서 API 키는 어디에 입력하나요?

메뉴가 아니라 환경 변수에 입력합니다. 가장 편리한 위치는 모든 프로젝트에 적용되는 ~/.claude/settings.json의 env 블록입니다(Windows에서는 %USERPROFILE%\.claude\settings.json). 또는 ~/.zshrc, ~/.bashrc 또는 PowerShell 프로필을 사용할 수 있습니다. ANTHROPIC_AUTH_TOKEN을 사용하세요. Kunavo는 ANTHROPIC_API_KEY도 지원하지만 이 변수를 사용하면 Claude Code가 승인을 요청하며, 거부하면 /config에서 다시 활성화할 때까지 무시합니다. 프로젝트의 .claude/settings.json에는 절대 입력하지 마세요. 저장소에 포함될 수 있습니다.

Claude Code가 내 계정이 아니라 API 키를 사용하고 있는지 어떻게 알 수 있나요?

세션을 열고 /status를 입력하세요. “Anthropic base URL” 줄에 https://api.kunavo.com이, “Auth token” 줄에 ANTHROPIC_AUTH_TOKEN이 표시되어야 합니다. “Login method”에 claude.ai 계정이 표시되면 변수가 세션에 전달되지 않은 것입니다. 터미널을 닫고 새 터미널을 연 다음 변수를 어디에 입력했는지 확인하세요. 이전 Pro 또는 Max 로그인은 변수에 우선순위가 있으므로 영향을 주지 않습니다. 제거하려면 /logout을 사용하세요.

ANTHROPIC_BASE_URL을 사용하면 Claude Code가 404를 반환하는 이유는 무엇인가요?

일반적으로 두 가지 이유가 있습니다. 첫 번째는 끝에 /v1을 붙인 주소입니다. Claude Code가 이미 /v1/messages를 추가하므로 요청이 /v1/v1/messages로 전송됩니다. https://api.kunavo.com만 입력하세요. 두 번째는 모델입니다. 변수가 없으면 Claude Code가 별칭을 사용하며, API 사용자의 경우 sonnet 별칭은 현재 Kunavo가 제공하지 않는 Sonnet 5.5를 가리킵니다(모델 문서를 2026년 10월 3일에 확인). 따라서 /model sonnet, opusplan의 실행 단계 및 model: sonnet을 사용하는 서브에이전트는 404가 됩니다. 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를 설정하면 모든 요청이 사용 가능한 모델로 전송되며 적용 요금도 알 수 있습니다. Opus 5.5에는 Claude Code 2.1.280 이상이 필요합니다. 이전 버전이라면 claude update를 실행하세요.

Satispay로 Claude Code 비용을 결제할 수 있나요? PayPal은요?

Satispay는 가능하지만 API 크레딧에만 해당하며 구독에는 사용할 수 없습니다. Kunavo에서는 Stripe의 유로 결제 화면에 Satispay가 표시되며 Claude Code가 토큰 비용을 차감하는 잔액을 충전할 수 있습니다. 최소 금액은 $10이고 환전 수수료 2–4%는 결제자가 부담합니다. Satispay 충전은 수동으로 진행해야 합니다. Kunavo의 자동 충전은 저장된 카드(Satispay 카드도 가능하며 Plus, Metal 및 Velvet 요금제의 Mastercard 직불카드) 또는 Link를 사용할 때만 작동합니다. PayPal은 Kunavo와 Anthropic 모두에서 사용할 수 없습니다. Anthropic은 웹에서 Pro 및 Max에 대해 신용카드 또는 직불카드만 받습니다. Kunavo는 부가가치세 청구서나 SDI를 통한 전자 청구서를 발행하지 않습니다.