Installing Claude Code takes one command; the real obstacles come afterward. Most installation guides stop at “installation complete,” but in South Korea, getting it running involves two more hurdles: global installation permissions and login and payment. This guide walks through all three steps in order and explains how to resolve the issue you may encounter at each one.
Step 1 — Install (one command)
The only prerequisite is Node.js 18 or later. macOS, Windows (WSL), and Linux all use the same command.
# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version
# 설치
npm install -g @anthropic-ai/claude-code
# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --versionclaude --versionIf it prints this version, installation is complete. If you’re stuck here, see one of the next two sections.
Step 2 — Permission and path errors
These are the two most common errors during installation.
| Symptom | Cause and resolution |
|---|---|
EACCES Permission error | No write permission for npm’s global directory — move the global path into your home directory |
command not found: claude | npm’s global bin directory isn’t on PATH — add it to PATH, then open a new terminal |
We don’t recommend adding EACCES to sudo. It may install successfully for now, but the same issue will recur with every update, and the global directory will be owned by root, making things more complicated. Moving the path into your home directory is cleaner.
# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrcOn Windows, install it inside WSL. The project files must also be in the WSL file system for file watching and path handling to work correctly.
Step 3 — Login and payment (the real stumbling block in South Korea)
After installation, run claude and you’ll be asked to log in. This is where most users in South Korea get stuck, and the cause is unrelated to installation.
- Cards with overseas payments blocked — subscription payments fail. Enabling overseas payments in your card issuer’s app or website resolves the issue in most cases.
- KakaoPay and Toss — these aren’t supported for claude.ai web payments (they’re only available as store payment methods for mobile app subscriptions). If you expect to pay with a local digital wallet, you’ll get stuck here.
- If you do not have a card that supports international payments — you cannot use the web subscription route. The key-based route below uses a topped-up Kunavo balance; when checkout is displayed in Korean won, KakaoPay, Naver Pay, PAYCO, Samsung Pay, and domestic cards (with international payments disabled) are offered as payment methods, so you can top up without a card that supports international payments (Toss is not supported).
For a summary of which payment methods work and which don’t, see Claude payment methods.
When subscription payment is blocked — run it with a key without reinstalling
In addition to subscription login, Claude Code supports API key authentication. If the two environment variables below are set, Claude Code runs without showing the login screen. Remove the variables to switch back. No reinstallation is needed.
# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# 클로드 코드의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 따라가므로,
# Kunavo가 제공하는 모델로 고정해 404를 막습니다. sonnet 별칭은 Kunavo가 제공하지
# 않는 Sonnet 5.5를 요청하므로, 고정하지 않으면 /model sonnet, opusplan의 실행 단계,
# sonnet 서브에이전트가 404로 실패합니다. opus는 Opus 5.5로 고정하며,
# 클로드 코드 v2.1.280 이상이 필요합니다(이전 버전은 claude update).
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
claudeWith this option, you’re charged for the tokens you use instead of a monthly fee, so there’s no cost in months when you don’t work. See How to get a Claude API key for instructions on getting a key, and Claude Code pricing to compare the cost of a subscription with pay-as-you-go.
First run after installation — a 3-minute check
Once it’s running, launch claude from your project directory and run /init once. It reads your repository and creates CLAUDE.md, which is automatically read in every subsequent session. The workflow from here—writing rules, configuring permissions, and adding custom commands—is covered in How to use Claude Code.
Errors that occur after Claude Code is running (401, 429, and 529) have completely different causes from installation issues. See Claude Code error guide for how to tell them apart.
Frequently asked questions
How do I install Claude Code?
Install it globally with a single npm command. Run npm install -g @anthropic-ai/claude-code, then verify with claude --version. The only prerequisite is Node.js 18 or later, and the same command works on macOS, Windows, and Linux. On Windows, installing inside WSL tends to avoid problems.
Installation completed, but it won’t run. What should I check?
First, check whether `claude --version` prints a version. If it does, installation is complete and the remaining issue is authentication. If you get a “command not found” error, npm’s global path is missing from PATH. Add the `bin` directory under the path returned by `npm config get prefix` to PATH, then reopen your terminal.
I get an EACCES permission error during installation.
This means you don’t have permission to write to npm’s global directory. Installing with sudo may work for now, but it can cause recurring permission issues, so it’s not recommended. A safer approach is to move the global path into your home directory with `npm config set prefix ~/.npm-global` and add it to PATH.
Payment fails during login after installation.
This is the point where users in Korea most often get blocked. Cards with international payments disabled fail for subscription payments; enabling international payments in the card issuer's app or website resolves the issue in most cases. KakaoPay and Toss are not supported for web payments on claude.ai and appear only in the Korean payment-method lists for App Store and Google Play mobile subscriptions. If you need to work around payment restrictions, you can authenticate with an API key instead of using a subscription. On this route, Kunavo balance top-ups offer KakaoPay, Naver Pay, PAYCO, Samsung Pay, and domestic cards as payment methods when checkout is displayed in Korean won (Toss is not supported).
Can I use Claude Code without a subscription?
Yes. Claude Code supports API key authentication as an alternative to signing in with a subscription, so you can run it without logging in by setting the two environment variables ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN. In this case, you’re charged for the tokens you use instead of a monthly fee, and there’s no cost in months when you don’t use it.
How do I install it on Windows?
We recommend installing it inside WSL (Windows Subsystem for Linux). Install Node.js 18 or later in a WSL terminal, then run the same npm command. The project you’re working on must also be in the WSL file system for file watching and path handling to work correctly.