Claude Code 설치: Windows, macOS 및 Linux, 구독 없는 API 키 및 Bancontact 결제

Claude Code를 설치하는 데는 한 줄이면 충분하지만 환경마다 다릅니다. macOS, Linux 또는 WSL 터미널에서는 curl -fsSL https://claude.ai/install.sh | bash, PowerShell에서는 irm https://claude.ai/install.ps1 | iex, Windows 명령 프롬프트에서는 install.cmd 줄을 사용합니다. 첫 실행 시 진짜 질문은 요청 비용을 누가 부담하느냐입니다. Pro, Max, Team, Enterprise 또는 Console 계정으로 로그인할 수 있습니다(Claude.ai 무료 요금제에는 Claude Code가 포함되지 않음). 구독이 없어도 API 키만 있으면 됩니다. ANTHROPIC_BASE_URL는 /v1 없이 설정하고 ANTHROPIC_AUTH_TOKEN를 포함한 여섯 개 변수를 설정한 다음 /status를 확인하세요. Kunavo 잔액은 카드, Apple Pay, Google Pay, Link 또는 벨기에에서는 Bancontact로 충전할 수 있으며, $10부터 시작하고 구독이 없습니다.

D’où viennent les informations : les commandes et les variables sont reprises de la documentation officielle de Claude Code (설치, 환경 변수, Gateway 연결), relue le 2026년 10월 3일 ; les prix Kunavo et les moyens de paiement ont été contrôlés le 2026년 10월 3일. D’après la Anthropic 지원 국가 목록 (lue le 2026년 10월 3일), Claude.ai et l’API sont ouverts en France, en Belgique, en Suisse, au Luxembourg et au Canada, comme au Maroc, en Tunisie, en Algérie, au Sénégal et en Côte d’Ivoire. Le même guide existe 영어로 et, pour la Flandre, 네덜란드어로.

입력할 명령: 창에 따라 다름

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

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

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

처음 세 줄은 Anthropic이 권장하는 네이티브 버전을 설치합니다. 즉, ~/.local/bin(Windows에서는 %USERPROFILE%\.local\bin)에 저장되는 독립 실행형 바이너리이며 백그라운드에서 업데이트를 다운로드하고 다음 시작 시 적용합니다. 설치가 완료되면 터미널을 닫고 새 터미널을 여세요. 설치에 사용한 터미널에는 아직 새 PATH가 반영되지 않았기 때문입니다.

Windows에서는 잘못된 창을 사용하는 것이 가장 흔한 실패 원인이며 오류 메시지에도 명확히 표시됩니다. The token '&&' is not a valid statement separator는 CMD 줄을 PowerShell에 붙여 넣었다는 뜻입니다. 'irm' is not recognized as an internal or external command는 그 반대입니다. 프랑스어 Windows에서는 두 번째 메시지가 번역되어 표시될 수 있지만 원인은 같습니다. 그 밖의 메시지는 가이드 끝의 오류 표에 정리되어 있습니다.

시스템 요구 사항

Windows: 오래된 튜토리얼의 내용과 현재 사실

Une bonne partie des tutoriels en français datent des premières versions de Claude Code. Voici leurs consignes les plus répandues, confrontées à la 현재 설치 문서 et à la 문제 해결 페이지 (lues le 2026년 10월 3일) :

Si vous installez Git for Windows, Claude Code passe par Git Bash et garde l’outil PowerShell à côté. Il arrive qu’il ne trouve pas bash.exe : indiquez alors son chemin dans la variable CLAUDE_CODE_GIT_BASH_PATH, au sein du bloc env de ~/.claude/settings.json (la documentation donne C:\Program Files\Git\bin\bash.exe en exemple). Dernier piège : le raccourci « Windows PowerShell (x86) » lance une version 32 bits, que Claude Code refuse.

네이티브 설치와 WSL 중 무엇을 선택할지는 프로젝트가 위치한 곳에 따라 결정합니다.

WSL 쪽에서는 모든 작업이 Linux 배포판 내부에서 이루어집니다. curl … | bash 줄을 붙여 넣는 곳도 여기이고, 이후 claude를 입력하는 곳도 여기입니다. PowerShell 또는 CMD에서 실행하면 이 설치를 볼 수 없습니다.

Homebrew, WinGet, apt 또는 npm

패키지 관리자는 작동하지만 한 가지 대가가 있습니다. Claude Code가 자동으로 업데이트되지 않습니다. Homebrew와 WinGet의 경우 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 변수가 Claude Code를 통해 직접 업데이트하도록 합니다. 이 변수가 없으면 직접 업데이트해야 합니다.

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # pas de mise à jour automatique

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # pas de mise à jour automatique

