Claude Code 설치 방법【Windows・Mac】— 구독 없이 API key 구성 및 JCB・Apple Pay 결제

Claude Code 설치는 공식 네이티브 설치 프로그램을 한 줄 실행하는 것만으로 완료됩니다. Mac·Linux·WSL은 install.sh, Windows는 PowerShell에서 install.ps1, CMD에서 install.cmd를 사용합니다(npm으로도 설치할 수 있지만 이 경우 Node.js 22 이상이 필요함). 일반적으로 그 후 Pro·Max 등의 요금제로 로그인하지만 구독하지 않는 경우 ANTHROPIC_BASE_URL=https://api.kunavo.com(/v1는 추가하지 않음), API 키가 포함된 ANTHROPIC_AUTH_TOKEN 및 모델을 고정하는 네 가지 변수를 설정하면 로그인 없이 시작할 수 있습니다. 작동 여부는 /status로 확인합니다. API 잔액은 JCB 등의 카드, Apple Pay, Google Pay 및 Link로 $10부터 선불 충전할 수 있으며 결제 화면은 엔화로 표시됩니다.

# 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 の公式ドキュメント（설정、설치 문제 해결、2026년 10월 3일確認）です。このページはその内容をなぞるのではなく、日本語の解説記事で食い違っている点（Node.js のバージョン、Windows の管理者権限と Git）と、公式ドキュメントが扱っていないこと——ログインせずに API キーで動かす設定と、日本からの支払い——を中心にまとめています。料金と決済手段は 2026년 10월 3일時点の情報です。日本は Anthropic の지원 국가 목록に、Claude.ai と API の両方で載っています（2026년 10월 3일確認）。

먼저 결정할 사항: 구독으로 로그인할지, API 키로 실행할지

설치 자체는 어느 쪽이든 동일하며, 차이는 최초 실행 후에 있습니다. Claude Code를 시작하면 인증을 요청합니다. 망설여진다면 다음 3가지로 판단할 수 있습니다.

• 이미 Pro·Max·Team·Enterprise를 구독 중이거나 Console 계정이 있음: 그대로 로그인하면 사용할 수 있습니다. 이 페이지의 API 키 설정은 필요하지 않습니다. 무료 플랜에는 Claude Code가 포함되지 않습니다.
• 매월 정액을 지불하고 싶지 않거나, 사용하는 달과 사용하지 않는 달의 차이가 큼：API キーで動かし、使ったトークン分だけ払う形が合います。参考までに、Claude のサブスクは Pro が月 $20（年払いは $200 で月 $17 相当）、Max は月 $100 からで、いずれも税別です（Claude 요금 페이지、2026년 10월 3일確認）。どちらが安くなるかの分岐点は Claude Code 요금で試算しています。
• Remote Control이나 음성 입력을 사용하고 싶음: 둘 다 claude.ai 계정이 필요하므로 API 키로는 사용할 수 없습니다. 로그인을 선택하세요.

支払い手段も違います。Anthropic の Web サイトで契約するサブスクはクレジットカードかデビットカードのみで、iPhone・Android アプリから契約した場合は App Store・Google Play が決済します（Anthropic 도움말、英語版、2026년 10월 3일確認）。Kunavo の API 残高は、JCB を含むカード、Apple Pay、Google Pay、Link でチャージします（詳しくは後半の支払いの章）。

설치 전 확인

조건은 공식 문서(2026년 10월 3일확인)에 나와 있는 대로입니다. 오른쪽 열은 직접 확인할 때의 방법입니다.

설치 방법

공식 문서에서 「권장」하는 방법은 네이티브 설치 프로그램입니다. 다른 방법과의 차이는 주로 업데이트 방식입니다.

# Homebrew（既定では自動更新されない）
brew install --cask claude-code

# WinGet（Windows・既定では自動更新されない）
winget install Anthropic.ClaudeCode