Sur Debian, Ubuntu, Fedora, RHEL et Alpine, Anthropic publie aussi des dépôts apt, dnf et apk signés, mis à jour avec le reste du système ; la procédure figure sur la 설치 페이지.

Node.js가 이미 도구 체인의 일부라면 npm도 편리합니다. 이 패키지는 최소 Node.js 22를 요구합니다. 더 오래된 버전에서는 npm이 EBADENGINE 경고만 표시하고 계속 진행합니다. 패키지가 실행에 Node.js가 필요 없는 동일한 네이티브 바이너리를 설치하기 때문입니다. 규칙은 두 가지입니다. sudo npm install -g는 사용하지 말 것, 그리고 @latest로 업데이트할 것. npm update -g는 원래 버전 범위 안에 머물러 뒤처질 수 있습니다.

node -v                                       # v22 ou plus récent
npm install -g @anthropic-ai/claude-code      # jamais avec sudo

# mise à jour : avec @latest, pas avec npm update -g
npm install -g @anthropic-ai/claude-code@latest

설치 확인 및 PATH 수정

claude --version   # affiche le numéro de version, suivi de (Claude Code)
claude doctor      # diagnostic de l’installation et des réglages, sans ouvrir de session

버전 번호가 반환되면 설치가 완료된 것입니다. claude doctor는 세션을 시작하지 않고 더 많은 항목을 확인합니다. 설치 상태, 설정 파일의 오류, 마지막 업데이트 결과를 확인합니다. 문제가 생기면 가장 먼저 실행할 명령입니다.

command not found: claude sur macOS ou Linux, claude « non reconnu » sous Windows : le programme est bien installé, mais le shell ne sait pas où le chercher. Une nouvelle fenêtre suffit le plus souvent. Sinon, ajoutez ~/.local/bin au PATH dans ~/.zshrc ou ~/.bashrc. Sous Windows, la 공식 문제 해결 페이지 donne ces trois étapes PowerShell :

# 1. Le dossier d'installation est-il déjà dans le PATH ?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Aucun résultat ? Ajoutez-le au PATH de l'utilisateur, puis ouvrez une nouvelle fenêtre
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Dans la nouvelle fenêtre : deux chemins = deux installations concurrentes
where.exe claude

npm으로 설치했는데 PowerShell에서 npm.ps1 cannot be loaded이라고 응답하나요? 실행 정책이 npm 스크립트를 차단하고 있는 것입니다. 네이티브 설치 프로그램으로 전환하거나, 본인 계정에 한해 로컬 스크립트를 허용하세요.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

요청 비용 부담 주체: Claude 구독 또는 API 키

선택은 설치 시가 아니라 첫 실행 시 이루어지며, 나중에 되돌릴 수 있습니다. 환경에 설정된 키가 저장된 claude.ai 연결보다 우선하고, 해당 연결은 대기 상태로 남습니다. 변수를 삭제하면 다음 실행부터 연결이 다시 사용됩니다.

Claude 구독 사용

구성할 것은 없습니다. 프로젝트 폴더에서 claude를 실행한 다음 브라우저에서 연결하면 됩니다. 예외는 환경에 남아 있는 ANTHROPIC_API_KEY입니다. 이 경우 Claude Code가 한 번 사용 여부를 묻습니다. 거부하면 선택이 저장되고, 이후 키는 메시지 없이 무시되므로 변수가 읽히지 않는 것처럼 보일 수 있습니다. 이 선택을 변경하려면 /config → Use custom API key를 선택하세요.

구독 없음: Kunavo API 키

Faire pointer Claude Code ailleurs que chez Anthropic n’a rien d’un bricolage. La 공식 환경 변수 목록 présente ANTHROPIC_BASE_URL comme le moyen d’envoyer les requêtes vers un proxy ou une passerelle. Kunavo répond au format de l’API Messages d’Anthropic : vous gardez le Claude Code officiel, sans extension ni version modifiée.

1. 계정을 만드세요: Kunavo 가입.
2. Billing에서 잔액을 충전하세요. 최소 $10입니다. (결제 수단은 아래에 설명합니다.)
3. /app/keys에서 키를 생성하세요. 키는 sk-kn-로 시작하며 생성할 때만 표시됩니다. 즉시 복사하세요.
4. 아래의 6개 변수를 입력하세요.

Pourquoi épingler quatre modèles ? Les alias de Claude Code suivent les sorties d’Anthropic. D’après la 모델 구성 문서 (lue le 2026년 10월 3일), pour un compte API, le réglage par défaut et opus visent aujourd’hui Opus 5.5, et sonnet vise Sonnet 5.5, que Kunavo ne sert pas : sans ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la phase d’exécution d’opusplan et les sous-agents réglés sur sonnet tombent sur une 404. L’alias opus est épinglé sur Opus 5.5 (claude-opus-5-5), qui exige Claude Code v2.1.280 ou plus récent ; sur une version plus ancienne, lancez claude update. Un modèle tout juste sorti n’est pas non plus toujours disponible chez Kunavo le jour même. Avec des noms complets, chaque requête part vers un modèle servi, au prix que vous connaissez. La 게이트웨이 프로토콜 문서 (lue le 2026년 10월 3일) confirme le point sur les tâches de fond : avec Claude Haiku 4.5, elles coûtent peu.