어떤 방법이든 완료되면 터미널을 다시 열고 확인합니다. 설치 전에 열어 둔 창은 새로운 PATH을 로드하지 않았을 수 있기 때문입니다. claude doctor는 세션을 시작하지 않고 설치 및 설정 상태만 표시하므로, 제대로 작동하지 않을 때 원인을 좁히는 데 사용할 수 있습니다.

claude --version   # 2.1.211 (Claude Code) のようなバージョン番号が出れば OK
claude doctor      # セッションを開かずに、インストールと設定を診断する

npm으로 설치할 때의 주의 사항

日本語の解説記事では今も「Node.js 18 以上」という記載をよく見かけますが、公式ドキュメントの要件はNode.js 22 이상です（공식 문서、2026년 10월 3일確認）。古い Node.js でも npm は EBADENGINE の警告を出すだけでインストールを止めず、claude も起動しますが、警告が出たら Node.js を上げておくほうが安全です。nvm や Volta などでバージョンを切り替えている場合は、インストールするシェルで node -v を確かめてください。

node -v                                    # v22 以上であること
npm install -g @anthropic-ai/claude-code   # sudo は付けない

# 更新は @latest で（npm update -g は使わない）
npm install -g @anthropic-ai/claude-code@latest

공식 문서에는 sudo npm install -g를 사용하지 말라고 명시되어 있습니다. 또한 본체 바이너리는 선택적 종속성으로 설치되므로, --omit=optional 또는 .npmrc의 optional=false로 선택적 종속성을 생략하면 Mac·Linux에서는 claude native binary not installed가 표시되며 시작되지 않습니다.

Windows에 설치할 때의 요점

まず、ネットでよく見る 2 つの手順は不要です。「PowerShell を管理者として実行」と「Git for Windows を先に入れる」は、どちらも公式ドキュメントの要件ではありません。관리자 권한은 필요하지 않으며, Git for Windows는 선택 사항입니다で、入っていなければ Claude Code は PowerShell でコマンドを実行します（Windows 설정、2026년 10월 3일確認）。

그런 다음 명령을 붙여넣기 전에 두 가지만 확인하세요.

1. 현재 열려 있는 것이 PowerShell인지 CMD인지 확인합니다. 프롬프트가 PS C:\Users\ユーザー名>이면 PowerShell용 irm 행을, PS가 붙지 않은 C:\Users\ユーザー名>이면 CMD용 install.cmd 행을 사용합니다. 잘못 선택하면 PowerShell에서는 &&가 구분 기호로 인식되지 않는다는 오류가, CMD에서는 irm가 인식되지 않는다는 오류가 발생합니다(일본어 표시 Windows에서는 메시지가 일본어로 표시될 수 있습니다).
2. 「Windows PowerShell (x86)」를 열고 있지 않은지 확인합니다. 시작 메뉴에 표시되는 (x86) 버전은 32비트 프로세스이므로 64비트 컴퓨터에서도 Claude Code does not support 32-bit Windows에서 중지됩니다.

Windows에서 실행하는 방법은 3가지입니다. 망설여진다면 네이티브 방식으로 시작해도 됩니다.

Git for Windows를 설치했는데 Claude Code가 Git Bash를 찾지 못하는 경우, 사용자 설정 파일의 env에서 CLAUDE_CODE_GIT_BASH_PATH에 bash.exe의 위치를 지정합니다.

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

설치했는데 claude가 작동하지 않을 때

'claude' is not recognized(Mac·Linux에서는 command not found: claude)는 설치 위치가 PATH에 포함되지 않은 상태입니다. 네이티브 설치 프로그램의 위치는 Windows에서는 %USERPROFILE%\.local\bin\claude.exe, Mac·Linux에서는 ~/.local/bin/claude입니다. 터미널을 다시 열어도 해결되지 않으면 공식 문서의 절차에 따라 PowerShell에서 확인하고 추가합니다.

# 1. インストール先が PATH に入っているか確認する
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 何も出なければユーザーの PATH に追加し、ターミナルを開き直す
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 新しいターミナルで
claude --version