변수를 입력할 위치

파일에 기존 내용이 있다면 기존 내용과 병합할 권장 버전입니다. 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"
  }
}

macOS와 Linux의 셸에서도 동일한 값입니다.

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # le domaine seul, sans /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

PowerShell 창에서 빠르게 테스트하려면:

# Valable uniquement dans cette fenêtre 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

VS Code 확장의 경우 편집기 사용자 설정에서 다음 명령을 실행하세요: Preferences: Open User 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" }
  ]
}

Claude 데스크톱 앱은 예외입니다. ANTHROPIC_BASE_URL도 settings.json도 읽지 않습니다. 셸에서 변경한 변수가 효과가 없나요? 우선순위가 높은 settings.json에서 같은 변수를 먼저 확인하세요.

Tarifs par million de tokens tirés du catalogue Kunavo, à côté du prix public d’Anthropic relevé sur claude.com/pricing (lu le 2026년 10월 3일) :

작업 중 잠시 Opus로 전환하려면 세션 중 /model opus를 사용하세요(claude-opus-5-5에 고정된 별칭). 또는 시작 시 claude --model claude-opus-5-5를 사용하세요. 사용량에 따른 월 예산과 구독이 더 유리해지는 기준은 Claude Code 가격에 계산되어 있습니다. Claude 토큰 비용 계산기는 본인의 사용량으로 계산하며, 가격 페이지에는 모든 모델이 나와 있습니다.

/status로 확인

/status보다 먼저 확인할 수 있는 첫 번째 징후입니다. ANTHROPIC_AUTH_TOKEN이 설정되어 있으면 Claude Code가 로그인 화면 없이 시작됩니다. 이 화면이 나타나면 키를 읽지 못한 것입니다. 대개 프로젝트 설정(.claude/settings.json 또는 .claude/settings.local.json)에만 키가 있기 때문입니다. 대화형 세션에서는 이 env 블록이 최초 실행 도우미와 폴더 신뢰 질문을 마친 후에만 적용됩니다. 키를 셸 또는 ~/.claude/settings.json로 옮기세요.

Une fois dans la session, /status s’ouvre sur l’onglet Status. Voici comment le lire, d’après la 게이트웨이 문서 (lue le 2026년 10월 3일) :

이미 구독으로 로그인한 상태였나요? 이 경우 Claude Code는 시작할 때 두 개의 활성 인증 소스를 감지했다고 경고할 수 있으며, 경고는 auth may not work as expected로 끝납니다. 요청에 사용되는 것은 키입니다. /logout을 실행하면 기존 연결이 삭제되고 경고가 사라집니다.

문제가 Kunavo에서 발생했는지 설정에서 발생했는지 확인하려면 Claude Code 없이 테스트하세요. 문서에는 출력 토큰 하나만 사용하는 제한된 요청이 있으며 비용은 1센트의 일부입니다. 아래 두 명령은 셸에서 주소와 키를 가져옵니다. 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)가 비활성화된 것으로 표시됩니다. 확인에는 claude.ai 연결 또는 Anthropic 키가 필요하며 단순 bearer 토큰으로는 확인할 수 없기 때문입니다.
• MCP 도구 검색은 기본적으로 꺼져 있습니다. ANTHROPIC_BASE_URL가 Anthropic 외부를 가리킬 때 적용됩니다.
• /context가 추정치를 표시합니다. Kunavo ne propose pas /v1/messages/count_tokens, et dans ce cas Claude Code compte à partir du nombre de caractères (게이트웨이 프로토콜 문서).

그 밖의 기능(코드 읽기 및 쓰기, 도구, 하위 에이전트, MCP 서버, 훅, 프롬프트 캐시)은 달라지지 않습니다. 영어로 된 기술 세부 정보는 Claude Code 통합 문서에 있습니다.

프랑스 또는 벨기에에서 결제

Deux circuits à ne pas confondre. L’abonnement Claude acheté sur le web se règle uniquement par carte de crédit ou de débit (Anthropic 청구 FAQ, lue le 2026년 10월 3일) ; souscrit dans l’app mobile, il passe par l’App Store ou Google Play. Les montants de claude.com/pricing sont hors taxes.