npm で入れた場合に npm.ps1 cannot be loaded because running scripts is disabled on this system （起動時なら claude.ps1）と出るのは、PowerShell の実行ポリシーが npm の .ps1 スクリプトを止めているためです（공식 문서、2026년 10월 3일確認）。現在のユーザーにだけローカルのスクリプト実行を許可する次のコマンドで解消します。ポリシーを変えたくなければ、npm.cmd・claude.cmd を使うか、PowerShell 用のネイティブインストーラーに切り替えてください。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

로그인하지 않고 API 키로 실행하도록 설정

Kunavo는 Anthropic이 아니라 Claude 등의 모델에 대한 API 액세스를 선불로 제공하는 독립적인 API 게이트웨이입니다.Claude Code には送信先を差し替える ANTHROPIC_BASE_URL という変数が公式に用意されていて、公式ドキュメントにも「Claude Code를 LLM 게이트웨이에 연결」というページがあります。プラグインや改造版は使いません。この変数が変えるのは送信先だけで、どのモデルが答えるかは別の変数で決まります（모델 설정、2026년 10월 3일確認）。

설정할 항목은 다음 6가지입니다.

Mac·Linux에서는 셸 설정 파일(~/.zshrc 또는 ~/.bashrc)에 추가한 뒤 터미널을 다시 엽니다.

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # ドメインだけ。/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 창에서 다음을 실행합니다. 창을 닫으면 사라집니다.

# このウィンドウの中だけで有効（閉じると消える）
$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에 작성합니다. 모든 프로젝트에 적용되며 Mac과 Windows에서 같은 방식으로 설정할 수 있습니다. 다른 설정이 이미 있는 파일이라면 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"
  }
}

저장 위치에 관해 세 가지 주의 사항이 있습니다.

• プロジェクトの .claude/settings.json には키를 작성하지 않음でください。リポジトリにコミットされ、クローンした人全員に渡ります（공식 문서）。
• 셸과 설정 파일 양쪽에 같은 변수가 있으면 설정 파일의 값이 사용됩니다. export를 다시 해도 바뀌지 않는다면 설정 파일을 확인하세요.
• VS Code 확장 기능에서 사용할 때는 VS Code 사용자 설정의 claudeCode.environmentVariables에 같은 변수를 입력합니다.

ANTHROPIC_AUTH_TOKEN을 사용하는 이유

ANTHROPIC_AUTH_TOKEN는 Authorization: Bearer 헤더로 전송되며 설정한 즉시 활성화됩니다. 반면 ANTHROPIC_API_KEY는 x-api-key 헤더로 전송되고, 대화형 모드에서는 처음 한 번 사용해도 되는지 승인을 요청합니다. 여기서 거부하면 이후 아무것도 표시되지 않은 채 키가 무시되며, /config의 Use custom API key에서 다시 활성화할 때까지 사용할 수 없습니다. Kunavo는 두 헤더로 전송된 키를 모두 허용하므로 ANTHROPIC_API_KEY에서도 작동하지만, 이러한 문제가 없는 ANTHROPIC_AUTH_TOKEN가 더 확실합니다. 공식 문서도 키 유형이 지정되지 않은 경우 ANTHROPIC_AUTH_TOKEN를 사용하도록 안내합니다.

모델을 고정하는 이유(2026년 10월 3일 시점)

공식 문서（2026년 10월 3일確認）によると、API キーで使う場合、既定モデルと opus エイリアスは Opus 5.5、sonnet エイリアスは Sonnet 5.5 を指します。エイリアスの行き先は新しいモデルが出るたびに変わりますが、Kunavo で同じ日から使えるとは限りません。実際、Kunavo は 2026년 10월 3일時点で Sonnet 5.5 を提供していないので、固定せずに /model sonnet を選ぶと 404 になります。opusplan の実行フェーズや、model: sonnet を指定したサブエージェントも同じです。そのため上の設定では ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 で sonnet エイリアスも固定しています。opus エイリアスも、行き先が次の Opus に変わっても困らないよう ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5 で Claude Opus 5.5 に固定しています。Claude Opus 5.5 には Claude Code v2.1.280 以降が必要なので、古い場合は claude update で更新してください。