Le solde Kunavo, lui, se recharge sur une page de paiement Stripe. Le tarif est fixé en dollars américains, mais depuis la France ou la Belgique Stripe vous montre le montant en euros, à un taux garanti 24 heures qui intègre 2 à 4 % de frais de conversion à votre charge (Adaptive Pricing에 관한 Stripe 문서, lue le 2026년 10월 3일). Vous pouvez payer en dollars pour éviter ces frais, mais votre banque applique alors son propre change, et Bancontact n’est proposé qu’en euros. Les moyens de paiement disponibles :

• 프랑스 CB 카드? Selon la Cartes Bancaires에 관한 Stripe 문서 (lue le 2026년 10월 3일), plus de 95 % des cartes CB sont co-badgées Visa ou Mastercard. Elles passent donc au checkout en tant que Visa ou Mastercard, et une simple carte de débit fait l’affaire.
• Bancontact est proposé aux acheteurs situés en Belgique. Stripe vous envoie sur le site ou l’app Bancontact pour valider, et le résultat est connu immédiatement (Bancontact에 관한 Stripe 문서, lue le 2026년 10월 3일).
• Pay by Bank, le paiement depuis votre banque en ligne, n’est pas proposé depuis la France ni la Belgique : le checkout ne l’affiche qu’aux acheteurs situés au Royaume-Uni, en Irlande et en Finlande. La Pay by Bank에 관한 Stripe 문서 (lue le 2026년 10월 3일) le classe en préversion privée pour la France et ne mentionne pas la Belgique.
• 스위스 또는 캐나다에서는 금액이 스위스 프랑 또는 캐나다 달러로 표시됩니다. 카드와 Link를 사용할 수 있으며, 카드에 연결된 Apple Pay와 Google Pay도 사용할 수 있습니다.

제공되지 않음: PayPal, SEPA 자동이체, Klarna. Klarna는 미국에 있는 구매자에게만 제공됩니다. 달러로 결제하는 것만으로는 충분하지 않습니다.

1. Kunavo에 가입하세요. 이 단계에서는 카드를 요구하지 않습니다.
2. Billing에서 금액을 선택하세요. 최소 $10입니다. 더 높은 금액에는 보너스가 제공됩니다($100 payés, $110 crédités ; $1 000 payés, $1 200 crédités ; $5 000 payés, $6 250 crédités).
3. Stripe 페이지에서 결제 수단을 선택하세요. 유로 금액은 승인 전에 표시됩니다. Bancontact를 사용하는 경우 앱 또는 카드로 확인하세요.
4. /app/keys에서 키를 생성하고 ANTHROPIC_AUTH_TOKEN에 입력하세요.

잔액은 선불 방식입니다. 월별 요금과 만료일이 없으며 실패한 요청에는 요금이 부과되지 않습니다. 자동 충전에는 등록된 카드 또는 Link가 필요합니다. Bancontact는 Stripe에서 반복 결제를 지원하지 않으므로 Bancontact 충전은 매번 수동으로 시작해야 합니다. Kunavo는 프랑스, 벨기에 또는 다른 국가의 VAT 청구서를 발행하지 않습니다. 충전 내역은 Billing에서 확인할 수 있습니다. 또한 이러한 결제 수단은 Kunavo API 잔액에만 사용되며 Claude Pro 또는 Max 구독 결제에는 사용할 수 없습니다. App Store와 Google Play를 포함한 다른 모든 방법은 은행 카드 없이 Claude 결제하기에서 검토합니다.

일반적인 오류

프로젝트 시작하기

Claude Code가 처음 탐색하는 저장소에서는 /init부터 시작하세요. 코드를 살펴보고 테스트 명령과 발견한 규칙을 기록한 CLAUDE.md를 작성합니다. 이 파일은 매 세션마다 다시 로드되므로 검토하고 불필요한 내용을 삭제하세요. 주제를 바꾸려면 /clear로 빈 대화를 시작하고, 긴 작업을 계속하려면 /compact로 기록을 요약하세요.

API 키의 한계

• Claude Pro 또는 Max 요금제가 아니라 사용량에 따라 지불합니다. 매일 여러 시간씩 Claude Code를 사용한다면 구독이 더 유리한 경우가 많습니다. 간헐적으로 사용한다면 토큰 단위 결제가 더 유연하며, 사용량이 적은 달에는 비용이 들지 않습니다. 수치는 Claude Code 가격에서 확인하세요.
• 키가 활성화된 동안 Remote Control과 음성 받아쓰기를 사용할 수 없습니다.
• Kunavo의 용량은 공유되며 예약 할당량이나 계약상 약정이 없습니다. 필요하다면 Anthropic과 직접 계약하세요.
• Bancontact는 수동 충전만 지원합니다. 자동 충전은 등록된 카드 또는 Link를 사용합니다.
• 유로 금액에는 Stripe의 환전 수수료가 포함되며 Kunavo는 VAT 청구서를 발행하지 않습니다.

자주 묻는 질문