固定しておくと、費用の見通しも立てやすくなります。何も指定しないと既定モデルが Claude Opus 5.5 になり、Claude Sonnet 5 をメインにした場合より 1 トークンあたりの単価が上がります。Kunavo の単価（1M トークンあたり、入力 / 出力）は、Claude Haiku 4.5 が $0.70 / $3.50、Claude Sonnet 5 が $1.40 / $7.00(Anthropic 가격은 $2.00 / $10.00)、Claude Opus 5.5 が $2.80 / $14.00 です。ANTHROPIC_DEFAULT_HAIKU_MODEL を設定しないと、ANTHROPIC_AUTH_TOKEN で接続したセッションでは claude --resume 用の会話要約などのバックグラウンド処理もメインのモデルで動きます（게이트웨이 호환성 가이드、2026년 10월 3일確認）。なお Anthropic の요금 페이지では、メインに固定している Sonnet 5 は「レガシーモデル」の欄に移っています（2026년 10월 3일確認）。

3단계로 작동 확인

1. 시작하기 전에 URL과 키만 테스트

공식 문서와 동일한 출력 1토큰 요청입니다(잔액에서 아주 조금 차감됩니다). 셸 변수를 읽으므로 키를 설정 파일에만 작성한 경우 이 터미널에서 export한 후 실행합니다. {"id":"msg_로 시작하는 JSON과 200가 반환되면 URL과 키가 모두 정상이고, 401이면 키가 거부된 것입니다.

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_로 시작하면 성공입니다.

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

2. claude를 시작하고 로그인 화면이 표시되지 않는지 확인

처음에는 최초 실행 마법사와 폴더 신뢰 확인이 표시되지만, 그 후 브라우저 로그인을 요청하지 않습니다. 로그인을 요청한다면 키가 전달되지 않은 것입니다.

흔한 원인은 프로젝트의 .claude/settings.json 또는 .claude/settings.local.json에만 키를 작성한 경우입니다. 대화형 세션에서는 프로젝트 설정의 env가 마법사와 폴더 신뢰 확인이 끝난 후 로드되므로 최초 실행 시점에는 키가 없는 것으로 처리됩니다. 셸의 export 또는 사용자의 ~/.claude/settings.json로 옮기세요.

3. /status의 두 줄 확인

セッションの中で /status を実行し、Status タブを確認します（공식 문서、2026년 10월 3일確認）。

• Anthropic base URL에 https://api.kunavo.com가 표시되는지 확인합니다. 이 줄은 게이트웨이를 설정했을 때만 나타나므로 줄 자체가 없다면 ANTHROPIC_BASE_URL가 세션에 전달되지 않은 것입니다.
• Auth token에 ANTHROPIC_AUTH_TOKEN이라고 표시되는지 확인합니다. 대신 claude.ai 계정의 Login method가 표시된다면 저장된 로그인으로 실행 중입니다.

API 키로 실행할 때 달라지는 점

• Remote Control과 음성 입력은 사용할 수 없습니다. 둘 다 claude.ai ID를 전제로 하므로 ANTHROPIC_AUTH_TOKEN 등의 게이트웨이 인증 정보가 유효한 동안에는 비활성화됩니다. v2.1.196 이상에서는 ANTHROPIC_BASE_URL가 Anthropic 이외의 호스트를 가리키기만 해도 Remote Control이 비활성화됩니다.
• /fast는 비활성화되었다고 표시됩니다. 베어러 토큰만으로 인증하면 Claude Code는 고속 모드 사용 가능 여부를 확인하지 않고 비활성화된 것으로 처리하여 Fast mode has been disabled by your organization라고 표시합니다.
• /context의 수치는 대략적인 값입니다.Kunavo は /v1/messages/count_tokens を提供していないため、Claude Code は文字数ベースの推定に切り替えます（게이트웨이 호환성 가이드、2026년 10월 3일確認）。

Kunavo 측의 자세한 설정은 Claude Code 연동 문서와 ANTHROPIC_BASE_URL 문서(둘 다 영어)에 있습니다.

API 잔액 결제: JCB·Apple Pay·Google Pay·Link

일본에서 결제할 때 자주 묻는 내용을 먼저 정리합니다.

절차는 4단계입니다. 먼저 Kunavo에 가입합니다(이메일 주소 또는 Google 계정. 가입 시 카드 정보는 요구되지 않습니다). 다음으로 대시보드의 Billing에서 충전 금액을 선택합니다. 최소 $10이며 월정액은 없고 큰 금액에는 보너스가 붙습니다($100 で残高 $110、$1,000 で残高 $1,200、$5,000 で残高 $6,250). Stripe 결제 화면에서 위 방법 중 하나를 선택해 결제한 후, 마지막으로 API Keys에서 sk-kn- 키를 만들고 ANTHROPIC_AUTH_TOKEN에 입력합니다. 키는 생성 시 한 번만 표시되므로 그 자리에서 복사하세요.

잔액에는 유효 기간이 없으며 실패한 요청에는 요금이 부과되지 않습니다. 일본에서 Claude 구독을 결제할 때 사용할 수 있는 방법(App Store·Google Play 경유 포함)은 출처와 함께 Claude 결제 방법에 정리했습니다.

비용 예시(계산)

API 키로 실행하는 Claude Code는 토큰 종량제입니다. Claude Code는 요청마다 대화의 문맥을 모두 전송하지만, 이전 요청과 동일한 앞부분은 캐시 읽기 단가가 적용될 수 있습니다. 아래 표는 요청 1회의 입력을 40,000 토큰(그중 36,000 = 90%가 캐시 읽기, 나머지 4,000가 캐시 쓰기), 출력을 1,000 토큰으로 하고, 한 작업을 50 요청으로 가정한 계산입니다. 백그라운드의 Claude Haiku 4.5 호출은 포함하지 않습니다. Kunavo의 캐시 단가는 Claude Sonnet 5의 경우 읽기가 입력 단가의 10%, 쓰기가 1.25배입니다(표의 각 모델은 해당 비율로 계산). 실제 측정값도 상한도 아닙니다.

실제 금액은 문맥 길이, 캐시 적용 방식, 응답 길이, 작업마다 /clear할지 여부에 따라 달라집니다. 모든 모델의 단가는 요금 페이지, 자신의 사용 방식에 따른 예상 금액은 Claude 토큰 요금 계산기(영어), 모델별 API 단가는 Claude API 요금에서 확인할 수 있습니다.

일반적인 오류와 해결 방법

이 방법이 적합하지 않은 경우

• 경비 정산에 적격 청구서가 필수인 경우. Kunavo 결제에서는 청구서도 등록번호가 기재된 적격 청구서도 발행되지 않습니다.
• 편의점 결제나 PayPay로 결제하고 싶은 경우. 둘 다 지원하지 않으며, 은행 송금과 통신사 결제도 지원하지 않습니다. 자동 충전은 저장한 카드 또는 Link만 사용할 수 있습니다.
• Remote Control이나 음성 입력을 사용하려는 경우. API 키로는 사용할 수 없으며 /fast도 비활성화되었다고 표시됩니다. 구독으로 로그인하세요.
• Sonnet 5.5를 사용하려는 경우. Kunavo는 2026년 10월 3일 시점에 이를 제공하지 않습니다.
• 일본어 문서만으로 설정을 완료하려는 경우. Claude Code 본체의 공식 문서는 일본어로 읽을 수 있지만 Kunavo의 연동 문서는 영어만 제공됩니다.

다음 단계

/status로 확인되면 작업할 프로젝트 디렉터리에서 claude를 시작하고, 먼저 /init로 CLAUDE.md를 만듭니다. CLAUDE.md에 무엇을 작성할지, 확인 대화 상자를 줄이는 방법, 사용자 지정 명령을 만드는 방법은 Claude Code 사용법에서 순서대로 설명합니다.

자주 묻는 질문